---
title: "Mid-Conversation Tool Changes: Anthropic's Fix for the Other Prompt-Cache Killer"
date: 2026-08-06
tags: ["claude-api","prompt-caching","agentic-workflows","tool-use","opus-5","verification"]
categories: ["AI Tools","Agentic Workflows"]
summary: "A beta spotted on aggregator sites but absent from Anthropic's official Claude Code changelog turns out to be real: mid-conversation tool changes, documented directly on the Claude Developer Platform, let you add or remove tools mid-session via tool_addition/tool_removal blocks without invalidating the prompt cache — a beta introduced with Opus 5, also available on Fable 5, Mythos 5, and Opus 4.8."
---


![Mid-Conversation Tool Changes: Anthropic's Fix for the Other Prompt-Cache Killer](/images/mid-conversation-tool-changes-claude-api.png)

Yesterday's [Claude Code v2.1.221-222 changelog piece](/posts/claude-code-v2-1-221-222-worktree-isolation-fix/) closed with an honest admission: a "mid-conversation tool-switching beta" had turned up in a research sweep, credited to Fable 5, Mythos 5, Opus 4.8, and Opus 5, but it wasn't in the official Claude Code changelog and couldn't be verified against any Anthropic primary source in that session. Rather than cite it anyway, it got logged as an unverified watch item. Today it's resolved — the feature is real, officially documented, and it's a genuinely useful piece of agentic-coding infrastructure. It just wasn't where anyone was looking for it.

## Where It Actually Lives

The feature isn't in `code.claude.com/docs/en/changelog` because it isn't a Claude Code CLI feature — it's a Claude API capability, documented at `platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages` under the heading "Mid-conversation tool changes." That's a meaningful distinction for anyone trying to track Anthropic's release surface: the Claude Code changelog covers the terminal agent, but capabilities that ship at the model/API layer — this one included — get documented on the separate Developer Platform docs site instead. Two different products, two different changelogs, and a feature can be fully shipped and documented on one while being invisible on the other. That's exactly the kind of fragmentation that makes verification work necessary rather than optional.

## The Problem It Solves

Anthropic's prompt caching hashes the request prefix in a fixed order: `tools`, then `system`, then `messages`. A cache hit requires that entire prefix to match byte-for-byte up to the cache breakpoint. Anthropic's [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) feature — generally available, not a beta — already fixes one half of that problem — appending a new system-role message at the end of the conversation instead of editing the top-level `system` field, so a late-discovered instruction doesn't blow away the cached prefix that came before it.

But the `tools` array sits even earlier in that hashed prefix than `system` does. Editing it — adding a tool mid-session, or taking one away — invalidates the prompt cache for the *entire* conversation, not just the system portion. For a long agentic coding session that's accumulated tens of thousands of cached tokens across dozens of turns, that's an expensive tax to pay just because the agent now needs access to a linter it didn't need three turns ago, or should lose access to a destructive `deploy` tool once a task is scoped down.

## How Mid-Conversation Tool Changes Work

The mechanism, introduced in beta with Claude Opus 5, keeps the `tools` array itself completely static for the life of the conversation. You declare the full tool set up front — everything the model might ever need in this session — and then use two new content-block types inside a `role: "system"` message to control what's actually offered at any given point:

- **`tool_removal`** withdraws a tool from a specific point in the conversation onward, referencing it by name via a `tool_reference` block rather than editing `tools`.
- **`tool_addition`** re-offers a previously withdrawn tool, or surfaces one that was declared with `defer_loading: true` and withheld from the start.

Because the `tools` array never changes, its contribution to the hashed prefix never changes either, and the cache stays intact. Anthropic's own documentation example makes the mechanics concrete:

```json
{
  "role": "system",
  "content": [
    {
      "type": "tool_removal",
      "tool": {"type": "tool_reference", "name": "get_weather"}
    }
  ]
}
```

Requests need the `mid-conversation-tool-changes-2026-07-01` beta header, and MCP tools get the same treatment — `mcp_tool_reference` targets a single tool on a connected MCP server, while `mcp_toolset_reference` can add or remove an entire server's toolset in one block. The feature is available on Claude Fable 5, Mythos 5, Opus 4.8, and Opus 5, across the Claude API, Amazon Bedrock, and Google Cloud — but notably not on Claude Sonnet 5, which still requires the top-level `tools` field for any change.

## Why This Matters for Agentic Coding Specifically

This is squarely infrastructure for the kind of long-running, tool-heavy agentic sessions this blog covers constantly — a coding agent that starts with read/search/edit tools, later needs to spin up a deploy or migration tool once a task is scoped and approved, and should probably lose access to that same tool once the task is done. Before this beta, every one of those transitions meant editing `tools` and paying full price to reprocess the entire conversation history on the next request. Now the transition is a small `system`-role block appended at the natural boundary — after a tool result, before Claude's next turn — and the accumulated cache from everything before it survives untouched.

It also slots cleanly next to a security detail worth calling out on a blog that's spent the last two days covering Claude Code permission-bypass fixes: Anthropic's own limitations section is explicit that `tool_removal`/`tool_addition` blocks are not a place for untrusted content. The blocks reference tools by name; they don't carry arbitrary text from tool output or retrieved documents. That data still belongs in `tool_result` blocks, and the standard jailbreak/prompt-injection mitigations still apply. Anthropic drew that boundary deliberately rather than leaving it as an afterthought — a good sign for a feature explicitly aimed at agentic loops, which are exactly where injected instructions do the most damage.

## The Placement Rules Are Strict, and That's a Feature

A mid-conversation system message — tool-change blocks included — can't be the first entry in `messages`, can't sit between an `assistant` `tool_use` block and its answering `tool_result`, and must immediately follow either a `user` turn or an `assistant` turn ending in a server tool result. Get the placement wrong and the API returns a 400 rather than silently accepting something malformed. For a mechanism whose entire purpose is precise surgical edits to an otherwise-frozen prompt structure, that rigidity is the right trade: a system that quietly accepted tool changes in arbitrary positions would make cache behavior far harder to reason about, trading a clear error for a subtle, hard-to-debug cache miss three turns later.

## The Takeaway

Nothing about this beta is flashy — it's the unglamorous kind of infrastructure work that shows up as a line in an aggregator's rumor mill months before anyone writes it up properly, because "Anthropic reduced prompt-cache invalidation for tool-list changes" doesn't generate clicks the way a benchmark number does. But it's a real, concrete improvement for anyone running production agentic coding sessions with dynamic tool access, and it's a good reminder that Anthropic's release surface spans more than the Claude Code changelog this blog checks daily. When a claim shows up on secondary sites with no primary-source backing, the right move isn't to repeat it or to dismiss it — it's to go find where Anthropic actually documented it, which is exactly what closed this watch item.