> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Give your agent things it can do during a call.

A **tool** is an action the agent can invoke mid-conversation. The LLM decides when to call a tool based on its name, description, and the parameter schema you provide.

Tools are configured in the **Abilities** section of the agent editor.

## Tool anatomy

Every tool has:

| Field              | Purpose                                                        |
| ------------------ | -------------------------------------------------------------- |
| `name`             | Identifier the LLM uses (e.g. `transfer_to_billing`)           |
| `description`      | What the tool does and **when** to use it — the LLM reads this |
| `properties`       | JSON Schema of parameters the LLM must fill                    |
| `required`         | Which properties are mandatory                                 |
| `actions`          | The concrete actions taken when the tool fires                 |
| `actions_on_error` | Fallback actions if the primary actions fail                   |

The `description` field is the most important. The LLM only invokes the tool when the description matches the conversation context. Be explicit:

✅ `"Use this when the caller asks to speak with a human, mentions a billing dispute, or asks a question outside the scheduling scope."`

❌ `"Transfers the call."`

## Built-in actions

When a tool fires, it runs one or more **actions** in sequence. Available actions:

| Action               | What it does                                         |
| -------------------- | ---------------------------------------------------- |
| `play_message`       | Speak a fixed message before continuing              |
| `play_audio`         | Play a pre-recorded audio file                       |
| `cold_transfer`      | Transfer to another number, hang up                  |
| `warm_transfer`      | Transfer with the agent staying on the line briefly  |
| `conference`         | Add a third party to the call                        |
| `dtmf`               | Send DTMF tones (for IVR navigation)                 |
| `wait`               | Pause for N seconds                                  |
| `hangup`             | End the call                                         |
| `leave_room`         | Drop the agent from a multi-party call               |
| `stop_audio`         | Stop audio started by `play_audio`                   |
| `update_endpointing` | Change the turn-detection endpointing delay mid-call |
| `workflow`           | Invoke an Anyreach workflow                          |
| `knowledge_base`     | Run an explicit KB query                             |

Each action can carry a `condition` expression so it only runs when the condition holds. In the async **text** and **email** engine only `workflow`, `knowledge_base`, and `play_message` run; the telephony and audio actions are skipped. For the full field-by-field reference see [Abilities and actions](/agents/abilities-and-actions); transfers have their own page in [Call transfers and conference](/agents/transfers).

You can chain actions. For example, a "transfer to billing" tool might be: `play_message("Connecting you to billing now") → cold_transfer("+15551234567")`.

## Workflow tools

Exposing a workflow as a tool is the most powerful pattern in Anyreach. The workflow can do anything — call APIs, run code, branch on AI — and return a result the agent uses.

<Steps>
  <Step title="Build and publish a workflow">
    See [the workflow builder tour](/workflows/builder-tour). The workflow's input schema becomes the tool's parameter schema.
  </Step>

  <Step title="Add it to the agent">
    Abilities → Add tool → **Workflow**. Pick the workflow and a published version (or "latest published").
  </Step>

  <Step title="Map parameters">
    The workflow's input fields appear as tool parameters. Edit names and descriptions if you want them to read better to the LLM.
  </Step>

  <Step title="Decide on output handling">
    The workflow's output is returned to the agent. Decide whether the agent should speak the result verbatim, summarize it, or use it silently to inform the next turn.
  </Step>
</Steps>

### Example: look up an order

Workflow input: `order_number: string` → HTTP step calls your order API → Output step returns `{ status, ship_date, items }`.

In the agent prompt, instruct: *"When a caller asks about their order, ask for their order number, then call `lookup_order`. Tell them the status and shipping date."*

The LLM will fill `order_number` from the conversation, invoke the tool, get the result, and weave it into a natural response.

## Knowledge base tools

Even though knowledge bases are queried implicitly when attached to an agent, an explicit `knowledge_base` tool is useful when:

* You have multiple KBs and want the LLM to choose between them
* You want the agent to *announce* it's looking something up ("Let me check on that...")
* You want different `top_n` values for different question types

Configuration:

| Field        | Purpose                                                                  |
| ------------ | ------------------------------------------------------------------------ |
| `dataset_id` | Which KB to query                                                        |
| `query`      | Expression that builds the search query (often `${last user utterance}`) |
| `top_n`      | How many chunks to retrieve. Default `5`                                 |

## Error handling

Set `actions_on_error` for any tool that can fail. A common pattern:

```
actions: [workflow → lookup_crm_record]
actions_on_error: [play_message("I'm having trouble looking that up — let me get a human.")]
                  [cold_transfer("+1555...")]
```

Without this, a workflow failure produces an awkward silence.

## Limits

* An agent can have many tools, but each tool's description is in the system prompt at every turn. More than \~15 tools tends to dilute selection accuracy.
* Workflow tools have a soft latency budget of \~2-3 seconds before the caller notices a pause. Use `play_message` to fill silence on slower workflows.