[DOCS] MCP output warning docs lack format-specific recovery recipes

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

MCP output limits and warnings and the follow-up guidance for recovering from oversized MCP tool results

Current Documentation

The docs currently say:

Output warning threshold: Claude Code displays a warning when any MCP tool output exceeds 10,000 tokens Configurable limit: you can adjust the maximum allowed MCP output tokens using the MAX_MCP_OUTPUT_TOKENS environment variable * Default limit: the default maximum is 25,000 tokens

And later:

If you frequently encounter output warnings with specific MCP servers you don't control, consider increasing the MAX_MCP_OUTPUT_TOKENS limit. You can also ask the server author to add the anthropic/maxResultSizeChars annotation or to paginate their responses.

The troubleshooting page also gives only generic recovery advice:

Ask Claude to read the oversized file in smaller chunks, such as a specific line range or function, instead of the whole file

What's Wrong or Missing?

Changelog v2.1.105 says Claude Code improved the MCP large-output truncation prompt to give format-specific recipes, including jq for JSON and computed Read chunk sizes for text.

The current docs explain the limits and mention raising MAX_MCP_OUTPUT_TOKENS, anthropic/maxResultSizeChars, and pagination, but they do not document the practical recovery workflow users now see when output is too large:

A. No format-specific guidance

There is no documented advice for common cases like extracting a smaller JSON subset with jq or reading a large text artifact in calculated chunks.

B. No bridge between warning behavior and next steps

The docs explain that large results may be persisted to disk and replaced with a file reference, but they stop short of showing what a user should do next once that happens.

C. Generic troubleshooting guidance is too vague for MCP output

"Read the oversized file in smaller chunks" is helpful, but it does not tell users how to choose chunk sizes or adapt the approach based on output format.

Suggested Improvement

Add a short recovery subsection under MCP output limits and warnings, for example When large output is saved to disk.

That subsection should include:

1. A JSON example that shows narrowing output before retrying, such as using jq to select fields or summarize large arrays/objects.
2. A text example that shows asking Claude to read a persisted file in bounded ranges, with guidance on choosing chunk sizes or line ranges.
3. A brief decision table:

• raise MAX_MCP_OUTPUT_TOKENS when the full result is genuinely needed
• use anthropic/maxResultSizeChars when you control the MCP server
• paginate/filter on the server when large responses are routine
• use format-specific post-processing when the saved artifact is already on disk

The troubleshooting page should cross-link back to the MCP page and reuse the same concrete JSON/text examples instead of only saying to use "smaller chunks."

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 1006-1047 | MCP output limits and warnings explains thresholds and server-side mitigations, but not format-specific recovery steps after truncation/persist-to-disk behavior |
| https://code.claude.com/docs/en/troubleshooting | 765-773 | Generic "read the oversized file in smaller chunks" advice that could cross-reference MCP-specific JSON/text recipes |

Total scope: 2 pages affected

Source: Changelog v2.1.105

Exact changelog entry: Improved MCP large-output truncation prompt to give format-specific recipes (e.g. jq for JSON, computed Read chunk sizes for text)