[trace-mcp]

How to reduce Claude Code token usage

Token cost in Claude Code is not mostly the code you show it. It is the code it reads looking for the code it needs, plus everything it re-reads on later turns because the earlier result scrolled out of reach.

Below are seven tactics ordered by how much they moved the number in our own measurements, with the numbers we actually have and honest gaps where we do not have any. Several of them have nothing to do with trace-mcp; those come first, because they are free.

1. Stop paying for exploration twice

The dominant cost on a repository too large to fit in context is search, not reading. An agent asked “where is rate limiting handled” will open a dozen candidate files before it finds the one that matters, and every one of those reads stays in the transcript for the rest of the session.

Two cheap habits fix most of it:

2. Read symbols, not files

Reading a 500-line file to change five lines pays for 495 lines you did not need — and pays again on the next turn if the result gets re-read. The pattern that works is outline → one symbol → edit.

This is what trace-mcp’s get_outline and get_symbol exist for: the first returns signatures with line numbers, the second returns exactly one function or class. Claude Code’s native Read supports offset/limit and will do the same job once you know the range, which is precisely what the outline gives you.

3. Audit your MCP tool surface — including ours

This is the tactic most people never check, and it can dominate everything else.

Every MCP server you connect injects its tool schemas into the context at session start, before you ask anything. Three servers with large surfaces can cost tens of thousands of tokens on every single session, whether or not you call any of them.

Measured on our own server, August 29, 2026: trace-mcp’s shipped default is the minimal (28 tools) preset — ~9.8K tokens of tools/list plus ~1.75K tokens of server instructions, ~11.6K in total, which is the number to budget against because a client pays both. (full (169 tools) is ~49.9K + ~2.1K if you opt into it.) That is still not cheap, and we say so on our own comparisons page — the leanest peers in this category advertise ~1.9K and ~7K tokens by shipping a small default surface with the rest opt-in.

What to do about it:

4. Pick the output format per tool, not globally

Encoding matters, but not uniformly. Our measurements (scripts/bench-toon.ts, gpt-tokenizer with the cl100k_base encoding, against a snapshot of this repo’s own index — 1,501 files, 9,467 symbols):

Payload shape Format change Measured
Flat, same scalar fields per row (query_decisions) JSON → TOON +31.4%
Flat symbol records (get_outline) JSON → TOON +28.8%
Flat item records (search) JSON → TOON +16.4%
Nested object per row (find_usages) JSON → TOON −17.5%
Inner array per row (search_text) JSON → TOON −25.5%
Repeated long paths (search_text) flat → grouped by file +20.8%

The rule underneath: compact tabular encodings win when every row has the same scalar columns, and lose the moment a row contains a nested object or an inner array. Full method and the breakeven curve are on the TOON savings page.

5. Prefer one structural query over many reads

“What breaks if I change this function” answered by reading files is an open-ended crawl: find the definition, grep for the name, open each hit, follow each of those. Answered from a dependency graph it is one call that returns the affected symbols and the tests covering them.

The same applies to “who calls this”, “which tests cover this”, and “what does this module import”. These are graph traversals. If your tooling can compute them, the token cost is the answer’s size rather than the search’s size — and the search is the expensive part.

6. Compact, don’t clear

Clearing the context feels like saving tokens and usually is not: the agent re-derives what it lost, and re-derivation costs more than the transcript did. Compaction — or simply writing a short summary of conclusions and starting fresh from it — keeps the findings while dropping the raw tool output that produced them.

7. Index once, query many times

The reason a code index pays off is amortisation. Building it costs something once; every query afterwards is cheap and scoped. A packing tool that concatenates your repository into a prompt pays its full cost on every refresh, which is fine for a one-shot question and expensive across a long session.

That is the trade in one line: if your session is a single question about a small repository, pack it. If it is many turns against a repository too large to fit in context, index it. We wrote up the specifics against the main packing tool in trace-mcp vs Repomix.

What we claim, and what we have measured

Our homepage claims ~40–50% fewer tokens on average across real agent workflows. That is our own aggregate figure from our own usage, not a third-party benchmark, and it varies enormously with repository size and session shape — on a small repo that fits in context it is roughly zero. The numbers on this page that come with a script and a tokenizer are the ones in section 4; those you can reproduce.

We do not currently have a published, independently reproducible end-to-end benchmark, and at least one competitor does. We would rather write that here than quietly imply otherwise.

FAQ

What actually uses the most tokens in Claude Code? Repeated full-file reads during exploration, the MCP tool schemas advertised at session start, and long transcripts carrying every earlier tool result forward — in that order on large repositories.

Do MCP servers increase or decrease token usage? Both. Each pays a fixed up-front schema cost and then saves per query if its answers are narrower than the reads they replace. A large surface with few calls per session is a net loss. Measure it with tools/list.

Does asking for an outline instead of reading the file really help? Yes, when you only need structure. Outline first, then read the specific symbol or line range — instead of reading 500 lines to edit five.

Does output format affect token cost? Measurably, per payload shape. TOON beat JSON by 31.4% on query_decisions and 28.8% on get_outline, and lost by 17.5% and 25.5% on find_usages and search_text. It is a per-tool decision.

Is clearing context the same as saving tokens? No — clearing forces re-derivation, which usually costs more. Compact, or hand off a short written summary.

Next steps

Last updated: August 30, 2026