[DOCS] MCP docs missing `_meta["anthropic/maxResultSizeChars"]` result-size override

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

MCP output limits and warnings plus MCP server author guidance for large tool results

Current Documentation

The MCP docs currently say:

When MCP tools produce large outputs, Claude Code helps manage the token usage to prevent overwhelming your conversation context: 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

The same page uses large schema output as an MCP use case:

Show me the schema for the orders table

The Agent SDK docs currently describe tool annotations like this:

Tool annotations are optional metadata describing how a tool behaves. Pass them as the fifth argument to tool() helper in TypeScript or via the annotations keyword argument for the @tool decorator in Python. All hint fields are Booleans.

And the TypeScript reference currently shows:

type CallToolResult = { content: Array<{ type: "text" | "image" | "resource"; // Additional fields vary by type }>; isError?: boolean; };

No current documentation explains _meta["anthropic/maxResultSizeChars"] or the 500K override mentioned in changelog v2.1.91.

What's Wrong or Missing?

Changelog v2.1.91 added a per-result persistence override for MCP tool results via _meta["anthropic/maxResultSizeChars"], but the docs still only describe the global MAX_MCP_OUTPUT_TOKENS setting.

A. The override itself is undocumented

There is no user-facing documentation that this _meta key exists, what it does, or when to use it.

B. The return shape is unclear for MCP server authors

The SDK docs describe boolean ToolAnnotations and a minimal CallToolResult shape, but they do not show where this Anthropic-specific _meta field belongs in a returned tool result.

C. The limit and intended use cases are missing

The docs do not explain that the override can raise result persistence up to 500,000 characters for cases like large database schema output, nor how it relates to the existing global token limit docs.

Suggested Improvement

Add a short subsection to https://code.claude.com/docs/en/mcp for per-result large-output handling.

That update should:

• document _meta["anthropic/maxResultSizeChars"] as a supported MCP tool-result override
• explain that it can raise persistence for specific results up to 500,000 characters
• clarify how this differs from MAX_MCP_OUTPUT_TOKENS (global token limit vs per-result persistence override)
• include one concrete example for a large structured result such as a database schema
• add Agent SDK cross-references showing where _meta belongs in returned tool results for TypeScript and Python MCP tools

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/mcp | 611-625, 981-1004 | Database-schema example and the current output-limits section, which only documents MAX_MCP_OUTPUT_TOKENS |
| https://code.claude.com/docs/en/env-vars | 166 | Global MAX_MCP_OUTPUT_TOKENS reference; no per-result override |
| https://platform.claude.com/docs/en/agent-sdk/custom-tools | 270-281 | Tool annotations docs say all hint fields are booleans and list only the standard hint fields |
| https://platform.claude.com/docs/en/agent-sdk/typescript | 70-80, 2273-2284 | ToolAnnotations and CallToolResult references omit _meta["anthropic/maxResultSizeChars"] |
| https://platform.claude.com/docs/en/agent-sdk/python | 111-118 | Python tool reference documents annotations but not the result metadata override |

Total scope: 5 pages affected

Source: Changelog v2.1.91

Exact changelog entry:

Added MCP tool result persistence override via _meta["anthropic/maxResultSizeChars"] annotation (up to 500K), allowing larger results like DB schemas to pass through without truncation