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=[
{"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.