The Confession

When Protocol Creators Challenge Their Own Work

The Bloat Problem: Why Agents Get Dumber as You Add Tools

You followed the documentation. Connected 30 tools. Suddenly your agent takes 15 seconds to respond and gives worse answers than when it had 5 tools. You thought you were doing something wrong.

You weren't. The architecture was.

The assumed causes were all wrong. "We're not writing tool descriptions well enough." "Our prompts need better few-shot examples." "Maybe we need a bigger context window." "Probably need a more powerful model."

The actual cause: structural token bloat in MCP architecture. Not an implementation bug—a fundamental design characteristic.

"Tool descriptions occupy more context window space, increasing response time and costs. In cases where agents are connected to thousands of tools, they'll need to process hundreds of thousands of tokens before reading a request."

The Context Window: A Finite Resource

A context window is the total tokens an LLM can process in a single request. It includes everything: system prompt, tool definitions, conversation history, and the current query.

But here's the hidden cost: more context doesn't equal better results. More tokens to process means higher latency and higher costs. And quality degrades as relevant signal drowns in noise.

Problem 1: The Upfront Tool Definition Tax

Most MCP clients load all tool definitions into context immediately, before the agent even sees your query. No progressive discovery—everything upfront.

The math at scale becomes brutal.

Real-World Impact: The GitHub MCP Server

Simon Willison documented a striking example: the GitHub MCP server alone defines 93 tools and consumes 55,000 tokens. That's nearly 28% of Claude's 200,000-token context window for a single MCP integration.

Add 2-3 more popular MCP servers and you've consumed 80%+ of your context window before the agent starts working.

Problem 2: Exponential Intermediate Result Accumulation

Each tool call adds its result to the context. The next tool call must include all previous context. This isn't linear growth—it's exponential.

Worked Example: Google Drive → Salesforce Workflow

The waste is staggering: The transcript appears in context three times. First as the tool result from Google Drive (12,000 tokens). Second in the assistant's tool call to Salesforce (12,000 tokens). Third as referenced in the Salesforce confirmation.

Effective tokens processed: 24,000+ tokens for a single data transfer. As Anthropic notes: "Every intermediate result must pass through the model. In this example, the full call transcript flows through twice."

The Compounding Effect: Multi-Step Workflows

Consider a research agent analyzing 10 competitor websites. With MCP direct tool calling, the token accumulation becomes catastrophic.

Cost Impact: The Hidden Waste

What You See vs What Gets Billed

The Performance Degradation Mechanism

Why do more tools make your agent dumber? Four compounding effects:

The Scale Thresholds

When Does This Become Critical?

The tipping point arrives when:

• Token costs spike 10-50x unexpectedly
• Agent response times exceed user patience (>10 seconds)
• Agent quality noticeably degrades
• Production incidents occur due to context window overflow
• Finance asks: "Why is our AI bill $50,000 per month?"

"In cases where agents are connected to thousands of tools, they'll need to process hundreds of thousands of tokens before reading a request. This isn't just expensive—it fundamentally degrades the agent's reasoning capability."

Next chapter: Why code execution works better—the training distribution insight that explains everything.

Training Distribution Bias

Why LLMs Are Shakespeare Writing in Mandarin

"Making an LLM perform tasks with tool calling is like putting Shakespeare through a month-long class in Mandarin and then asking him to write a play in it. It's just not going to be his best work."

The Interface Must Match the Capability

The fundamental insight from Cloudflare cuts through all the technical complexity: LLMs excel at patterns they've seen millions of times and struggle with patterns seen thousands of times. This isn't about MCP being "bad engineering"—it's about interface-capability mismatch.

Shakespeare's capability was English literature—lifetime of training, native fluency, poetic mastery. Ask him to perform in Mandarin after a month-long class? He'd produce functional work, but nothing approaching his sonnets or plays. The training distribution simply wasn't there.

The same principle applies to LLMs. Code generation is their native fluency. Tool-calling schemas are their Mandarin crash course.

The Training Data Reality

Let's examine what LLMs actually learned during pre-training, because the numbers reveal why code execution works better.

Why This Matters: Pattern Matching vs Reasoning

Here's the uncomfortable truth about LLMs: they're not reasoning systems. They're pattern-matching engines that predict the next token based on training distribution. They perform best on patterns they've seen most frequently.

