Tools & actions

Knowledge lets an agent answer. Tools let it act. A tool is a named capability the agent can decide to invoke mid-conversation — opening a ticket, sending a message, looking up a live order, cancelling a booking — and the difference between a helpful agent and a merely articulate one is usually a tool.

This page covers the agent's Tools tab, the nine tools that ship built in, how to build your own on top of a knowledge base, and the settings that decide what any of them may do.

Who can do this: workspace owners and admins.

The Tools tab #

Open the agent and choose Tools. The tab has two cards.

Built-in tools holds three switches:

Your own tools holds one switch, Let this agent take actions (Allowed or Blocked), and an Open Knowledge link, because your own tools live on knowledge bases. See Building your own tools and The tool policy.

Below them, What happens automatically and Safety policy describe behaviour you cannot switch off.

The voice-only tools (search_knowledge, end_call and schedule_callback) have no switch. They are offered on every call where they apply.

What a tool is #

To the model, a tool is a name, a description of when to use it, and a set of typed parameters. On each turn it may either answer or call a tool; if it calls one, the result comes back and it continues from there. The loop runs at most three rounds before the agent is forced to answer with what it has, so a tool that misbehaves cannot trap a customer in silence.

Three properties are worth internalising before you build anything:

• The description is the control surface. The agent decides whether to call a tool almost entirely from its description. "Check stock" invites speculative calls; "Use when the customer asks whether a specific product is currently available, after they have named the product" does not.
• A tool the agent cannot see cannot be called. Disabling a tool does not add a rule telling the model to avoid it — the tool is never declared, so it does not exist as far as the model is concerned. That is a much stronger guarantee than an instruction.
• Tool failures never surface as errors. If a tool throws or times out, the failure is handed back to the model as text and it recovers in conversation. A customer sees "I could not reach our order system right now" rather than a stack trace or an abrupt silence.

The built-in tools #

The platform supplies the following tools when their channel and policy make them relevant. These are their exact registered names — what the model sees, and what you will see in a transcript.

Create support tickets #

The Create support tickets switch turns on create_support_ticket. It creates a support ticket and resolves or creates the customer's contact record in one guarded action. It returns a status and the ticket's public reference — AM-4F91C2E0 — which the agent can read back to the customer.

When the agent reaches for it: when the customer asks for a human, asks for follow-up, asks to escalate, or has an unresolved problem that needs staff action. It is the mechanism behind every "let me get someone to look at this".

How identity is resolved, per channel — the agent never asks for information the channel already knows:

That voice behaviour is deliberate and worth understanding. Speech recognition is not reliable enough to transcribe an email address or a phone number correctly, so rather than accepting a plausible-looking wrong address, the fields are removed from the tool entirely. The caller ID is the identity.

Ticketing is idempotent within a conversation. A retry — the customer asking again, the model calling twice — returns the same ticket rather than opening a duplicate.

The agent is also instructed never to claim a ticket exists until the tool has actually returned success. If ticket creation fails, the customer is told it failed.

See Tickets for what happens next, and Escalate to a ticket for the end-to-end shape.

Send WhatsApp messages #

The Send WhatsApp messages switch turns on send_whatsapp_message. It puts a confirmation, a link, or a reference on the customer's phone — from any channel. A caller on the phone can be sent the booking reference by WhatsApp before they hang up. A web visitor can be sent the tracking link.

It is off by default, including for agents created before it existed.

On the Tools tab:

• The switch stays greyed out until the workspace has a WhatsApp number. The card says Connect a WhatsApp number before this agent can send. with a Set up WhatsApp link.
• With more than one number, Send from picks the sender. Workspace default uses the workspace's default number.
• Templates this agent may send lists your approved templates with their language and category. Tick the ones the agent may use. Templates still in review are counted underneath, for example One more template is in review with Meta — they appear here once approved.
• Allow messaging a different number is explained below.

Who it can message. By default, only the person the agent is already talking to. On WhatsApp itself, the customer's own WhatsApp ID is authoritative — if the model produces a different recipient, that recipient is ignored outright. There is one setting, Allow messaging a different number, that permits a model-chosen destination; it exists for cases like an order desk notifying a third party, and it is the one control that lets a customer's wording decide where a message goes. Leave it off unless you specifically need it.

