Claude Code Token Optimization: Context, Tools, and Compaction Cost
A source-backed engineering report on where Claude Code spends tokens and the documented controls, tool search, prompt caching, CLAUDE.md discipline, compaction, and subagents, that cut waste without hiding project context.
The highest-value controls are visible in the docs.
The report keeps only source-backed metrics and treats savings as workload-dependent unless the cited source gives a number.
Tool definitions can consume this many tokens for 50 tools.
Loads relevant tools on demand instead of carrying every schema.
Rewards stable reusable context and disciplined project memory.
Summarizes long conversations when old detail stops paying rent.
Token waste usually comes from repeated context, not one bad prompt.
Claude Code token usage is dominated by repeated context: instructions, project memory, tools, MCP surfaces, prior messages, file content, command output, web content, images, and compaction summaries.
Short durable context, scoped tools, measured output, and deliberate compaction beat blanket context hoarding.
Always-on instructions
Large memory files and broad project docs are paid for repeatedly.
Scoped surfaces
Expose only the tools, files, and context needed for the current workflow.
Measure first
Usage commands and context inspection prevent guesswork.
Tool Search Changes the Math
Large tool libraries should be discoverable, not permanently loaded.
Anthropic describes the context pressure directly: 50 tools can consume 10K-20K tokens. Tool search reduces that pressure by discovering relevant tools on demand.
The practical levers are small enough to operate.
Discovers and loads needed tools on demand.
Use for large custom tool or MCP catalogs.
Search matching uses tool names and descriptions.
Make tools searchable and specific so fewer retries are needed.
Project memory is loaded into context at session start.
Keep base memory short and move workflows into on-demand skills.
Tool definitions can consume this many tokens for 50 tools.
Do not convert this into a universal savings percentage. The report keeps the number tied to its original source and context.
Controls map to operating decisions.
| Lever | Documented behavior | Operating decision | Source |
|---|---|---|---|
| Tool search | Discovers and loads needed tools on demand. | Use for large custom tool or MCP catalogs. | [claude-tool-search], [anthropic-tool-search] |
| Tool names and descriptions | Search matching uses tool names and descriptions. | Make tools searchable and specific so fewer retries are needed. | [claude-tool-search] |
| CLAUDE.md discipline | Project memory is loaded into context at session start. | Keep base memory short and move workflows into on-demand skills. | [claude-costs] |
| /compact and /clear | Compaction and clearing are documented context controls. | Compact at milestones and clear after commits or task changes. | [claude-costs] |
| Preprocessing hooks | Command output can be filtered before it enters context. | Trim noisy logs and long tool results. | [claude-costs] |
Lowest-waste default workflow
The operating pattern keeps useful context close and noisy context out of the recurring prompt path.
Check usage
Check cost or usage commands before and after large tasks in the installed Claude Code build.
Use tool search
Use tool search for large tool catalogs and keep MCP servers project-scoped.
Keep CLAUDE.md lean
Keep CLAUDE.md stable and concise so prompt caching can help.
Read targeted ranges
Read targeted line ranges and symbols instead of whole files.
Filter noisy logs
Filter tests and build logs to failing cases.
Claims Removed or Downgraded
The older report included fixed token counts for Claude Code hidden prompts, exact MCP totals, and version-specific behavior claims. This version keeps numbers only where Anthropic documentation supports them.
No fabricated stats, no fake case studies, no universal savings claims without a source-backed measurement path.
[claude-costs]
Claude Code cost docs
[claude-tool-search]
Claude Code tool search docs
[anthropic-tool-search]
Claude API tool search docs
Make Claude Code cost a managed system.
Move from anecdotal token pressure to a source-backed operating model for tool search, context discipline, compaction, and measured engineering workflows.
A practical report for teams operating Claude Code at scale.
Bring the controls into the room.
The full report turns the research into decisions your engineering team can operate.
- Source-backed cost and context controls
- Tool search and compaction workflow
- Decision matrix for day-to-day use