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

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

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

![Claude Code tool lifecycle flow](/images/blog/progressive-disclosure-claude-code/tool-lifecycle.webp)

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

![AI coding tools industry convergence diagram](/images/blog/progressive-disclosure-claude-code/industry-convergence.webp)

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](https://blog.cloudflare.com/code-mode/)**  -  How TypeScript sandboxes beat MCP schema bloat
- **[Anthropic Advanced Tool Use](https://www.anthropic.com/engineering/advanced-tool-use)**  -  Tool search, programmatic calling, memory tools
- **[Cursor's Dynamic Context Discovery](https://cursor.com/blog/dynamic-context-discovery)**  -  46.9% token reduction in practice
- **[Claude Code Skills](https://code.claude.com/docs/en/skills)**  -  Implementation guide

## Watch the Video

<iframe width="100%" height="480" src="https://www.youtube.com/embed/DQHFow2NoQc" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen title="Progressive Disclosure in Claude Code"></iframe>

## 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.