Claude Opus 5 — Preserving Cache with Mid-Conversation Tool Changes

Have you all seen the new 'mid-conversation tool changes' feature in Anthropic's Claude Opus 5? It's a clever solution to the prompt caching issues that have always been a headache for developers designing agents.

In existing agent loops, adding or removing tools mid-conversation would change the tool list at the top of the API request, which would completely break the prompt cache [1]. Even if you wanted to start with read-only tools for security and then gradually expose write-access tools under specific conditions, the latency and cost overhead caused by broken caches made it difficult to justify.

However, with the newly released mid-conversation-tool-changes-2026-07-01 beta header, you can dynamically add or remove tools within your system message while keeping the top-level tool definition intact.

json
{
  "role": "system",
  "content": [
    {
      "type": "tool_addition",
      "name": "apply_patch"
    }
  ]
}

By configuring it this way, the beginning of the prompt hash remains unchanged, allowing you to retain tens of thousands of tokens of context cache perfectly. Benchmarks from actual builders show that in multi-turn agent loops, input processing speed can increase by up to 85% and costs can be reduced by nearly 90%. Furthermore, the minimum threshold for prompt caching has been lowered to 512 tokens, making it easier to benefit from caching even in lightweight tasks.

Note that this feature is currently in beta only for specific reasoning-focused models like Claude Opus 5 and Mythos 5, and it is not applied to Sonnet 5. Also, it cannot be used in the first message of a conversation. Still, it's a feature that will drastically increase the efficiency of long-running agents, and it's likely to bring significant changes to future production agent design patterns. 😄

(Edited)