Which templates it may send. You choose an explicit allowlist, up to 20 templates. That list becomes the set of values the template_name parameter will accept — the model literally cannot name a template you did not approve. If no template is approved yet, the agent can only reply inside an open WhatsApp conversation.

The closed-window result #

WhatsApp permits free-form messages only within 24 hours of the customer's last inbound message. Outside that window, only pre-approved templates go out. See The 24-hour window for the rule itself.

What matters here is how the tool behaves when it hits that wall. It does not fail silently, and it does not quietly substitute different words. It returns a structured status the agent can reason about:

The practical consequence: on template_required, the agent knows why it could not send and can do something sensible — send an approved template instead, or tell the customer plainly that it cannot message them right now and offer another route. It does not tell the customer the message went out when nothing was sent. If you have approved no templates, this is the moment your agent starts apologising to customers at 2 a.m.; approving one utility template is usually the whole fix.

search_knowledge #

Voice calls only, and only when the agent has knowledge attached.

On a call, the agent already holds a compressed fact sheet built from its knowledge base, so ordinary questions are answered without any lookup — which is what keeps a call feeling like a conversation rather than a query. search_knowledge is the long tail: when the caller asks for a specific detail the fact sheet does not carry, the agent searches the full knowledge base for it.

You do not configure this tool. It appears when the agent has content and disappears when it does not.

On chat channels there is no equivalent tool because retrieval is not a decision there — the relevant passages are put in front of the model before it answers. See Knowledge bases.

end_call #

Voice calls only. Hangs up, after the agent's goodbye has finished playing.

This exists because a phone call needs an ending. Without it, an agent that has said goodbye sits on an open line waiting for a caller who has stopped talking, and the call ends on an idle timeout instead of a clean farewell. The tool waits for the spoken goodbye to complete before disconnecting, so the caller never hears themselves cut off mid-word.

schedule_callback #

Voice calls only. When a caller asks to be called later, this tool resolves the requested time in the workspace time zone, keeps it inside calling hours, and creates a visible scheduled call-back. The agent reads back the time that was actually booked rather than merely agreeing to the caller’s wording.

Scheduled calls appear on the Calls page, where staff can cancel them before they are placed.

Appointment tools #

The Book appointments switch lets the agent check what is free and book a time during the conversation. It is off by default.

On the Tools tab:

• The switch stays greyed out until the workspace has a booking calendar. The card says No calendar set up yet. with a Set up a calendar link. When you come back from creating one, booking is switched on with that calendar.
• Calendar chooses which calendar the agent books into, when you have more than one. Turning booking on picks your default calendar, so the agent is never on with no calendar.
• Let it move or cancel a booking lets the agent cancel a booking the customer already has.
• A summary line under the switch shows the calendar's booking rules, with Change these to edit them on the calendar.

The appointment tools are offered when Book appointments is on and a calendar is selected:

• check_appointment_availability reads live capacity and returns opaque slot ids. The agent must call it before offering a time.
• book_appointment accepts only a slot id returned by that check.
• reschedule_appointment reserves the new slot before releasing the old one. It is offered whenever booking is on, whatever the Let it move or cancel a booking switch says.
• cancel_appointment identifies the customer's existing booking and records the reason when supplied. It is offered only when Let it move or cancel a booking is on.

See Appointments and calendars.

Building your own tools #

Your own tools are knowledge sources. There is no separate integrations screen, no plugin directory, and no third-party connector marketplace — a tool is an endpoint or mcp source on a knowledge base, and it reaches an agent through the same attachment that gives it knowledge.

That is a deliberate design: the thing that decides what an agent knows also decides what it can do, so there is exactly one place to audit.

Read tools versus action tools #

Every custom tool declares a capability.

In the console these read as Look up data and Take an action, and a source configured as an action carries an Action badge wherever it appears.

The distinction is enforced, not advisory:

• A read tool may only use GET or POST. Choose PUT, PATCH, or DELETE and you are told {method} changes data — set capability to 'action' to use it.
• An action must be a live tool. It cannot be a scheduled ingest, because ingesting a DELETE on a timer is not a thing anyone wants.
• A live tool must have a name the agent can call.

A live read tool #

