Give agents capabilities—and safe exits

Capability with accountability

A tool changes the world. A handoff changes who is responsible.

Keep both deliberate. Assign each real capability to the specialist that owns its business outcome. Create handoffs for recognizable topic changes—not as generic escape hatches. SmartSite adds enforced confirmation and duplicate protection around consequential actions, but safe design still begins with what admins choose to expose.

Understand the two layers of a flow tool

The normal Tools page defines the real capability: its function name, parameters, type, email recipient, webhook URL, static data, WordPress option, response messages, and enabled state. The Agent Flow Tool node connects that existing capability to one specialist and adds workflow-specific usage guidance and confirmation policy.

Configured once in Tools

SmartSite Tool

What the capability technically does, which data it accepts, where it sends data, and whether the source tool itself is enabled.

connected by

Configured inside one flow

Workflow Tool node

Which specialist may use it, when it is appropriate, whether additional confirmation is required, and whether this connection is enabled.

A workflow tool does not copy the underlying email or webhook configuration into an immutable independent service. It references an existing SmartSite Tool. Test and secure that source first using Agent Tools documentation, parameters, and action-tool guidance.

Every workflow Tool field

In a builder, select Add Tool. These are the fields in the Agent Capability form—not the larger form used to create the underlying SmartSite Tool.

Purpose and behavior
Field	Meaning	How to use it well
Name	The friendly node title administrators see.	Name the outcome in plain language: “Check Appointment,” “Send Quote Request,” or “Look Up Order.” Avoid generic names such as “API Tool.”
Key	A stable internal identifier for this workflow connection.	Use lowercase words separated by underscores, such as check_appointment. Keep it distinct and stable.
Description / Usage Guidance	The AI-facing rule explaining when and how the assigned specialist should use the capability.	Name the exact visitor intent, information required first, when not to call it, and what to do with success or failure. This field strongly influences tool choice.
Config JSON	Structured advanced settings for a Custom Instruction node.	Non-technical admins should leave the default empty object unless a developer or trusted guide provides exact content. It does not make a Custom Instruction executable.

Connection and safety
Field	Meaning	How to use it well
Assigned Agent	The specialist allowed to receive this tool in its runtime capability set.	Choose the one role accountable for the result. An enabled unassigned tool creates a Flow Check warning and is not a good live design.
Source	Existing SmartSite Tool connects a real capability. Custom Instruction creates a planning-only node.	Use Existing SmartSite Tool for live work. A Custom Instruction node must be disabled or replaced before publishing because it cannot execute.
Existing Tool	Selects the source capability already configured on the normal Tools page.	Choose an enabled, fully tested tool. Use Edit selected tool or Create new SmartSite tool when its parameters or endpoint need work.
Require confirmation	Adds explicit visitor approval to read-only or custom tools.	Enable when the lookup itself is sensitive, costly, privacy-relevant, or surprising. Email, non-GET webhook, and WordPress action tools are protected automatically even if this switch is off.
Enabled	Allows this connection to be included in the workflow.	Disable incomplete, unavailable, or temporarily withdrawn capabilities rather than deleting the design. Both the workflow node and source tool must be operational.
Sort Order	Controls admin ordering; lower numbers appear earlier.	Use for readability only. It does not force the model to choose one tool before another. Clear usage guidance controls the decision.

Write Usage Guidance as a decision rule

Specific enough to act safely

“Use this only when a visitor wants to submit a new appointment request. First collect name, contact method, service, preferred date or time, and any required note. Do not use it for general availability questions or to change an existing appointment. Before submission, summarize the exact details and wait for confirmation. After the tool result, distinguish ‘request received’ from ‘appointment confirmed.’”

Too broad to control

“Use this tool for appointments.”

Descriptions should align with the underlying tool parameters. If email is required by the tool, the guidance should tell the specialist to collect an email address before calling. Do not describe fields that the underlying tool cannot accept.

Confirmation is a runtime gate, not polite wording

Advanced Agents automatically protects:

Send Email tools;
Webhook tools using any method other than GET, normally POST;
WordPress Hook action tools.

The agent cannot silently bypass this protection. On the first attempt, the runtime stores the proposed action and exact arguments, then the assistant asks the visitor to reply with a clear confirmation or cancellation. If the visitor confirms, the stored action can be claimed and executed once. If details change, the changed arguments require a new confirmation. The same confirmed action is protected against duplicate execution.

1Collect required details

→

2Summarize exact action

→

3Visitor confirms

→

4Execute once

→

5Report actual result

The visitor can use direct replies such as “Confirm,” “Yes, please,” “Proceed,” or “Cancel.” A long or ambiguous message is not treated as approval. Instruct specialists to ask for a clear confirmation rather than burying consent inside another question.

The unsafe HTTP exception

An underlying Webhook Tool can enable Allow non-safe HTTP requests. This bypasses WordPress’s safer remote URL checks and may be necessary for a trusted Local/private-network endpoint during development. It also weakens protection against requests to internal or otherwise unsafe destinations.

Advanced Agents therefore reports an error such as:

Appointment lookup uses an unsafe webhook — Advanced Agents blocks this webhook because “Allow unsafe HTTP” bypasses WordPress URL safety checks. Turn that option off and use a public HTTPS endpoint.

