Tool result too large for the context window (MCP tool output exceeds 10,000 tokens warning, truncated or saved-to-file output, 'prompt is too long'): how do I add truncation, pagination and summaries to tools?

Cause: Everything a tool returns is placed in the model's context. A tool that dumps a full file, query result or API listing can use up the window, slow the agent down and crowd out the task. Clients protect themselves in different ways. Claude Code's MCP docs say it warns when MCP tool output passes 10,000 tokens, limits MCP output to 25,000 tokens by default (adjustable with the MAX_MCP_OUTPUT_TOKENS environment variable), and saves successful text results longer than 50,000 characters to a file instead of inlining them, unless the server raises that tool's own limit. Raising the client limit just moves the problem; better to fix the tool. Fix (best first): 1. Return less by default. Give tools a limit parameter with a sensible default, field selection, and filters, so the agent asks for what it needs rather than everything. 2. Paginate. Return a page plus a cursor or offset and a clear flag for more results. The MCP specification defines opaque cursor pagination for its list operations: the server returns a nextCursor, the client passes it back, page size is server-controlled, and clients must not parse or assume the format of cursors. Mirror that pattern in your own tools, and make cursors stable and invalid ones return a clear error. 3. Summarize or reference. For big payloads, return a short summary, counts and a handle (file path or id) plus a second tool to fetch a specific slice, search within it, or read a line range. 4. Truncate explicitly. If you must cut, say so in the output ("showing first 200 of 5,431 rows, call again with offset=200"), cut at record boundaries, and keep the beginning and end of logs where errors usually are. 5. Strip noise: drop HTML, base64, duplicated fields and verbose metadata before returning. 6. Only raise MAX_MCP_OUTPUT_TOKENS when a specific workflow truly needs large results and you accept the context cost. Verify: Call the tool against the biggest realistic input and check the output stays well under the client's warning threshold, includes an explicit more-results indicator, and that paging through returns every record exactly once. Sources: https://code.claude.com/docs/en/mcp https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination