OpenAI Agents SDK tool not found: what a Sume call returns
A hosted MCP tool name that differs only in - or _ gets a tool_not_found result with a Did you mean hint; a scope-hidden tool returns insufficient_scope.
When an agent calls a hosted MCP tool name that differs from a real one only in - versus _, Sume returns a tool result with code tool_not_found and a message of the form "Unknown remote MCP tool: NAME. Did you mean real_name?". A tool that exists but is hidden from a read-only OAuth session returns insufficient_scope instead. Neither is a JSON-RPC protocol error.
The OpenAI Agents Python v0.22.3 release (published 2026-09-17) lists "fix(core): deliver tool-not-found output on server-managed resume (#4947)". The release note says no more than that, so this post covers only what the Sume side sends. Sources were read 2026-10-01.
What does the model see for a mistyped tool name?
The server compares the requested name with its registry, ignoring - and _ punctuation. If that finds a registered tool the caller could see, it returns the hint with the suggested name and the stable code tool_not_found. Other typos are not matched: a name that does not resolve returns tool_not_found with no suggestion. The docs also say the server turns . into _ on call, so a dotted alias such as tools.list still works and is not an error.
How is a hidden tool different?
Under OAuth with only mcp:read, mutating and paid tools are not listed. If the model calls one anyway, the result carries insufficient_scope and the required scope mcp:write. The fix is to re-authorize with write access, not to rename the call.
| Situation | Result code | What to do |
|---|---|---|
| Differs only in - / _ | tool_not_found plus a Did you mean hint | Retry with the suggested name |
| Dotted alias | Works (. becomes _) | Nothing |
| Write tool, read-only OAuth | insufficient_scope | Grant mcp:write or use an API key |
| Name not in the catalog | tool_not_found, no suggestion | Call tools_list |
Why do these come back as results and not errors?
A code comment in the server says tool execution failures are returned as MCP tool results with isError: true, not as JSON-RPC errors, so a client can show the payload. That matters for an agent loop: the failure text is ordinary tool output the model can read, and your runner must pass it back on the next turn, including after a resume.
How do I stop an agent guessing names?
Have it discover the live tools first. MCP tools and gates says to always discover the live contract with tools_list and tools_schema rather than assume the HTTP API surface. For the error shapes in general, see Sume tool errors in the OpenAI Agents SDK.
Sources
Related posts
More in Developers
- Agents SDK mcp.Client mode auto against Sume's MCP server
With MCP Python SDK v2, the Agents SDK probes the newest protocol and falls back to initialize. Sume's hosted server still serves initialize with 2025-11-25.
- OpenAI Agents Python MCP non-text content as JSON: Sume results
openai-agents-python v0.20.0 serializes non-text MCP blocks as JSON. Sume tool results are text blocks, with media delivered as URLs inside the JSON.
- OpenAI Agents Python MCP backoff ceiling vs Sume retry-after
Set the MCP retry backoff ceiling low enough that a Sume 429 with retry-after is honored first, and never retry a paid create without its idempotency key.
- Agents SDK approve_unsafe_replay with Sume paid calls
approve_unsafe_replay resends a model request, not a Sume tool call. Sume paid and write tools need a stable idempotency_key; keep it fixed on a repeat.
Written by Sume