Claude API: Swap Tools Mid-Conversation Without Invalidating the Cache

A Claude API beta header lets agents swap tools between turns while preserving the prompt cache — no more latency tax for tool-list changes.

Multi-step agents often need different tools at different phases. Previously, changing the tools array between turns invalidated the entire prompt cache — paying full input cost again on every tool swap, plus re-processing the full conversation history.

The mid-conversation-tool-changes-2026-07-01 beta header fixes this on Opus 5, Fable 5, Opus 4.8, and Mythos 5:

import anthropic

client = anthropic.Anthropic()
BETA = ["mid-conversation-tool-changes-2026-07-01"]

# Phase 1: read-only tools
response = client.messages.create(
    model="claude-opus-5-20260724",
    betas=BETA,
    system="You are a code analysis agent.",
    messages=conversation,
    tools=[search_tool, read_file_tool],   # read-only
    max_tokens=4096,
)
conversation.extend(...)

# Phase 2: write tools — cache stays hot despite different tool list
response = client.messages.create(
    model="claude-opus-5-20260724",
    betas=BETA,
    system="You are a code analysis agent.",  # still cached
    messages=conversation,                    # history still cached
    tools=[write_file_tool, run_cmd_tool],    # different list — no cache bust
    max_tokens=4096,
)

Why this matters for agent design. You can match tool access to the task's risk level per turn — give the planner phase read-only tools, give the executor write access — without paying cache penalties. Least-privilege tool design is now practical in long conversations.

Per-turn effort is also cache-friendly. Opus 5 supports changing budget_tokens per turn without busting the cache. Start a planning pass at effort="low" and escalate to effort="xhigh" for a hard sub-problem, mid-conversation. One constraint: at xhigh or max effort, setting thinking: {"type": "disabled"} returns a 400 error — plan your effort ladder with this in mind.

Sources: Claude Platform release notes — Anthropic · What's new in Opus 5 — Claude Platform Docs · Effort parameter — Claude Platform Docs