"In short, LLMs are better at writing code to call MCP, than at calling MCP directly."

The "Seen It Before" Advantage

Let's make this concrete with a side-by-side comparison: the same task (filtering a dataset) via MCP tool calling vs code generation.

Training Data Breakdown: What LLMs Actually Know

The Shakespeare Analogy Expanded

Cloudflare's analogy deserves deeper exploration, because it captures the fundamental mismatch perfectly.

Why Formal Schemas Don't Help

There's a persistent intuition that "formal schemas should be easier—they're structured, typed, validated." But structure doesn't overcome training distribution bias.

As Cloudflare notes: "If you present an LLM with too many tools, or overly complex tools, it may struggle to choose the right one or to use it correctly. As a result, MCP server designers are encouraged to present greatly simplified APIs."

The problem: "Simplified for LLMs" often means "less useful to developers."

Tool APIs get dumbed down to help LLM selection. Code APIs can be rich and expressive because LLMs handle code syntax naturally.

Training Distribution Defines Performance Ceiling

Here's the core principle that explains everything:

This wasn't obvious earlier because we assumed human software engineering principles would transfer to LLMs. We thought: formal systems are better than ad-hoc ones, so LLMs should prefer structured tool schemas over freeform code generation.

But LLMs aren't reasoning systems—they're pattern-matching systems. Give them patterns they've seen before. Millions of times. Not thousands.

Predictive Power of This Insight

Understanding training distribution bias gives us predictive power about when tool calling might catch up to code execution, and when code will remain superior.

This principle also generalizes to other AI interface decisions:

• Prompt engineering: Natural language descriptions beat rigid templates (models trained on real writing, not prompt formats)
• API design for agents: REST + JSON beats bespoke protocols (familiar web dev patterns in training)
• Error handling: Descriptive English messages beat error codes (models understand explanations better than numeric codes)

"We found agents are able to handle many more tools, and more complex tools, when those tools are presented as a TypeScript API rather than directly."

Next: The alternative pattern Anthropic and Cloudflare recommend—code-first architecture.

Code-First Architecture

The Pattern Anthropic and Cloudflare Actually Recommend

"With code execution environments becoming more common for agents, a solution is to present MCP servers as code APIs rather than direct tool calls."

┌──────────┐
│   User   │
│  Query   │
└────┬─────┘
     │
     ▼
┌──────────────────┐
│   LLM (Agent)    │  ← Minimal context (no tool schemas loaded)
│  Generates Code  │
└────┬─────────────┘
     │
     ▼ Code (Python/TypeScript)
┌──────────────────────────────┐
│   Secure Sandbox Environment │
│                              │
│  ┌────────────────────────┐ │
│  │  Generated Code Runs   │ │
│  │                        │ │
│  │  Imports APIs          │ │  ← MCP servers as backing transport
│  │  Processes Data        │ │
│  │  Loops, Filters, Maps  │ │
│  │  Stores Intermediate   │ │
│  └────────────────────────┘ │
│                              │
│  Data stays inside sandbox   │
└────┬─────────────────────────┘
     │
     ▼ Compact Summary
┌──────────────────┐
│   LLM (Agent)    │  ← Receives only final results (100-500 tokens)
│ Analyzes Results │
│ Responds to User │
└──────────────────┘

The Five Components of Code-First Architecture

servers/
├── google-drive/
│   ├── getDocument.ts
│   ├── updateDocument.ts
│   ├── createDocument.ts
│   ├── ...
│   └── index.ts
├── salesforce/
│   ├── updateRecord.ts
│   ├── createLead.ts
│   ├── ...
│   └── index.ts
└── slack/
    ├── postMessage.ts
    ├── getChannelHistory.ts
    ├── ...
    └── index.ts

// Agent generates this code, runs in sandbox:
const allRows = await gdrive.getSheet({ sheetId: 'abc123' });

// Data processing happens IN sandbox (not in LLM context)
const pendingOrders = allRows.filter(row => row.Status === 'pending');

// Further filtering/aggregation
const highValue = pendingOrders.filter(row => row.Amount > 1000);

// Return compact summary to LLM
console.log(`Found ${pendingOrders.length} pending orders`);
console.log(`${highValue.length} are high-value (>$1000)`);
console.log(`Top 5:`, highValue.slice(0, 5));

