Opus 5 beta stops tool swaps from wiping the cache

Anthropic shipped a beta with Opus 5 that stops mid-conversation tool changes from wiping a conversation's entire prompt cache, per the mid-conversation system messages guide in its developer docs.

Agent systems that move through several phases used to pay a full cache rebuild every time they swapped a tool. The new beta lets that swap happen without the rebuild.

Why the old approach broke

The tools array sits earlier in the hashed request prefix than the top-level system field, per the docs. Edit that array to add or drop a tool, and the cache for the whole conversation invalidates, not just the request.

The beta flips the order of operations. You declare the full tool set up front and mark the ones you don't need yet as defer_loading: true.

To bring a deferred tool in or take an active one out, you send a role: "system" message carrying a tool_addition or tool_removal block naming the tool, instead of editing the array again.

MCP tools get the same treatment. A single tool swaps via mcp_tool_reference; a whole server swaps via mcp_toolset_reference.

The docs don't say what a deferred tool costs while it sits dormant, or whether the mechanism will reach models older than Opus 5.