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

# Unknown Tool Alias

> The model emitted a tool_use whose name is neither a registered MCP wire form nor a caller-declared tool.

**Surface:** `GET /agents/runs/{id}`, `error.type = "AgentLoopUnknownToolAlias"`

## When this error occurs

The workflow routes every emitted tool call by the shape of its wire name:

* **Dash-prefixed (`{alias}-{tool}`)**: alias must match an `mcp_servers[].alias` for this
  run's effective config.
* **Dash-free (`{tool}`)**: name must match an entry in caller-declared `tools[]`.

This error means neither lookup hit — the model emitted a name that doesn't resolve to a
registered tool. There's nothing for the platform to call and nothing meaningful to surface
in `pending_tool_calls`, so the run fails.

Common causes:

* The system prompt or the tool catalog references a tool that wasn't actually registered
  for this run (typo in alias / name).
* The model hallucinated a tool name (rare with `tool_choice` set; more common with `auto`
  and a loose prompt).

## How to fix

* Make sure every tool the system prompt mentions also appears in `mcp_servers` or
  `tools[]` for the run's effective config.
* Tighten the prompt: "Only use the tools listed below; do not invent new ones."
* Use `tool_choice: {kind: any}` to force a real tool, or `specific_tool` (with optional
  `mcp_alias`) if you know which one is expected next.