Skip to main content
Surface: GET /agents/runs/{id}, error.type = "UnknownTool"

​
When this error occurs

The workflow called an MCP server’s tools/call for a tool name that the server doesn’t recognise. JSON-RPC reports this as -32601 method not found. Discovery normally prevents this — the workflow calls tools/list at run start and uses only the names the server actually exposes. This error fires when something changes between discovery and the tools/call:
  • The server is behind a load balancer where some instances have the tool and some don’t (deploy in progress on the server side).
  • The server’s catalog was edited between the run’s tools/list and tools/call (rare race; same-run discovery + call usually happen within a few hundred ms).
  • The model hallucinated a tool name that wasn’t in the discovered catalog — but in that case the workflow would normally reject earlier with Unknown Tool Alias. Seeing UnknownTool instead suggests a classifier mismatch worth investigating.

​
How to fix

  1. Verify the tool name against the MCP server’s current tools/list (curl it directly with a JSON-RPC client) — has the catalog drifted?
  2. If the discrepancy is intermittent, fix the server-side deploy first.
  3. If the catalog now permanently lacks the tool the agent loop was calling, either restore the tool or update your system prompt to stop referencing it.