{"slug": "claude-api-swap-tools-mid-session-without-cache-blowup", "title": "Claude API: Swap Tools Mid-Session Without Cache Blowup", "summary": "Anthropic has launched a beta feature for the Claude API that allows developers to add or remove tools mid-conversation without invalidating the prompt cache, addressing a long-standing pain point for agentic AI developers. The feature, enabled via the header 'anthropic-beta: mid-conversation-tool-changes-2026-07-01', works on Fable 5, Mythos 5, Opus 4.8, and Opus 5, and supports up to 512 tool additions per request. However, the request that introduces the tool change still incurs a cache miss, with the benefit applying to subsequent turns, and Anthropic recommends batching changes to maximize cost savings, especially given that cache reads on Fable 5.1 cost $0.25/M tokens versus $1.00/M on Fable 5.", "body_md": "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.\n\n## The Problem This Fixes\n\nUntil 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.\n\nThis 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.\n\n## How It Works\n\nEnable 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.\n\nInstead 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:\n\n```\nresponse = client.messages.create(\n    model=\"claude-fable-5-1-20260901\",\n    max_tokens=4096,\n    tools=[\n        # Declare all tools upfront\n        {\"name\": \"web_search\", \"description\": \"...\", \"input_schema\": {...}},\n        {\"name\": \"run_code\",   \"description\": \"...\", \"input_schema\": {...}},\n    ],\n    messages=[\n        *existing_conversation,\n        {\n            \"role\": \"system\",\n            \"content\": [\n                {\"type\": \"tool_removal\", \"tool\": {\"type\": \"tool_reference\", \"name\": \"web_search\"}},\n                {\"type\": \"tool_addition\", \"tool\": {\"type\": \"tool_reference\", \"name\": \"run_code\"}},\n                {\"type\": \"text\", \"text\": \"Switching to code execution phase.\"}\n            ]\n        }\n    ],\n    betas=[\"mid-conversation-tool-changes-2026-07-01\"]\n)\n```\n\nThe API supports up to 512 `tool_addition` blocks per request, so large tool catalogs are well within scope.\n\n## The Cache Tradeoff (Read This Part)\n\nThe 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.\n\nThe 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.\n\nAnthropic’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.\n\n## When to Use This\n\nThe 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.\n\nSecurity-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.\n\n## One More Beta Feature Worth Knowing\n\nAnthropic 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.\n\n## What to Watch For\n\nBoth 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.\n\nIf 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.", "url": "https://wpnews.pro/news/claude-api-swap-tools-mid-session-without-cache-blowup", "canonical_source": "https://byteiota.com/claude-api-swap-tools-mid-session-without-cache-blowup/", "published_at": "2026-09-09 06:12:08+00:00", "updated_at": "2026-09-09 06:28:36.973762+00:00", "lang": "en", "topics": ["ai-tools", "ai-infrastructure", "large-language-models"], "entities": ["Anthropic", "Claude API", "Fable 5", "Mythos 5", "Opus 4.8", "Opus 5", "Amazon Bedrock", "Google Cloud"], "alternates": {"html": "https://wpnews.pro/news/claude-api-swap-tools-mid-session-without-cache-blowup", "markdown": "https://wpnews.pro/news/claude-api-swap-tools-mid-session-without-cache-blowup.md", "text": "https://wpnews.pro/news/claude-api-swap-tools-mid-session-without-cache-blowup.txt", "jsonld": "https://wpnews.pro/news/claude-api-swap-tools-mid-session-without-cache-blowup.jsonld"}}