> 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

> **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](/agents/guides/connecting-tools.md) walks through standing up a tool server.
>
> YAML examples follow **manifest schema 6.1.1**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](/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](/agents/concepts/routines.md) tool node or a [policy](/agents/concepts/policies.md) action says to.

Each MCP server is declared in the manifest with an `id` that becomes the **namespace** for its tools:

```yaml
agent_config:
  mcps:
    - id: cars
      hostname: http://cars-mcp
      port: 8765
      transport: streamable-http
    - id: crm
      hostname: https://crm-tools.internal.example.com
      port: 443
      transport: streamable-http
      api_key: ${CRM_MCP_KEY}
```

A tool named `search_cars` on the `cars` server is referenced everywhere as `cars:search_cars`. The namespace keeps same-named tools on different servers unambiguous.

### Declaration fields

| Field       | Type              | Required | Default           | Meaning                                                                                   |
| ----------- | ----------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------- |
| `id`        | string            | yes      | —                 | Namespace prefix for this server's tools.                                                 |
| `hostname`  | string            | yes      | —                 | Host **including scheme** (`http://` or `https://`). Host only — no path, port, or query. |
| `port`      | integer 1–65535   | yes      | —                 | TCP port.                                                                                 |
| `transport` | `streamable-http` | no       | `streamable-http` | The only supported MCP transport.                                                         |
| `api_key`   | `${VAR}` env-ref  | no       | —                 | Sent to the MCP server as `Authorization: Bearer`. Omit for unauthenticated servers.      |

### Connection behaviour

* All declared servers are 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](/agents/guides/connecting-tools.md#3-designing-tools-the-agent-calls-well).

## Where tools are called from

| Caller                       | Mechanism                                                                                                                                                                                                                     |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Routine TOOL node**        | `tools:` + `tool_instruction` — the instruction tells the model how to derive parameters. The node completes when the tool executes. See [Routines](/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.                                                                                                                                                                     |
| **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`).

## Built-in tools

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

| Tool                   | Purpose                                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `built-in:reason`      | Backs `think:` nodes — typed structured inference validated against the node's `output_schema`, stored in `session.metadata.step_outputs`. |
| `built-in:emit_output` | Terminates an autonomous run — validates the final JSON against the routine's `output_schema` and settles the run.                         |

Authors use them via routine syntax (`think:` nodes; `tools: built-in:emit_output` terminal nodes); the exact parameter contracts are in [Built-in tools](/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 manifest's `mcps` servers. 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`](/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](/agents/reference/http-api.md).

## See also

* [Connecting tools](/agents/guides/connecting-tools.md) — build and wire an MCP server
* [Routines](/agents/concepts/routines.md) — tool nodes and instructions
* [Security](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.