This is the only Flow Check error that an admin may intentionally override at publication. Publish Changes opens a security dialog showing the same issue, with Cancel and Publish anyway. Do not ask me again stores a preference only for the current WordPress admin account. It does not remove the Flow Check, make the endpoint safe, or dismiss the warning for other admins.

Use the override only when all are true:

the endpoint and network are controlled and understood;
the risk is intentional, not a workaround for a typo or certificate failure;
the URL cannot be influenced by visitor input;
no unnecessary secret or personal data is transmitted;
the flow was tested in the exact target environment;
the decision is recorded in the Version note or team change record.

For an ordinary public integration, use a public HTTPS endpoint and leave unsafe HTTP off. All other readiness errors remain blocking.

Every Handoff field

A handoff is a directed connection: one owner may give the conversation to another when a condition matches. Open Add Handoff or select a line and choose Edit.

Handoff fields
Field	Meaning	Recommended practice
From	The current conversational owner allowed to initiate this route. Base Assistant and each specialist are valid actors.	Choose the role that can recognize the topic change. From Base creates an explicit workflow entry.
To	The actor that receives ownership. It may be a specialist or Base Assistant.	Send to the narrowest clearly responsible role. Use Base for general or unowned questions. From and To must differ.
Label	A short admin-facing name for the connection.	Name the visitor intent: “Book or change appointment,” not “Route A.” The label also helps traces remain readable.
Priority	Orders handoff rules; lower numbers are considered earlier.	Give narrow or urgent rules a lower number than broad rules. Leave gaps such as 10, 20, 30. Priority cannot rescue overlapping conditions.
Condition	The plain-language decision rule explaining when this movement is appropriate.	Include positive triggers, exclusions, and how clear the intent must be. Enabled conditions shorter than a useful sentence generate a warning.
Pass summary	Provides a short conversation summary to the receiving specialist.	Normally keep on so the visitor does not repeat details. Turn off only when context should deliberately not cross the boundary.
Enabled	Makes this connection available to the live workflow revision.	Disable while drafting or temporarily withdrawing a route. Publishing snapshots the current enabled state.

Condition patterns that reduce accidental movement

Use visitor language and distinguish nearby intents:

Use this handoff when the visitor wants to schedule, reschedule, or cancel an
appointment, or check a specific existing booking. Do not use it when the
visitor only asks what services are available, how long a service takes, or
where the clinic is located.

Use this handoff when the newest message is clearly about an invoice, receipt,
deposit, unexplained charge, or payment policy. Do not transfer a visitor who
merely mentions price while choosing a service; Base Assistant can answer
published general pricing questions.

Use this handoff when the visitor is clearly agitated, repeatedly frustrated,
or says they feel ignored or confused and needs a calm response. Do not use it
for ordinary negative feedback that the current specialist can address directly.

Avoid conditions such as “when necessary,” “when the other agent can help,” or “for support.” They give the model no distinctive decision boundary.

Pass Summary: continuity with a privacy decision

With Pass summary on, the receiving agent gets concise context so the visitor does not repeat an order number, preferred time, or previous explanation. That improves continuity. It also means relevant conversation details cross the specialist boundary.

Keep summaries on for normal transitions within the same public website workflow. Consider turning them off when a receiving role does not need prior sensitive detail, then design the recipient to ask only for the minimum required information. Regardless of the switch, avoid requesting secrets, passwords, full payment-card data, medical records, or identity documents in ordinary website chat.

Generated routes versus explicit handoffs

If a specialist has no Base-to-specialist handoff, SmartSite can generate an activation route from the specialist’s Description and Tool guidance. This keeps a draft usable, but Flow Checks warns that the activation is generated. Explicit Base entries are better for important production paths because an admin controls the condition and can review it separately.

Specialist scope can also support generated switching when routing policy permits. Explicit specialist-to-specialist handoffs remain available even if general direct switching is off. That makes them useful in structured workflows where only named transitions should occur.

Tool and handoff anti-patterns

Build this

One accountable specialist per action outcome.
Usage guidance that mirrors required parameters.
Explicit confirmation and an honest success/failure response.
Narrow handoff conditions with positive and negative examples.
A deliberate path back to Base or a human.

Avoid this

Every tool attached to every agent.
Custom Instruction nodes enabled as if they execute.
POST webhooks treated like harmless lookups.
“Do not ask again” interpreted as a global safety exemption.
Bidirectional handoffs with identical generic conditions.

Screenshot capture pending /images/screenshots/agentic-flows/tools-handoffs.webp

Tool and handoff configuration in the visual builder

Capture: Capture a synthetic Send Appointment Request tool assigned to Appointments, then capture its Appointments-to-Billing handoff in an adjacent panel.
Show: Tool source, existing tool, assignment, usage guidance, confirmation, enabled state, From, To, Condition, Priority, and Pass summary
Viewport: Desktop, 1440 × 1000
Annotate: Highlight the automatic action-safety note and the Condition field.
Redact: API keys, private URLs, personal data, real visitor messages, and production action details

The test before routing policy

For each enabled tool, test one correct use, one nearby use that should not call it, missing required data, corrected data, cancellation, confirmation, tool failure, and accidental repeated confirmation. For each handoff, test the positive condition, a close negative, a short follow-up that should stay with the current owner, and a genuine topic switch.

Then continue to routing controls to decide how much implicit switching the workflow allows. Complete end-to-end simulation and publication using Test, publish, observe, improve.