OpenAI Agents Python MCP error content: reading Sume tool errors
openai-agents-python v0.20.0 keeps MCP error content with structured output. Sume tool failures arrive as isError text with code, message and http_status.
With openai-agents-python v0.20.0 or later, an MCP tool error keeps its content even when structured output is enabled. A Sume failure is a normal tool result with isError: true and one JSON text block holding code, message and, when known, http_status, so your code can branch on code.
The fix is listed in the openai-agents-python release notes; the error shape is from Sume's MCP server code and MCP OAuth docs, read 2026-10-01.
What did v0.20.0 fix?
The release list has one line: "fix(mcp): keep MCP error content when structured output is enabled". It gives no further detail, so I will not guess at the failing case.
What does a Sume tool error look like?
The server's toolErrorResult builds an envelope with code (falling back to tool_execution_error), message, optional details and http_status, plus any other fields, and returns it as one text block with isError: true.
| code | When |
|---|---|
| insufficient_scope | A mutating tool is called on an mcp:read session; the error also carries required_scope |
| mcp_output_too_large | Result exceeds the output limit; message says it is not a job failure and never to resubmit a paid create |
| tool_execution_error | Default when no code is set |
How should my agent react?
Parse the text block as JSON and switch on code. For insufficient_scope, re-authorize with mcp:write or use an API key. For mcp_output_too_large, read a narrower or paginated result; never repeat a paid create. Gate paid calls with approvals as in require_approval for Sume write tools.
Sources
Related posts
More in Developers
- 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.
- Does an OpenAI API key expire? Expiry dates and key rotation
OpenAI project keys can now carry an expiration date and orgs can cap lifetime. Sume documents no expiry field: rotate by minting a replacement key.
- OpenAI async tool calling for long-running render jobs
OpenAI's async tool calling lets the model keep working while your tool runs. For a slow Sume render, return the job id fast, then wait in slices.
Written by Sume