Skip to main content
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.