Tool Context Management

Overview (confidence: high)

Tool context management groups the strategies for controlling how tool definitions and accumulated tool_result blocks consume the context window. Long-running agents with many tools or many turns can exhaust available context before the task finishes. Claude Platform documents four approaches, each targeting a different source of context pressure.

The Four Approaches (confidence: high)

Approach	What it reduces	When it fits
Tool search	Tool definitions loaded upfront	Large toolsets (20+ tools) where most tools aren’t needed every turn
Programmatic tool calling	tool_result roundtrips	Chains of tool calls that can execute as a single script
Prompt caching	Token cost of repeated tool definitions	Stable toolsets across many requests
Context editing	Old tool_result blocks in history	Long conversations where early results are no longer relevant

• Tool search keeps tool definitions out of the context window until requested. Instead of sending 50 tool schemas upfront, a single tool_search tool lets the model discover the rest on demand. Trades a small latency cost (one extra turn to look up a tool) for a large reduction in baseline context usage. See tool-search-tool.
• Programmatic tool calling collapses a sequence of tool calls into a single code block the model writes and Anthropic’s code execution sandbox runs. Rather than five roundtrips of tool_use/tool_result, the model emits one script calling all five functions; intermediate results never enter the conversation history.
• Prompt caching doesn’t reduce token count, but reduces what you pay on subsequent requests. If tool definitions are stable, cache once and reuse the cached prefix across thousands of requests. Right choice when the toolset is large but fixed.
• Context editing removes old tool_result blocks from history once they’ve served their purpose, trimming stale results without restarting the conversation.

Combining Approaches (confidence: high)

The four compose — a long-running agent might use tool search to keep the toolset lean, prompt caching to amortize the remaining definitions, and context editing to trim stale results as the conversation grows. No conflict in using them together.

A reasonable starting point for a high-volume agent:

• Enable prompt caching on tool definitions from day one. Cache writes carry a 25% markup over base input pricing, which pays back on the second request that hits the cache.
• Add tool search once the toolset grows past roughly 20 tools or baseline context usage becomes noticeable.
• Add context editing once conversations run long enough that early results become irrelevant.
• Consider programmatic tool calling for repetitive chains of small tool calls that could run as a single batch.

The Gateway Layer (confidence: medium)

The four approaches above are client-side — Claude decides what to load. A gateway between the client and the MCP servers adds a fifth, infrastructure-level control: the gateway decides what the client can even see. Bifrost (Maxim AI) exposes connected servers as a virtual filesystem of Python stubs; the model reads only what it needs and writes a short script executed in a sandboxed Starlark interpreter, so tool count stops being the dominant driver of per-message context. Virtual keys scoped at tool level mean unauthorized tools are never injected at all — an even stronger version of tool search, enforced by the gateway rather than the model.^[raw/prompts/articles/bifrost-mcp-gateway-claude-code-token-costs.md] This is the code-mode-orchestration pattern; it composes with the four client-side approaches rather than replacing them.

Measuring and Trimming Schema Cost (confidence: medium)

The size of the tool context is itself something you can audit and shrink at the source. A 4-step process gives you the numbers before you pick a strategy: list every server in ~/.claude/settings.json and project .claude/settings.json, count tools per server via its tools/list endpoint, estimate cost with tokens ≈ (tools × 200) + (description_chars ÷ 4), then sort to find the 2–3 heaviest offenders.

Client-side trims (independent of the four approaches above, which are about when and whether schemas load):

• Prune unused servers — any server with no tool invoked in ~2 weeks leaves the default config; re-add per project.
• Project-level configs over a bloated global one — keep ~/.claude/settings.json lean (e.g. filesystem only) and extend per project (e.g. postgres), so a database server never loads for a frontend task.
• Trim descriptions at the source — forked/owned servers can shorten verbose descriptions (“Reads the complete contents of a file at the specified path. Supports relative and absolute paths. Returns the file content as a string. Useful when you need to inspect, analyze, or modify…” → “Read file contents at path. Returns content as string.”). ~60–80 tokens/tool saved; 3,000–4,000/turn across 50 tools.
• Tool filtering / lazy loading — some server implementations expose a subset of tools via config flags or env vars; worth checking for the heaviest sources.
• Separate agents for separate tool sets — match minimal tool sets to tasks (a code-review agent doesn’t need web search); this is both a performance and a security improvement.

The same source confirms the underlying mechanics: schemas are re-sent on every message with no cross-turn caching at the API level, and each additional server also adds session-initialization round trips that slow startup independent of token cost.

Relationship to Other Concepts (confidence: medium)

This is the organizing frame for context pressure specific to tool use. It relates to — but is distinct from — general context-compaction (whole-session checkpointing) and claude-code-context-window (raw capacity facts). The four approaches are Claude Platform’s documented tooling; two-tier-search-architecture is a separate, broader retrieval pattern.

Related

tool-search-tool context-compaction prompt-caching token-usage-reduction claude-code-context-window code-mode-orchestration capability-as-method-calls

Open Questions

• Whether programmatic tool calling and context editing have the same public adoption as tool search, and how each behaves at production scale.
• How the four approaches interact when a toolset is both large and frequently changing (caching value erodes).
• Whether gateway-enforced tool visibility (Bifrost-style) offers measurable savings over client-side tool search when the toolset is already lean.
• Whether capability-as-method-calls stays context-cheap as capability count grows, since the model must still know the method names without schema discovery.

Sources

• raw/external/platform-claude-com-manage-tool-context-625d4da8.md
• raw/prompts/articles/bifrost-mcp-gateway-claude-code-token-costs.md
• raw/prompts/articles/mindstudio-claude-code-mcp-token-overhead.md