Progressive Disclosure: How Claude Code Cut Token Usage by 98%

In September 2025, CloudFlare published a blog post titled "Code Mode: The Better Way to Use MCP." It contained a single, devastating observation: we've been using MCP wrong.

The problem wasn't theoretical. When you load MCP tool definitions directly into an LLM's context window, you're forcing the model to see every available tool for every request, whether it needs them or not. Most of the time, those tools sit idle, burning tokens for nothing.

CloudFlare's insight was radical: models are excellent at writing code. They're not great at leveraging MCP. So why not let the model write TypeScript to find and call the tools it needs instead of embedding all the schemas upfront?

Three months later, Anthropic and Cursor both arrived at identical conclusions independently. The pattern has a name: progressive disclosure.

The Numbers Don't Lie

For the next layer of context, read Claude Code Agent Teams, Subagents, and MCP: The 2026 Playbook and Why Skills Beat Prompts for Coding Agents in 2026; they show how reusable agent knowledge turns one-off wins into repeatable workflow.

Anthropic's tool search feature shows the math clearly. Using a full MCP tool library with traditional context loading consumed 77,000 tokens. With tool search - discovering tools on demand - that dropped to 8,700 tokens. That's an 85% reduction while maintaining access to the entire tool library.

Accuracy improved too. In MCP evaluations:

• Opus 4: 49% → 74%
• Opus 4.5: 79.5% → 88.1%

Cursor reported similar wins. By implementing dynamic context discovery, they achieved a 46.9% reduction in total agent tokens. One week later, CloudFlare dropped their findings: a 98.7% reduction in token usage using TypeScript sandboxes instead of MCP schemas.

This isn't incremental optimization. This is a paradigm shift.

The Shift from GPUs to Sandboxes

Six months ago, the industry obsessed over inference speed and GPU efficiency. The conversation has moved. CloudFlare, Anthropic, Vercel, Cursor, Daytona, and Lovable are all converging on the same infrastructure: sandboxes, file systems, and bash.

The pattern is elegant. Instead of tokenizing every tool definition, you give agents three things:

1. A file system (read, write, search)
2. Bash (execute commands, run scripts)
3. Code execution (call MCP servers on demand)

The agent's job becomes simple: discover what you need, load it, use it. No context bloat. No unused tool schemas. No wasted tokens.

How to Build This in Claude Code

Claude Code implements progressive disclosure through skills. A skill is a YAML file with frontmatter (the summary) and references to actual scripts and markdown files (the implementation).

Here's the pattern:

---
name: "Web Research"
description: "Search and summarize web content using Firecrawl"
---

## Usage
Call this skill when you need current web information.

## Implementation
- [[firecrawl.sh]] - Core search and scraping
- [[research-template.md]] - Output format

The agent sees only the frontmatter in context (10-30 tokens). When it invokes the skill, it reads the full implementation - and only then. Scale to 1,000 skills, 10,000 skills, and the static context cost remains flat.

You can nest skills hierarchically. A skill can reference sub-skills. An agent can walk the directory structure, find what it needs, and load only that.

Advanced Tool Use: Memory and Code Execution

Anthropic's advanced tool use releases included two other pieces that complete the picture:

Programmatic Tool Calling: Tools don't return raw results anymore. They execute in a code environment, so the agent can inspect output, transform it, chain operations - all without leaving context.

Memory Tool: Not embeddings. Not vector databases. Just files. Markdown documents stored in the file system, read and updated as needed. Simple. Searchable. Manageable.

The principle extends to Claude Code. Instead of complex vector retrieval, read sections of files on demand. Update a memory.md when something matters. Let the agent grep, grep, find. It works.

What This Enables

Before progressive disclosure, agent tasks had to be small and contained. You watched token limits. You minimized tool use. You feared the context reset.

Now:

• Multi-hour workflows without context resets
• Hundreds or thousands of tool integrations available instantly
• Complex orchestration without orchestration logic - if the system can look up tools and skills, it handles complexity
• Autonomous systems that run for extended periods
• Context is no longer the bottleneck

The Experimental MCP CLI Flag

CloudFlare and Anthropic's approach inspired an experimental feature in Claude Code: the MCP CLI flag. When enabled, instead of embedding all MCP schemas in context, the model uses tool search to discover and invoke servers on demand.

Is it perfect? Not yet. It's actively being refined. But the direction is clear: zero context cost for tool discovery. Tens of thousands of tokens saved per request.

The Convergence

What's remarkable is that CloudFlare, Anthropic, Cursor, and others arrived here independently. No coordination. Same conclusion: tools as files, loaded on demand, bash is all you need.

This wasn't what anyone predicted six months ago. It's counterintuitive. Most of us assumed you'd load everything up front. But the data is overwhelming.

The industry is converging on the same answer: progressive disclosure works.

Build Boldly

If you've been cautious about Claude Code's scope because of context limits, stop. The bottleneck just moved. File systems, bash, and progressive disclosure unlock agents that can tackle ambitious, complex work without the orchestration overhead that held us back before.

Give the agent a file system. Get out of the way. Let it discover what it needs. The results speak for themselves.

Further Reading

• CloudFlare Code Mode - How TypeScript sandboxes beat MCP schema bloat
• Anthropic Advanced Tool Use - Tool search, programmatic calling, memory tools
• Cursor's Dynamic Context Discovery - 46.9% token reduction in practice
• Claude Code Skills - Implementation guide

Watch the Video

Frequently Asked Questions

What is progressive disclosure in Claude Code?

Progressive disclosure is a pattern where AI agents discover and load tools on demand rather than having all tool definitions embedded in the context window upfront. Instead of burning tokens on unused tool schemas, the agent uses a file system, bash, and code execution to find and invoke only the tools it needs for each specific task.

How much does progressive disclosure reduce token usage?

The reductions are dramatic. Anthropic reported an 85% reduction (from 77,000 tokens to 8,700 tokens) using tool search. CloudFlare achieved a 98.7% reduction using TypeScript sandboxes instead of MCP schemas. Cursor reported a 46.9% reduction in total agent tokens with dynamic context discovery.

Why does progressive disclosure improve accuracy?

When models see fewer irrelevant tools in context, they make better decisions about which tools to use. Anthropic's evaluations showed accuracy improvements from 49% to 74% on Opus 4, and from 79.5% to 88.1% on Opus 4.5 after implementing tool search.

How do I implement progressive disclosure in Claude Code?

Use skills - YAML files with frontmatter summaries and references to implementation files. The agent sees only the frontmatter (10-30 tokens) in context. When invoked, it reads the full implementation. You can nest skills hierarchically and scale to thousands without increasing static context cost.

What three things do agents need for progressive disclosure?

Agents need: (1) a file system to read, write, and search, (2) bash to execute commands and run scripts, and (3) code execution to call MCP servers on demand. This lets the agent discover, load, and use tools dynamically instead of loading everything upfront.

Does progressive disclosure work with MCP servers?

Yes. Instead of embedding all MCP schemas in context, you can use tool search to discover and invoke MCP servers on demand. Claude Code has an experimental MCP CLI flag that implements this pattern, saving tens of thousands of tokens per request while maintaining access to the full tool library.

What does progressive disclosure enable that wasn't possible before?

It enables multi-hour workflows without context resets, hundreds or thousands of tool integrations available instantly, complex orchestration without orchestration logic, and truly autonomous systems that run for extended periods. Context is no longer the bottleneck for ambitious agent tasks.