> 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/reference/built-in-tools.md).

# Built-in tools

> **Context** — The runtime ships two synthetic tools under the `built-in` namespace. Authors normally meet them through routine syntax (`think:` steps; autonomous terminal steps); this page is the exact call contract — what the model is asked to supply and every result the handler can return.

Both tools take nested JSON **as a JSON-encoded string parameter** (`output_json`) — tool parameters are primitive-typed, so objects are marshalled through strings. Both return `{"ok": true, ...}` on success and `{"ok": false, "error": <code>, ...}` on failure; a failed call is visible to the model, which can retry with corrected output within the turn's iteration budget.

## `built-in:emit_output`

Terminates an [autonomous run](/agents/concepts/autonomous-routines.md) with its typed result. Every terminal node of an autonomous routine (a node with no outbound transitions) must be a TOOL node calling it.

| Parameter     | Type                         | Meaning                                                                                                                                       |
| ------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `output_json` | string (JSON-encoded object) | The run's final output. Must parse as JSON and validate against the routine's `output_schema` (tightened with `additionalProperties: false`). |

On success the run transitions to `succeeded` and the callback watcher fires. Schema violations transition the run to `failed` with error code `output_validation_failed` (the callback's `error.details` carries the violating path).

| Result `error`             | Meaning                                                                  |
| -------------------------- | ------------------------------------------------------------------------ |
| `output_validation_failed` | `output_json` didn't parse, or violated `output_schema` — the run fails. |
| `not_an_autonomous_run`    | Called in a session that isn't an autonomous run.                        |
| `routine_not_registered`   | Session metadata names a routine the runtime doesn't know.               |
| `session_not_found`        | The session disappeared mid-run.                                         |
| `not_configured`           | Autonomous runtime not wired (server misconfiguration).                  |

Usage in a routine:

```yaml
- id: finish
  tools: built-in:emit_output
  tool_instruction: >
    Call emit_output with output_json set to a JSON object
    containing exactly the decision and explanation fields
    produced by the assess node.
```

## `built-in:reason`

Backs the `think:` node kind — typed structured inference that does **not** end the turn. The loader compiles each `think:` + `output_schema:` node into a TOOL node calling this tool with the node's id baked into the instruction.

| Parameter     | Type                         | Meaning                                                                                                                                        |
| ------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `step_id`     | string                       | The think node's id (the parameter keeps its historical wire name; the value is compiled into the node's instruction — not chosen at runtime). |
| `output_json` | string (JSON-encoded object) | The inference result. Must validate against the node's `output_schema` (tightened with `additionalProperties: false`).                         |

On success the validated object is merged into `session.metadata.step_outputs[<node-id>]` and returned in the tool result, so downstream steps see the typed fields in history.

| Result `error`             | Meaning                                                                                                               |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `output_validation_failed` | `output_json` didn't parse or violated the node's schema — the model can correct and retry.                           |
| `missing_step_id`          | Empty `step_id` argument.                                                                                             |
| `step_not_registered`      | No `output_schema` registered for this routine + node id.                                                             |
| `routine_not_resolved`     | The session has no `routine_id` metadata. Autonomous runs set it automatically, so this indicates a misconfiguration. |
| `session_not_found`        | The session disappeared.                                                                                              |
| `persist_failed`           | Writing `step_outputs` to the session failed.                                                                         |
| `not_configured`           | Reason-step registry not wired (server misconfiguration).                                                             |

Authoring guidance for think nodes (autonomous routines only): [Autonomous routines](/agents/concepts/autonomous-routines.md#node-types).


---

# 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/reference/built-in-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.