> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/concepts/tools.md).

# Tools

Tools are functions the agent calls — served by your MCP servers, plus five built-ins. Covers namespacing, declaration, auth, reevaluation tools, and tool-event injection.

> **Context** — Tools are how an agent acts on the world: look up an order, create a booking, hand off to a human. This page covers the tool model; [Connecting tools](https://docs.interactive.ai/agents/guides/connecting-tools.md) walks through standing up a tool server.
>
> YAML examples follow **manifest schema 1.4.0**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](https://docs.interactive.ai/agents/operations/versioning.md).

## The model

Tools are served over the **Model Context Protocol (MCP)** — an open standard for exposing typed, described functions over HTTP. You run one or more MCP servers; the agent connects to each at boot, catalogues its tools, and can call them whenever a [routine](https://docs.interactive.ai/agents/concepts/routines.md) tool node or a [policy](https://docs.interactive.ai/agents/concepts/policies.md) action says to.

Each MCP server is registered in the project, which stores its address and credential. The manifest references registered MCPs by name, and each entry's `id` becomes the **namespace** for its tools:

```yaml
agent_config:
  mcps:
    - cars
    - ref: crm-prod
      id: crm
```

A tool named `search_cars` on the `cars` MCP is referenced everywhere as `cars:search_cars`. The namespace keeps same-named tools on different servers unambiguous. When the platform deploys the agent, it resolves each reference into the server's address and credential.

### Reference fields

An entry is either the registered MCP's name or an object:

| Field      | Type                  | Required | Default   | Meaning                                                                                                             |
| ---------- | --------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
| `ref`      | string                | yes      | —         | Name of the MCP connection registered in the project.                                                               |
| `id`       | string                | no       | `ref`     | Namespace prefix applied to this MCP's tools at runtime.                                                            |
| `endpoint` | `private` \| `public` | no       | `private` | Which endpoint of the MCP the agent connects to. `public` needs a self-hosted MCP with its public endpoint enabled. |

The agent sends the registered credential on every MCP request, as `Authorization: Bearer` by default. A manifest that reaches the agent with an unresolved reference fails boot.

A raw `{id, hostname, port}` connection is still accepted but deprecated. See [Manifest reference](https://docs.interactive.ai/agents/reference/manifest.md) for its fields.

### Connection behaviour

* Every referenced MCP is contacted at boot; an unreachable server fails startup (your tools are part of the agent's contract).
* Transient MCP failures at runtime trigger **automatic reconnection** — a flapping tool server degrades requests that needed it, not the whole agent.
* Tool definitions (names, descriptions, parameter schemas) come from the MCP server's own catalog. The agent passes the LLM your tool descriptions verbatim — well-described tools get called correctly; vague ones don't. See [Connecting tools](https://docs.interactive.ai/agents/guides/connecting-tools.md#3-designing-tools-the-agent-calls-well).

## Where tools are called from

| Caller                       | Mechanism                                                                                                                                                                                                                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Routine TOOL node**        | `tools:`, optional `input` (argument sources) and `tool_instruction` (argument guidance). The tools run when the routine reaches the node; the node completes when they execute. See [Routines](https://docs.interactive.ai/agents/concepts/routines.md#tool-node-completes-when-the-tool-executes). |
| **Policy action**            | A policy may name `tools:` and instruct their use in its `action`. Tool call and customer messaging can share one action (unlike routine nodes).                                                                                                                                                     |
| **Think node**               | Internally a call to the built-in `built-in:reason` tool.                                                                                                                                                                                                                                            |
| **Compute node**             | Internally a call to the built-in `built-in:compute` tool, with the values its formulas worked out.                                                                                                                                                                                                  |
| **Autonomous terminal node** | A TOOL node calling `built-in:emit_output`.                                                                                                                                                                                                                                                          |

Tool results land in the conversation history as **tool events** — visible to the model on subsequent iterations and to your integration in the event stream (`kind: "tool"`, carrying `tool_id`, `arguments`, `result`).

## When a tool fails

A tool request **fails** when:

* the tool's definition can't be read, because its MCP server is unreachable;
* its arguments can't be prepared, even after the fallback model;
* in an autonomous run, the model finds no value for a required argument (in a conversation the agent asks the customer for it instead);
* in an autonomous run, a value bound to its arguments is missing or of the wrong type (in a conversation the call is skipped instead, and no tool error is recorded);
* a compute node's formula can't give its value (an empty input, text where a number belongs, a division by zero), or its values don't match its `output`;
* its execution fails, because the tool raised an error, returned an MCP error result, or returned a result that doesn't match its node's `output`.

A failed request is recorded as a tool event whose result is `"Tool call error"`, with the details in `metadata.error_details` and the stage that failed in `metadata.failed_stage`: `definition`, `preparation`, `binding`, `compute` or `execution`. It only affects that request: the turn's other tools still run, and the same step or policy doesn't retry it later in the turn. A tool that returns an error-shaped payload as a normal result hasn't failed. If a failure should count, the tool must raise or mark its result as an error.

The failed result is the step's result, `ok: false`, which a routine step's rules can route on. In a conversation, a request that failed before its tool ran moves the routine on only from a step whose transitions are rules; at other steps the model decides on the next message, and normally runs the step again (see [Rules on transitions](https://docs.interactive.ai/agents/guides/authoring-routines.md#rules-on-transitions)).

`on_tool_error` decides what the turn does next, deterministically and without a model. Conversational turns read it from the manifest's `runtime`:

```yaml
runtime:
  on_tool_error:
    default: continue              # continue | silent | handoff
    tools:
      zendesk:create_ticket: handoff
    handoff:
      reason: A required tool failed
      internal_note: "Automatic escalation: a tool call failed."
      silent: true                 # or customer_message: <reply sent verbatim>
```

| Action               | Effect                                                                                                                                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `continue` (default) | The reply is generated knowing the tool failed.                                                                                                                                                                                                           |
| `silent`             | No reply this turn; the agent keeps handling the conversation.                                                                                                                                                                                            |
| `handoff`            | Calls `built-in:initiate_human_handoff` with the `handoff` arguments, plus `metadata` naming the failed tool and its error. The session switches to manual mode, as with any handoff: the agent stops replying until a human hands the conversation back. |
| `emit_output`        | Autonomous routines only: the run settles with a fixed output (see [Routines](https://docs.interactive.ai/agents/concepts/routines.md)).                                                                                                                  |

An entry in `tools` overrides `default` for that tool. One action runs per turn — the most severe the failed tools call for — and none after the turn has already handed off. Tools that already ran stay done; no further tools run after the action.

## Built-in tools

The runtime ships six synthetic tools under the `built-in` namespace:

| Tool                              | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `built-in:reason`                 | Backs `think:` nodes — typed structured inference validated against the node's `output`, stored in `session.metadata.step_outputs`.                                                                                                                                                                                                                                                                                                                                                           |
| `built-in:compute`                | Backs `compute:` nodes — records the values the node's formulas worked out, with no model call, as the node's result.                                                                                                                                                                                                                                                                                                                                                                         |
| `built-in:emit_output`            | Terminates an autonomous run — validates the final JSON against the routine's `output_schema` and settles the run.                                                                                                                                                                                                                                                                                                                                                                            |
| `built-in:initiate_human_handoff` | Escalates the conversation to a human and switches the session to manual mode.                                                                                                                                                                                                                                                                                                                                                                                                                |
| `built-in:current_datetime`       | Backs the manifest's `context.current_datetime` block — the engine (never the model) calls it each turn to refresh the `current_datetime` variable in the model's context.                                                                                                                                                                                                                                                                                                                    |
| `built-in:date_math`              | Exact date and time arithmetic: moves a date or timestamp by minutes, hours, days, weeks, months or years, measures the gap between two, and finds the next weekday. Days and longer count calendar dates; hours and minutes count exact time. With `until`, `reached` is a yes/no a routine can branch on, such as "pending at least 24 hours" or "has this deadline passed". `timezone` decides how timestamps without an offset are read and which calendar date every timestamp falls on. |

Authors use them via manifest or routine syntax (`think:` and `compute:` nodes; `tools: built-in:emit_output` terminal nodes; handoff nodes; the `context.current_datetime` block; `built-in:date_math` in the `tools` of a policy or routine node). The exact parameter contracts are in [Built-in tools](https://docs.interactive.ai/agents/reference/built-in-tools.md).

## Reevaluation tools

Normally the engine decides which policies and routines apply **at the start of a turn**. But some tools change the state those decisions depend on *during* the turn — and once that state changes, the right next action may be different from what was chosen a moment ago. Reevaluation tells the engine to re-decide after such a tool runs, so the new action can happen in the **same turn** instead of waiting for the next one.

The motivating example: a customer asks a question that requires them to be authenticated. At the start of the turn they aren't, so the engine picks the "authenticate first" path and runs `crm:authenticate_customer`. Without reevaluation, the turn would end there — the agent would authenticate, then ask the customer to repeat themselves next turn. Marking `crm:authenticate_customer` as a reevaluation tool makes the engine re-decide the moment authentication succeeds: it now sees an authenticated customer, activates the routine that answers the original question, and responds — all in one turn.

Declare such tools globally so a successful call re-triggers routine and policy matching:

```yaml
agent_config:
  context:
    reevaluation_tools:
      - id: crm:authenticate_customer
      - id: crm:get_account_status
```

Each id must match a tool exposed by one of the MCPs in the manifest's `mcps` list. Reserve this for tools whose result **meaningfully changes what the agent should do next** (authentication, account-status lookups, anything that unlocks or redirects a flow) — re-deciding has a cost, so don't mark every read-only lookup.

The per-policy [`reevaluate_after`](https://docs.interactive.ai/agents/concepts/policies.md#fields) field is the **same mechanism scoped to one policy**: use the global list when a state change has broad effects (authentication unlocks much of the routine catalog), the per-policy field when only one rule's relevance flips.

## Injecting context as a tool event

Sometimes your integration has data the agent should treat as "a tool already fetched this" — a prior-conversation dump, a bank statement, a CRM export — without the agent calling anything. POST it as a synthetic tool event:

```
POST /sessions/{session_id}/tool_events
Authorization: Bearer <agent api key>
Content-Type: application/json
```

```json
{
  "tool_id": "injected:conversation_history",
  "arguments": {"source": "zendesk", "ticket": "12345"},
  "result": {"messages": [{"from": "customer", "text": "Where is my refund?"}]},
  "idempotency_key": "zendesk-12345-import-1",
  "trigger_processing": false
}
```

Semantics to know:

* `tool_id` is an opaque label — it need not name a real tool. Use the `namespace:name` convention (e.g. `injected:bank_statement`).
* **Visibility is next-turn only.** The engine snapshots history when a turn starts; an event injected mid-turn appears from the next turn on.
* `trigger_processing: true` starts a response turn immediately — and **cancels any turn currently in flight** for the session. Default `false`.
* `idempotency_key` makes retries safe: a duplicate key returns the original event's ids without creating a duplicate.
* Injected content is sanitised (control characters stripped) before it reaches prompts.

Full request/response schema: [HTTP API](https://docs.interactive.ai/agents/reference/http-api.md).

## See also

* [Connecting tools](https://docs.interactive.ai/agents/guides/connecting-tools.md) — build and wire an MCP server
* [Routines](https://docs.interactive.ai/agents/concepts/routines.md) — tool nodes and instructions
* [Security](https://docs.interactive.ai/agents/operations/security.md) — credentials and network posture for tool servers


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/agents/concepts/tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
