MCP Tool Schemas Are Silently Eating Your Context Window

The key insight: your AI coding agent isn't running out of context because your codebase is huge—it's running out because every MCP server you've connected dumped its entire JSON schema into the conversation before you asked a single question.

The numbers from this teardown are stark: 255 tools across connected MCP servers ate 39,964 tokens, roughly 31% of a 128K context window, gone before the first prompt. That's not an edge case. It's the default behavior of MCP as most people wire it up, and it gets worse as you add more servers—repos, databases, ticketing systems, cloud APIs—because nobody thinks of tool schemas as a budget until they've blown through it.

Why full schema loading is the wrong default

MCP uses JSON Schema for tool validation, which is great for correctness but brutal for token efficiency. The problem isn't JSON Schema itself—it's that the protocol's naive implementation pattern is "load everything, always." Related research on MCP token overhead found tool definitions can consume 5–15x more tokens than a minimal schema representation, and that just 20–30 registered tools can occupy 15–30 KB of context before a user even sends a message.

That's the humbling part of the lesson here. It's tempting to think a 128K or 200K window solves the problem by brute force. It doesn't. It just delays the moment you notice you're paying for tokens that do nothing but sit in context, unused, competing with your actual task for the model's attention.

The fix: two-step discovery instead of eager loading

The practical pattern that keeps showing up across MCP optimization writeups is straightforward: stop sending full schemas up front. Instead:

1. Return compact tool summaries (name + one-line description) during discovery

2. Let the model pick a candidate tool based on the summary

3. Fetch the full JSON schema for that one tool only when it's about to be called

This is basically lazy loading applied to tool metadata, and it's the same instinct that made pagination and virtualized lists standard practice in frontend engineering. You don't render 10,000 rows because the user might scroll there eventually.

1# Naive approach: dump everything into context up front
2def get_tools_naive(mcp_servers):
3    all_schemas = []
4    for server in mcp_servers:
5        all_schemas.extend(server.get_full_schemas())  # expensive
6    return all_schemas  # 39,964 tokens before the user types anything
7
8# Two-step discovery: summarize first, expand on demand

The savings compound because most sessions only ever touch a handful of tools out of the hundreds registered. You're paying full schema cost for tools that never get invoked in that session.

Schema shape matters as much as schema count

Beyond discovery patterns, the schemas themselves are often bloated in ways that don't improve correctness:

• Deep nesting costs more tokens per unit of information than flat structures
• Redundant descriptions and examples in hot-path schemas add up fast across dozens of tools
• Overused enums, defaults, and required-field annotations look thorough but often duplicate what's already implied by naming conventions

None of this is exotic optimization—it's the same discipline you'd apply to trimming a bloated API response. The difference is that most people don't think to audit tool schemas the way they'd audit a REST payload, because MCP feels like plumbing you set up once and forget about.

Treat schema size as a budget, not an afterthought

The most transferable idea here isn't the specific 91% number—it's the mental model shift. Tool schema size should be tracked like latency or API cost: measured continuously, with regressions flagged before they ship. If you're building or maintaining an MCP gateway, that means:

• Logging total schema token count per session
• Alerting when a newly added server tool pushes you past a threshold
• Using semantic search over tool names/descriptions to shortlist candidates before expanding to full schemas, rather than exposing everything and hoping the model sorts it out

This last point matters more as MCP adoption grows. Teams are going to keep bolting on more servers—more databases, more internal tools, more third-party integrations—and if the default behavior stays "load every schema, every time," the token tax only grows. The 31%-of-context number in this piece isn't a ceiling; it's a snapshot of what happens with a moderate-sized tool catalog. Scale that catalog up and you're not losing a third of your context—you're losing most of it.

Why this matters: if you're running an AI coding agent with more than a handful of MCP servers connected, you are almost certainly paying a token tax you don't know about. The fix isn't exotic—it's applying discovery patterns and payload discipline that backend engineers already know from API design. Audit your tool count, measure your schema token footprint, and treat it as seriously as you'd treat a slow database query. The context window you save might be the one that lets the model actually solve your problem instead of just parsing metadata about how it could solve it.