Claude API: Swap Tools Mid-Session Without Cache Blowup

Anthropic just shipped something agentic AI developers have been asking for since multi-step agents became mainstream: you can now add and remove tools mid-conversation without destroying your prompt cache. It’s in beta, but it works on Fable 5, Mythos 5, Opus 4.8, and Opus 5 right now — and there’s a cache cost tradeoff you need to understand before you ship it to production.

The Problem This Fixes

Until this feature shipped, the Claude API treated your tool list as immutable for the lifetime of a session. Change tools[] between turns and you invalidated the prompt cache — every cached token in the conversation prefix got discarded and re-ingested at full price. For a long-running agent sitting on 50K–100K tokens of context, that’s a meaningful cost hit every time the task scope shifted.

This showed up in production in ugly ways. Teams using Set data structures to manage tool lists got non-deterministic ordering, which silently killed caching turn after turn. There’s a real GitHub issue on the anthropics/claude-code repo documenting exactly this pain. The new feature gives developers a controlled mechanism to change the tool set without blowing everything up.

How It Works

Enable it by passing a single beta header: anthropic-beta: mid-conversation-tool-changes-2026-07-01. The feature works across the Anthropic API, Amazon Bedrock, and Google Cloud.

Instead of re-sending a modified tools array, you inject a role: "system" message with tool_addition and tool_removal content blocks — each referencing a single tool by name. Declare all tools upfront in the top-level tools array, then selectively activate or deactivate them per turn:

response = client.messages.create(
    model="claude-fable-5-1-20260901",
    max_tokens=4096,
    tools=[
        # Declare all tools upfront
        {"name": "web_search", "description": "...", "input_schema": {...}},
        {"name": "run_code",   "description": "...", "input_schema": {...}},
    ],
    messages=[
        *existing_conversation,
        {
            "role": "system",
            "content": [
                {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "web_search"}},
                {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "run_code"}},
                {"type": "text", "text": "Switching to code execution phase."}
            ]
        }
    ],
    betas=["mid-conversation-tool-changes-2026-07-01"]
)

The API supports up to 512 tool_addition blocks per request, so large tool catalogs are well within scope.

The Cache Tradeoff (Read This Part)

The official docs say this feature works “while preserving the prompt cache” — a phrase that can be misread. Here’s what it actually means: the mechanism preserves the cache for subsequent turns after a tool change. The specific request where you inject a tool change system message still incurs a cache miss. The tools array sits early in the hashed request prefix, so modifying it triggers invalidation for that turn.

The win is forward-looking: turns that come after the change can cache against the new prefix. Contrast this with the old approach, where modifying tools[] at the top level would shatter the cache for every future turn in the session.

Anthropic’s practical guidance: batch your tool changes where possible. Don’t swap tools turn-by-turn if you can group them into a single transition. On Fable 5.1, cache reads cost $0.25/M tokens — down from $1.00/M on Fable 5. That 75% cut makes cache preservation worth more than it used to be, which makes this feature more economically significant than it would have been six months ago.

When to Use This

The pattern shines in phase-based agents. A research-to-implementation workflow naturally breaks into distinct phases with different tool requirements: web search and document retrieval in phase one, code execution and file I/O in phase two, test runners and linters in phase three. Previously, supporting this cleanly meant separate sessions or accepting cache blowups. Now you can thread a single session through all three phases with surgical tool swaps.

Security-conscious developers will also find value here: drop high-privilege write tools after an agent completes a sensitive operation and keep only read-only tools for the rest of the session — without restarting the conversation and losing context.

One More Beta Feature Worth Knowing

Anthropic shipped per-message effort changes alongside this feature, under a different header: mid-conversation-output-config-2026-07-01. This lets you dial reasoning effort up or down per turn without touching the prompt cache. High effort for complex reasoning steps, low effort for simple retrieval — in the same session. The two features compose well together for sophisticated agent architectures.

What to Watch For

Both features are in beta. API contracts can change, though the additive nature of the change — new content block types rather than modifications to existing ones — makes breaking changes unlikely. Monitor the Anthropic platform release notes for stable graduation.

If you’re already building production agents on Claude and you’ve been working around the immutable-tools constraint, this is worth testing now. The official documentation covers the full block syntax and supported model list. The beta header is the only friction to entry.