Tools

Tools are functions the agent calls — served by your MCP servers, plus two 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 walks through standing up a tool server.

YAML examples follow manifest schema 6.1.5. Manifest and content shapes are schema-versioned and differ across runtime versions — see Versioning & compatibility.

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 tool node or a policy action says to.

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

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
      path: /v2/mcp
      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.
path	string	no	/mcp	URL path the MCP endpoint is mounted at. Set when the server exposes MCP somewhere other than /mcp (e.g. /v2/mcp).
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.

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

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:

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 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

{
  "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.

See also

• Connecting tools — build and wire an MCP server

• Routines — tool nodes and instructions

• Security — credentials and network posture for tool servers