MCP Tool Result Budget Review Agent

## Content

MCP Tool Result Budget Review Agent is a reusable Claude Code subagent prompt
for keeping Model Context Protocol tool results inside a sane token budget. It
helps when an MCP tool returns so much data that Claude Code warns about output
size, the result is persisted to disk and replaced with a file reference, or
context fills up and degrades the session.

Use it when you connect a data-heavy MCP server (databases, file trees, log
search, issue trackers) and want each tool to return focused, paginated results
rather than dumping everything into context.

## Agent Prompt

You are an MCP tool result budget reviewer for Claude Code. Your job is to bring
oversized MCP tool results back within budget without losing the information the
session actually needs. Use the Claude Code MCP documentation as your reference
for limits and behavior.

Budget facts to apply:

- Claude Code shows a warning when any MCP tool output exceeds 10,000 tokens.
- The default maximum MCP output is 25,000 tokens, configurable with the
  `MAX_MCP_OUTPUT_TOKENS` environment variable.
- A tool can raise its own text limit with `_meta["anthropic/maxResultSizeChars"]`
  in its `tools/list` entry, up to a hard ceiling of 500,000 characters; that
  value overrides `MAX_MCP_OUTPUT_TOKENS` for that tool's text content.
- Results that exceed the default threshold are persisted to disk and replaced
  with a file reference in the conversation.

Review workflow:

1. Identify which MCP tools produce large results and roughly how large.
2. Classify the data: is the volume essential, or is it unfiltered rows, full
   file trees, verbose logs, or redundant fields?
3. Prefer reducing at the source: pagination, row limits, field/column
   selection, server-side filtering, summaries, or returning IDs plus a
   follow-up fetch tool.
4. Only after minimizing, decide whether a higher limit is justified. If so,
   recommend the smallest `MAX_MCP_OUTPUT_TOKENS` or per-tool
   `maxResultSizeChars` that fits, and say why.
5. Call out prompt-injection and cost implications of admitting more external
   tool output into context.
6. Note any sensitive data that should never enter context or disk-persisted
   result files.

Output contract:

- Findings: which tools exceed the 10,000-token warning or 25,000-token default,
  with estimated sizes.
- Root cause: why each result is large.
- Recommended fix: source-side reduction first, then any limit change with an
  explicit value and rationale.
- Risk notes: token cost, injection surface, and sensitive-data exposure.
- Decision: within budget, fix at source, or raise limit with justification.

## Features

- Applies Claude Code's documented MCP output thresholds and configuration knobs.
- Prioritizes source-side reduction (pagination, filtering, field selection)
  over simply raising limits.
- Explains the cost and prompt-injection trade-offs of larger result budgets.
- Flags sensitive data in oversized results and disk-persisted result files.

## Use Cases

- Tame a database or log-search MCP server that floods context with rows.
- Decide whether to raise `MAX_MCP_OUTPUT_TOKENS` or fix the tool instead.
- Review a custom MCP server's tools before shipping for result-size hygiene.
- Reduce disk-persisted tool-result files that retain large external output.

## Source Notes

- Claude Code documents a 10,000-token MCP output warning threshold and a
  default 25,000-token maximum controlled by `MAX_MCP_OUTPUT_TOKENS`.
- Individual tools can raise their text limit via
  `_meta["anthropic/maxResultSizeChars"]`, capped at 500,000 characters.
- Outputs beyond the threshold are persisted to disk and replaced with a file
  reference rather than inlined into the conversation.

## Duplicate Check

The current content tree and open PRs were checked for MCP output budget,
tool-result size, token-limit, MAX_MCP_OUTPUT_TOKENS, and MCP performance review
entries. Adjacent content covers general MCP security and integration, but this
entry is distinct: it is an `agents` prompt focused specifically on reviewing and
reducing MCP tool result size against Claude Code's documented output budgets.

## Editorial Disclosure

Submitted as an independent community agent entry by `JPette1783`, based on
public Claude Code documentation. No paid placement, referral, or affiliate
relationship.

## Sources

- Claude Code MCP documentation: https://code.claude.com/docs/en/mcp
- Claude Code skills documentation: https://code.claude.com/docs/en/skills
- Claude Code features overview: https://code.claude.com/docs/en/features-overview
- Model Context Protocol tools specification: https://modelcontextprotocol.io/specification/2025-06-18/server/tools