// LLM sees ~200 tokens (summary), not 50,000 (full dataset)

"The agent sees five rows instead of 10,000. Similar patterns work for aggregations, joins across multiple data sources, or extracting specific fields—all without bloating the context window."

let found = false;
while (!found) {
  const messages = await slack
    .getChannelHistory({
      channel: 'C123456'
    });
  found = messages.some(m =>
    m.text.includes('deployment complete')
  );
  if (!found)
    await new Promise(r =>
      setTimeout(r, 5000)
    );
}
console.log('Deployment received');

"When agents use code execution with MCP, intermediate results stay in the execution environment by default. This way, the agent only sees what you explicitly log or return, meaning data you don't wish to share with the model can flow through your workflow without ever entering the model's context."

// Agent generates code (no PII seen yet):
const sheet = await gdrive.getSheet({ sheetId: 'abc123' });

for (const row of sheet.rows) {
  await salesforce.updateRecord({
    objectType: 'Lead',
    recordId: row.salesforceId,
    data: {
      Email: row.email,    // PII flows through sandbox only
      Phone: row.phone,
      Name: row.name
    }
  });
}

// LLM sees only:
console.log(`Updated ${sheet.rows.length} leads`);
// (No actual PII in LLM context)

// Query Salesforce, save results locally
const leads = await salesforce.query({
  query: 'SELECT Id, Email FROM Lead LIMIT 1000'
});

const csvData = leads.map(l => `${l.Id},${l.Email}`).join('\n');
await fs.writeFile('./workspace/leads.csv', csvData);
console.log('Saved 1,000 leads to leads.csv for later processing');

// Later execution (different session):
const saved = await fs.readFile('./workspace/leads.csv', 'utf-8');
// Agent picks up where it left off

// Agent creates ./skills/save-sheet-as-csv.ts
import * as gdrive from '../servers/google-drive';

export async function saveSheetAsCsv(sheetId: string): Promise {
  const data = await gdrive.getSheet({ sheetId });
  const csv = data.map(row => row.join(',')).join('\n');
  const filename = `./workspace/sheet-${sheetId}.csv`;
  await fs.writeFile(filename, csv);
  return filename;
}

// Future sessions - agent reuses skill:
import { saveSheetAsCsv } from './skills/save-sheet-as-csv';
const csvPath = await saveSheetAsCsv('xyz789');
console.log(`Saved to ${csvPath}`);

"The engineering teams at Anthropic and Cloudflare independently discovered the same solution: stop making models call tools directly. Instead, have them write code."

"With code execution environments becoming more common for agents, a solution is to present MCP servers as code APIs rather than direct tool calls."

Code-First in Production

Two real-world investigations where agents wrote their own tools

Theory is nice. Let's see code-first architecture handle real production problems. Two investigations, two different domains, same pattern: the agent writes custom tools, processes gigabytes of data in a sandbox, and returns compact analyses. No MCP. No pre-defined tool schemas. Just code.

Case Study 1: Unit Number Investigation

Debugging a production booking system bug

The agent didn't use MCP. It wrote log_analyzer.py, backup_tracer.py, processed gigabytes of data in a sandbox, and returned a 2-page analysis. Zero tool schemas in context.

Why Code-First Worked Here

This investigation required processing gigabytes of data—far too much to load into any LLM's context window:

• → booking1.log: 709 real transactions (after filtering test traffic)
• → CSV backups: Web_History, Contact, Appointment, WorkOrder objects
• → Cross-referencing needed: grep appointment IDs across multiple CSVs on remote servers
• → Total raw data: gigabytes (impossible for LLM context)

Tools the Agent Created On-Demand

The agent didn't have pre-defined MCP tools. It wrote custom Python scripts as needed, each solving one part of the investigation:

What the LLM Actually Saw

The agent processed gigabytes of logs and backups in the sandbox. What crossed back into the LLM's context? A compact 2,000-token summary:

"The agent processed gigabytes. It returned a 2-page summary. No raw logs in context. No CSV dumps in context. Just analysis and findings."

MCP vs Code Execution: The Comparison

Key Lessons from the Investigation

Case Study 2: Autonomous Disk Architect (ADA)

