Agents

Tools overview

The four kinds of tool an agent can call, where each one is defined, and how the agent decides to use it during a conversation.

A tool is something the agent can do besides talk. During a conversation the agent calls one, reads the result, and keeps speaking. You choose which tools an agent may call. The agent decides during the conversation which of them to use, and when.

Open the Tools tab on an agent to see them. The tab is split into two sections, Built-in tools and Workspace tools, under the line "Give this agent tools to perform actions and access external systems during conversations."

The four kinds

Kind What it does Where you define it
System A capability every agent already has. Three exist: web_search, dialect_detection, end_conversation. On the agent, in Built-in tools
Webhook Calls one HTTP endpoint you own, with parameters the agent fills in. Workspace tool library, type webhook
OpenAPI An imported Swagger or OpenAPI document. One library entry holds the whole API and its operations. Workspace tool library, type openapi
Integration A ready-made action from a connected provider, bound to that integration. Workspace tool library, type integration

System tools are not library rows. Every agent is created with all three present and switched off, so the three cards are always on the tab and never need adding.

Integration tools exist for three providers today: Slack (add_reaction, remove_reaction), Google Calendar (check_availability, create_event, list_events, list_calendars) and Twilio (send_sms). Each page says what the portal offers for its tools today.

Databases are another route to live data, and they are not library rows either. Connect a database once, approve the questions it may answer, and the agent reaches those during a conversation. The database pages under Tools cover that.

Which kind fits

  • One endpoint, a handful of parameters, a result the agent reads back: a webhook tool. You describe the request yourself, so nothing has to be imported.
  • A whole API with many operations: an OpenAPI tool. Import the document once instead of hand building one webhook tool per operation.
  • An action inside a product you already connected: an integration tool. The operation and its credentials come from the integration, so there is nothing to configure per call.
  • A capability of the conversation itself, such as looking something up online or hanging up: a system tool. There is no endpoint to point at.

Where tools live

Workspace tools live in a library shared by every agent in the workspace. Reach it from Tools in the agents navigation, at /agents/tools; the page is headed Tool Library. Create, edit and delete a tool there or from the Add Tool menu on an agent.

Giving a tool to an agent is a separate act. On the agent you select the library tools it may call, and saving replaces the whole selection: any id that no longer resolves inside the workspace is dropped, and duplicates are removed. Removing a tool from one agent leaves the library row untouched. Deleting the library row unselects it from every agent that used it.

System tools have no library row. Each agent carries its own switch, description and settings for all three.

How the agent decides to call one

Not every tool reaches the agent the same way.

System, webhook and integration tools are in front of the agent on every turn, and it picks by name and description. The description is the deciding text, which is why the webhook builder prompts its Description box with "What does this tool do? The agent uses this to decide when to call it."

Imported OpenAPI operations work differently. They are not all listed at once. Each turn the agent searches your imported operations for the ones closest to what the caller just said, keeps the top 5 and ignores anything scoring below 0.5. Database questions are searched in the same pass. The test on the Tests tab shows up to 3 hits by default, not 5.

That difference decides where to look when a tool never fires. A selected webhook tool is always in front of the agent, so a miss is a wording problem in its description. An imported operation has to win a search first, so a miss can also mean the caller's phrasing appears nowhere in the operation's description. To catch that before a caller does, open an imported OpenAPI tool from the agent's Tools tab and open its Tests tab, which runs the same search against a sentence you type. The last run shows in the Last tested column of the agent's tools table. A webhook, integration or system tool is never searched, so it has no Tests tab for this. The retrieval bench covers what that test does and does not prove.

Get it right

The description is the only thing the agent has to go on when it decides whether a tool applies. Name the situations you want it used in, and say what comes back.

Recommended

Look up a customer's order by its order number. Call this when the caller asks
where an order is, when it will arrive, or what it contained. Returns the status,
the carrier and the expected delivery date.

Less effective

Order lookup tool. Use for orders.

Interruption suppression

Every built-in tool runs with interruption suppression off: a caller can speak over the agent while the tool is running and be heard, and the agent can answer instead of finishing its line. There is no control for it in the portal today. The Built-in tools dialog edits the toggle and Description.

When a change reaches an agent

Changing a system tool or a tool selection applies to the next conversation the agent starts. A conversation already running keeps the tools it started with.

FAQ

Can one tool be used by several agents?

Yes. A workspace tool is defined once and selected on as many agents as you like. Each agent keeps its own selection, so removing the tool from one agent leaves the others alone.

Why does my tool never fire?

For a webhook, integration or system tool, the description is the only variable: rewrite it to name the situations you want the tool used in. For an imported OpenAPI operation, first check that the caller's phrasing reaches it on the tool's Tests tab, then look at the description.

Do I need a permission to add tools?

No. Any member of the workspace can create a tool, select it on an agent and switch a system tool on.

What happens to agents when I delete a tool from the library?

The tool is unselected from every agent that used it, and those agents keep working without it. Deleting cannot be undone.