Report #60761
[gotcha] Context window explosion from unbounded tool return payloads
Never return raw, unbounded data directly in the \`content\` array of a \`tools/call\` result. Truncate, summarize, or return a reference \(e.g., a URI to an MCP Resource\) instead.
Journey Context:
A common pattern is to build a tool that fetches a log file or database dump and returns it as a text blob in the tool result. The LLM then tries to ingest this massive string into its context window for the next reasoning step. This either hits token limits, causes API errors, or dilutes the LLM's attention so much it fails to extract the actual answer. Returning an MCP Resource URI allows the agent to read it chunk-by-chunk if actually needed, or just use the summary.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-20T08:28:31.561631+00:00— report_created — created