When agents build their own investigation framework

The Agentic Approach: Plan-Act-Reflect-Recover

ADA is a closed-loop system demonstrating the full agent reasoning cycle. Unlike the unit-number investigation (which was a one-off debugging task), ADA is a reusable investigation framework that agents extend as they discover new patterns.

The Tool Evolution Pattern

Here's where ADA demonstrates code-first's advantage over MCP: the agent extended its own toolset as the investigation progressed.

"It is anti-MCP—writes its own Python as it goes. Creates its own tools, loops. I initially created some tools to cache files, but then let it create/extend more tools. Eventually it added about 12 options to my original 8 options, then created a 2nd cache by category, and more than 20 other tools."

Technical Sophistication

ADA showcases production-grade patterns that would be difficult to achieve with MCP's pre-defined tool approach:

Measurable Outcomes

Why MCP Couldn't Do This

ADA's tool evolution pattern is fundamentally incompatible with MCP's architecture:

The MCP Sweet Spot

When Standards Actually Win

MCP isn't dead—it's repositioned. There are specific use cases where MCP's standardization beats code-first flexibility. Here's when to choose each.

Not "MCP Bad, Code Good"

Both patterns have valid use cases. The key insight isn't dogmatic rejection of MCP—it's understanding when standardization adds value and when it becomes overhead.

Use Case 1: Testing and Browser Automation

Why MCP Playwright Wins

The Playwright MCP server provides standardized browser automation actions through a well-defined, stable interface. For testing workflows, this formal schema approach delivers real advantages over code generation.

When Formal Schemas Help

Use Case 2: Sub-Agent Orchestration

The sub-agent pattern is where MCP's standardization shines without triggering context bloat. Main agent delegates to specialized sub-agents, each with focused tool access.

Architecture: Contained Context Blast Zones

┌─────────────────┐
│   Main Agent    │  ← Minimal context (orchestration only)
│  (Orchestrator) │
└────────┬────────┘
         │
         ├──► Sub-Agent A (MCP: GitHub tools only)
         │    └─► Writes findings to github_analysis.md
         │
         ├──► Sub-Agent B (MCP: Database tools only)
         │    └─► Writes findings to db_report.md
         │
         └──► Sub-Agent C (MCP: Monitoring tools only)
              └─► Writes findings to alerts.md

Why This Works

"Sub agents: the whole wasting/blowing up context blast zone is minimized. You get a sub-agent to use the MCP tools, and writes to a MD file when it's finished. This, funnily enough, is more like writing a subroutine—very similar."

Benefits Over Monolithic Agent

• ✓ MCP standardization helps sub-agent swapping: Replace GitHub sub-agent with GitLab sub-agent without touching main orchestrator.
• ✓ Clear boundaries: GitHub sub-agent only accesses GitHub MCP server—no accidental cross-tool leakage.
• ✓ Governance: Can audit which sub-agent uses which tools, enforce least-privilege access.
• ✓ Parallelization: Run 3 sub-agents concurrently, each investigating different domain. Main agent waits for all MD files, then synthesizes.

Example Workflow: Infrastructure Health Analysis

Use Case 3: Enterprise Multi-Agent Orchestration

For large enterprises coordinating 10+ agents from different vendors, MCP's neutral interface provides governance and interoperability benefits that outweigh the performance tax.

Why MCP Helps at Enterprise Scale

Who This Applies To

• • Large enterprises: Fortune 500, regulated industries
• • Heterogeneous ecosystems: Agents from multiple vendors, built by different teams
• • Compliance/governance: Strict requirements for auditability, access control
• • <20% of teams: Most teams build focused, single-vendor agents and don't need this complexity

Trade-Off Accepted

Agent writes TypeScript code
  ↓
import { gdrive, salesforce } from './servers'
  ↓
./servers/* files use MCP protocol under the hood
  ↓
MCP handles: auth, connections, protocol negotiation
  ↓
Agent never sees MCP schemas in context

References & Sources

This ebook synthesizes research from primary sources (Anthropic, Cloudflare), industry practitioners (NVIDIA, Google Cloud, Docker), production sandbox providers (E2B, Daytona, Modal), and community analysis. All sources were accessed and verified between November 2024 and January 2025. Direct quotes appear throughout the chapters with inline citations.