Anthropic Mid-Conversation Tool Changes: No Cache Bust

Anthropic just fixed one of the more quietly painful constraints in the Claude API: you can now add or remove tools mid-conversation without invalidating your prompt cache. The feature is in beta as of July 2026, and if you’re building multi-step agents, it changes how you should think about tool architecture.

The Cache Problem Nobody Talked About Enough

Prompt caching in the Claude API saves up to 90% on input costs — cache reads run at 10% of the base token price. For long-running agents with substantial context, that difference is real money. But the cache has always had a hard constraint: the prefix order is fixed at tools → system → messages, and modifying anything near the root invalidates everything below it.

In practice, that meant changing your tool list mid-conversation was effectively banned for cache-conscious applications. Add a new tool? Full cache bust. You’d pay base price again, plus the write premium on the re-cached content. The workarounds were bad: either front-load every possible tool at conversation start (bloating context with capabilities the agent might never use), or accept the cost hit every time tools changed.

One team’s numbers illustrate the scale of the problem: switching from a full MCP tool library loaded at context start to lazy-loaded tools dropped per-request token usage from 77,000 to 8,700 — an 85% reduction. But without cache-safe tool changes, that lazy-loading pattern would still break caching the moment a new tool needed to surface.

What the Beta Adds

Mid-conversation tool changes work through two new content block types — tool_addition and tool_removal — that appear in the content array of a role: "system" message. You can mix these with regular text blocks in the same message.

The implementation has a specific structure. You declare all your tools upfront in the top-level tools array, but mark ones that shouldn’t be active yet with deferLoading: true. This tells the API: the definition exists, but don’t surface this capability in the current context window. When you want to add a tool mid-conversation, a system message with a tool_addition block referencing that tool name activates it from that point forward — without touching the prefix that the cache is keyed on.

# 1. Declare ALL tools upfront — deferred ones won't load into context yet
tools = [
    {"name": "search_docs", "deferLoading": False, ...},      # active from start
    {"name": "database_write", "deferLoading": True, ...},    # deferred — not yet visible
    {"name": "run_tests", "deferLoading": True, ...},         # deferred — not yet visible
]

# 2. Mid-conversation: add database_write via a system message
mid_turn_system = {
    "role": "system",
    "content": [
        {"type": "text", "text": "The user has approved the plan. You may now write to the database."},
        {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "database_write"}}
    ]
}

# 3. Include beta header in your API request
headers = {"anthropic-beta": "mid-conversation-tool-changes-2026-07-01"}

To opt in, include the beta header mid-conversation-tool-changes-2026-07-01 in your API requests. Supported models are Claude Fable 5, Mythos 5, Opus 4.8, and Opus 5. The Anthropic Python SDK added the MidConversationSystemBlockParam type in v0.105.0.

The Pattern This Enables

Progressive tool disclosure isn’t a new idea — it’s how the best-designed agent systems already work conceptually. The problem was that the API didn’t support it without paying a cache penalty. Now it does.

• Phase 1 — Exploration: Agent starts with read-only tools (search, file inspection, database reads). It builds a plan.
• Phase 2 — Execution: Once the plan is approved, add the write tool. database_query becomes database_write. The file reader gets write access.
• Phase 3 — Verification: Swap execution tools for test and deployment tools. Remove write access; add the ability to run tests and trigger CI.

This isn’t just about token efficiency. It’s a legitimate approach to agent security. Giving an agent access to a write operation before it’s in the write phase isn’t just wasteful — it’s a risk. Mid-conversation tool removal is equally important as addition: you can revoke capabilities the agent no longer needs. This maps cleanly to how Anthropic’s own prompt caching documentation frames cache-aware design — structure your context so that the stable parts come first.

Caveats Worth Knowing

It’s a beta, so behavior may change. A few specific things to check before building on this:

The Vercel AI SDK issue: There’s an open bug (vercel/ai #10018) where custom anthropic-beta headers get silently dropped due to overwrite behavior in the SDK middleware. If you’re using Vercel AI SDK, verify your beta headers are actually reaching the API before assuming the feature is active.

deferLoading is required: Tools you intend to add mid-conversation must be declared with deferLoading: true in the initial request. You can’t introduce a new tool definition mid-stream — plan your full tool inventory at conversation initialization.

Tool redefinition: If you need to change a tool’s schema (not just add or remove it), the process is: remove the old definition at the end of one request, then carry the conversation forward with the updated definition in tools on the next request. Mid-stream schema edits aren’t supported.

Why This Matters Now

Claude Workbench retires August 17. The experimental prompt tools API goes with it. Anthropic is consolidating everything onto the production API, and the production API is getting meaningfully better — fast. Mid-conversation tool changes is the kind of feature that sounds like a footnote in the API release notes but restructures how serious agent systems get built.

If your current agent architecture front-loads tools to avoid cache issues, it’s worth rebuilding around this pattern. The result is cleaner code, lower token costs, and meaningfully better security posture for your agent. Full documentation is in the mid-conversation system messages guide on the Claude platform docs.