> For the full page index, fetch https://echonova.ai/llms.txt

# 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](/docs/agents/slack)
(`add_reaction`, `remove_reaction`),
[Google Calendar](/docs/agents/google-calendar) (`check_availability`,
`create_event`, `list_events`, `list_calendars`) and
[Twilio](/docs/agents/sms-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](/docs/agents/tool-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**

```text
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**

```text
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.

## Related

- [System tools](/docs/agents/system-tools): the three built-in tools and how to describe them
- [Webhook tools](/docs/agents/webhook-tools): give an agent one endpoint of your own
- [OpenAPI tools](/docs/agents/openapi-tools): import a whole API in one step
- [Connect a database](/docs/agents/database-tools-connect): answer callers from your own data
- [Web search](/docs/agents/system-tool-web-search): let the agent look something up online
- [Dialect detection](/docs/agents/system-tool-dialect-detection): adapt to the caller's Arabic dialect
- [End conversation](/docs/agents/system-tool-end-conversation): let the agent close the conversation
- [OpenAPI tool operations](/docs/agents/openapi-tool-operations): per-operation auth, fixed values and switches
- [Review and approve database questions](/docs/agents/database-tools-templates): decide what the agent may ask your database
- [Database tool security](/docs/agents/database-tools-security): what happens to your connection string
- [Google Calendar](/docs/agents/google-calendar): the four calendar tools and how to write the persona around them
- [SMS with Twilio](/docs/agents/sms-twilio): the **Send SMS** action on a Twilio number
- [Channels overview](/docs/agents/channels-overview): the connections integration tools come from
- [Workspace secrets](/docs/agents/secrets): store an API key once and reference it
- [Auth connections](/docs/agents/auth-connections): save a basic, bearer or OAuth2 credential
- [The retrieval bench](/docs/agents/tool-bench): check what a caller's wording would reach