Mode Call it live, capability Look up data. It is never ingested into the knowledge base; it is registered as a function the agent invokes mid-answer.

You provide:

• The URL, optionally with {braces} for values the agent fills in — https://api.yourcompany.com/orders/{order_id}. Each substituted value fills exactly one path segment; it cannot escape into the rest of the path.
• A tool name — a short verb, like check_stock. This is what appears in transcripts.
• When should the agent use it? — plain words. This is the field that stops the agent calling too eagerly, and it deserves more thought than the URL.
• Headers, if the endpoint needs auth. Values go into encrypted storage immediately and are never shown again.

The response is capped at 2 MB, and what reaches the model is truncated at 24,000 characters. Return the fields the agent needs, not your full object graph — a lean response is both faster and easier for the agent to use correctly.

An action tool #

Mode Call it live, capability Take an action. Same fields, plus a method that may be POST, PUT, PATCH, DELETE, or GET.

When any action tool is bound to an agent, extra rules are injected into its behaviour automatically:

• Confirm the customer actually asked for this before doing it.
• Gather missing details one at a time, not as a form.
• Never claim it is done before the tool returns success.
• Never call speculatively.

Every action call is audited — success or failure — with the workspace, agent, conversation, channel, deployment, source, tool name, capability, outcome, and latency. Arguments and response bodies are deliberately not recorded, because they carry customer data and, occasionally, credentials. You get a complete record of what happened without a second copy of the payload. Read-capability calls are not audited; nothing changed.

MCP servers #

An MCP server is added once and its tools become available to any agent the knowledge base is attached to. Up to 20 tools per server, and you can restrict which of them are allowed by name.

Because MCP does not declare which of a server's tools mutate state, you classify the server, not the tool — look-up or action — and every tool on it inherits that classification. If any tool on the server changes data, the whole server is an action server. That is a conservative default and it is the correct one.

Errors are reported in plain words: The MCP server rejected our credentials (401)., The MCP server answered with HTTP {code}., Couldn't reach the MCP server. Check the URL and try again., and The MCP server lists no tools.

Safety at call time #

Every custom tool call, read or action, runs through the same guards:

• The destination must resolve to a public address. Internal addresses, loopback, and cloud metadata endpoints are refused.
• Redirects are not followed, and the connection is pinned to the address that was checked — so a host cannot pass a check and then point somewhere else.
• Responses are capped at 2 MB, and what reaches the model at 24,000 characters.
• Credentials are read from encrypted storage at call time and are never present in any record you can read.

The tool policy #

The switches on the Tools tab make up the agent's tool policy. Each change is saved and live the moment you flip the switch. When you publish, the policy is recorded in the version, so what an agent was allowed to do on a given day can be looked up on the Versions tab, and a rollback restores it.

The actions master switch is absolute. Turned off, action tools on an attached knowledge base are not declared to the model at all — it cannot try and be refused, because it never learns they exist. Read tools continue to work normally, so an agent with actions blocked can still look up an order but cannot cancel one. Turn it off when you want an agent that answers questions about a system it must not touch.

Tools are also only offered when their source is actually serving. A source that is still syncing or has failed contributes nothing, so a broken integration degrades the agent rather than breaking the conversation.

What happens automatically #

Three behaviours are not settings and cannot be turned off, because turning them off would only produce bad data:

• Contact resolution. Before creating anything, the agent resolves the customer against your directory by email, phone, and WhatsApp ID. A returning customer enriches the record that already exists. See Conversations and contacts.
• Idempotent ticketing. Retries within the same conversation return the same ticket rather than duplicates.
• AI handoff context. When a ticket is opened, the issue summary, the channel, the requester, and the conversation reference go with it, so the person who picks it up is not starting from nothing.

Reading what a tool did #

Every conversation in the inbox shows an operational trail alongside the messages, and tool use appears there by kind: Knowledge base, Live API, MCP tool, and Action. That trail is staff-facing only — it is not part of the transcript a customer sees, and it is not returned by GET /conversations/{id}/messages.

When an agent gives a wrong answer, that trail is the first thing to read. It tells you immediately whether the agent looked anything up, called your API, or answered from memory — three very different bugs with three very different fixes.

Troubleshooting #

Where to go next #