# Claude API: Swap Tools Mid-Session Without Cache Blowup

> Source: <https://byteiota.com/claude-api-swap-tools-mid-session-without-cache-blowup/>
> Published: 2026-09-09 06:12:08+00:00

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](https://github.com/anthropics/claude-code/issues/81967) 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](https://platform.claude.com/docs/en/release-notes/overview) 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](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) covers the full block syntax and supported model list. The beta header is the only friction to entry.