Does a context tool actually reduce agent token usage, or add more on top of what Claude Code already uses?
Both happen, and the net depends on the task. The tool adds its tool names, server instructions and each answer it returns, which rides along on every later turn. It removes the file reads, searches and extra turns the agent would have spent finding the same facts. On tasks that need history from outside the repo the removal is larger. On tasks that need none, it only adds.
A context tool does both: it adds to agent token usage on every request, and it can remove far more than it adds. Your bill goes down only if the tool's answer is smaller than the exploration it replaces and the task ends in fewer turns. Exploration tokens are the tokens an agent spends finding things out for itself: grep output, file contents, search results, and the extra turns that carry them. A tool that returns a short, cited answer swaps a large pile of them for a small one. A tool that returns raw search results, or that the agent calls and then ignores, just adds to the pile.
| What the context tool adds | What it can remove | |
|---|---|---|
| At session start | Tool names and server instructions | Nothing |
| Per call | One answer, re-sent on every later turn | Several file reads, greps and searches |
| Per task | One request per call | Turns spent exploring and retrying |
What a context tool adds to each request#
Claude Code "sends your full conversation with every request," and each tool call adds "another request carrying that batch of tool results" (Claude Code costs docs). Anything a new tool adds is paid again on each one.
There are three separate costs, and their sizes differ considerably.
- Tool definitions are the names, descriptions and input schemas of a server's tools. Claude Code defers them by default. Its docs say "only tool names and server instructions load at session start" (Claude Code MCP docs).
- The tool-use system prompt is a short prompt Anthropic adds whenever any tool is present. It is 286 tokens on Claude Sonnet 5.5 (Claude pricing). Claude Code always has tools available, so this cost already exists.
- Tool results are the text a tool sends back. The same pricing page lists
tool_resultblocks among the tokens a request is billed for. An answer that arrives on turn 3 of a 20-turn task is sent 17 more times.
Tool results are where the cost sits, and the startup overhead is small by comparison.
What it can take away#
The savings come from investigation the agent no longer performs. For example, without outside context an agent answers "why does this service retry five times?" by reading code, grepping for callers, opening the test file and guessing. Every result lands in the conversation and is re-sent on every later turn, and every extra turn also re-sends everything that came before it.
So the saving compounds in two ways: fewer results means less text riding along, and fewer turns means fewer trips for all of it.
We measured both on 2026-04-16. The test setup held the prompt, the model (claude-sonnet-4-6) and the repository fixed, and changed one thing: Unblocked attached or not. With it, the agent took 19 turns instead of 50 and made 29 tool calls instead of 80. Output tokens fell 55 percent, a sharper reduction than input. The baseline "grep-walked the stack, opened dozens of files" and did not finish inside its turn budget (same prompt, same model, different context). That was one run of one task, so treat it as an example rather than a benchmark, though the numbers do show where the saving came from: turns that never happened.
Prompt caching softens both sides of the calculation. On Sonnet 5.5 a cache hit costs 5 percent of the base input price, $0.10 per million tokens against $2 (Claude pricing). New text is billed at the cache-write rate when it is first stored, $2.50 per million on the 5-minute cache, which is above the base price (same pricing page). After that it costs the hit rate on each later turn, so size still decides it: a 4,000-token file read and a short answer pay the same rates, on very different token counts.
When it costs more than it saves#
The tool increases total usage in four situations.
- The task needs no outside context. For instance, renaming a variable needs nothing from Slack or old PRs, so calling the tool there is pure overhead.
- The tool returns raw results. Ten Slack threads and two Confluence pages leave the sorting to the agent. Claude Code warns when one MCP result passes 10,000 tokens and caps it at 25,000 by default (Claude Code MCP docs, above). A capped result is still a large result, re-sent every turn after it arrives.
- The agent calls the tool, then explores anyway. You pay for both. A common cause is an answer without citations, which leaves the agent verifying everything independently. See how to make Claude call a context MCP without editing CLAUDE.md.
- Tool search is off. With
ENABLE_TOOL_SEARCH=false, "all MCP tools loaded upfront, no deferral" (Claude Code MCP docs, above). Our MCP token budget autopsy shows what that costs per server.
Independent research on tool selection points the same direction. A March 2026 paper found that sending every tool to the model "results in substantial token overhead, increased costs, reduced accuracy." Sending only the relevant ones cut tool-related tokens by 99.6 percent (Mudunuri et al., arXiv 2603.20313).
What makes a context tool land on the saving side#
The shape of the result decides most of it. The MCP specification lets a tool return a short text answer plus resource links, a URI "that can be subscribed to or fetched by the client" (MCP specification). The agent then retrieves a full document only when it actually needs one. The spec also asks servers to list tools in a fixed order, because that "improves LLM prompt cache hit rates when tools are included in model context."
Unblocked is designed around that response shape. Its main tool, context_research, runs "multi-source research across code, PRs, docs, issues, and messaging" and "returns a synthesized answer with citations", and context_get_urls fetches what a citation points to (Unblocked MCP docs). The reading across code, PRs, issues, docs, Slack and incidents happens on the server, so it never enters the agent's context window. The same server answers Claude Code, Cursor, GitHub Copilot and JetBrains IDEs.
How to tell which side you are on#
The quickest check on context tool token usage is in Claude Code itself: /context shows what fills the window, and /usage attributes recent usage to individual MCP servers. That attribution counts only "the requests that consumed one of its tool results" (Claude Code costs docs, above). If a context server shows a large share and your tasks still take as many turns as before, it is adding tokens instead of replacing exploration.
For a definitive answer, run the same tasks with and without the tool and compare priced tokens and turns per task. Our answer on proving a context tool's token savings lays out a 20-task paired test. For the wider picture of where agent tokens go, see why AI agents burn tokens.
