Claude API: Add Tools Mid-Conversation, Cache Intact

Every developer who has built a production Claude agent knows the pain. Your agent is 40 turns deep into a research session, the conversation history is 80,000 tokens long, and your user wants to pivot from research to code generation. So you add the code execution tool to your next API call. Cache miss. You just paid full input price to re-process 80,000 tokens that Claude already knew.

The tools array sits near the start of the hashed request prefix that prompt caching uses. Any change to it invalidates the cache for the entire conversation. For agents that run long, multi-phase sessions, this made dynamic tool capabilities an expensive luxury. Anthropic fixed it in September 2026 with two new beta features that let you add, remove, or fully define tools mid-conversation without touching the tools array — and without busting the cache.

What Shipped

There are two distinct beta headers to know about:

mid-conversation-tool-changes-2026-07-01 — The original beta, now in wider availability. Lets you add or remove tools by reference between turns using a mid-conversation role: "system" message. The tool must exist in the initial tools array; you are activating or deactivating it rather than introducing something new. The cache prefix stays intact.

inline-tools-2026-09-15 — The September upgrade and the more powerful of the two. With a tool_addition block inside a mid-conversation system message, you can define a tool by value — full name, description, and input schema — for a tool that was completely unknown at conversation start. You never add it to the top-level tools array. The cache prefix is never touched. Anthropic shipped this header on September 15 and highlighted it as a key feature of the Claude Opus 5.5 launch a week later.

How Inline Tools Work

Your initial API call looks normal: you send your base tool set in the tools array, and caching kicks in as usual. When the session needs a new capability, you append a role: "system" message to the conversation with a tool_addition block carrying the full tool definition:

response = client.messages.create(
    model="claude-opus-5-5",
    tools=[web_search_tool, read_document_tool],  # unchanged — cache hits
    messages=[
        *conversation_history,                     # cached prefix intact
        {
            "role": "system",
            "content": [{
                "type": "tool_addition",
                "tool": {
                    "name": "execute_code",
                    "description": "Execute Python code in a sandboxed environment",
                    "input_schema": {
                        "type": "object",
                        "properties": {
                            "code": {"type": "string"}
                        },
                        "required": ["code"]
                    }
                }
            }]
        }
    ],
    betas=["inline-tools-2026-09-15"]
)

Claude sees the new tool immediately. Your cached tokens remain cached. You pay only for the new message and the response.

MCP Toolsets Mid-Conversation

If you are using the MCP connector, a third beta header ships in this same update: mcp-client-2026-09-15. Combined with inline tools, it lets you add an entire MCP server toolset partway through a conversation. The API fetches the server’s tool list and records it in an mcp_tool_listing block in the response. Send that block back in subsequent requests and the API uses the pinned tool list rather than re-fetching — preventing a server update from silently changing what Claude can call mid-session. Full details are in the MCP connector documentation.

Turn-Scoped Instructions

The same update ships clear_at: "next_user_message" for mid-conversation system messages, via the mid-conversation-system-clear-at-2026-08-21 beta header. Set this field and the instruction renders only for the current turn, then stays in conversation history at no token cost. Useful for per-turn formatting instructions or one-off task constraints that should not persist into future turns.

Supported Models and Platforms

Both features work on Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 5, and Claude Opus 5.5. They are available across the Claude API, Amazon Bedrock, and Google Cloud Vertex AI. You opt in by including the relevant header in your anthropic-beta request field.

The Pattern This Unlocks

The “expanding scope” agent — where a session starts narrow and grows as the user’s intent clarifies — is now a first-class pattern. A research agent that gains code execution when the user confirms a direction. A support agent that gets escalation tools when a conversation reaches severity. A data agent that adds a SQL query tool when structured lookups become necessary. Before this, implementing these patterns meant either front-loading all possible tools (consuming tens of thousands of tokens per request in definitions) or accepting cache misses as the cost of doing business.

Anthropic’s engineering team has noted that an agent connected to just five MCP servers can consume roughly 55,000 tokens on tool definitions before the first user message. Inline tools let you defer that cost until the capability is actually needed. That is not a minor optimization — for high-volume production agents, it directly reduces operating costs and enables architectures that were previously impractical.

The full reference is in the official Anthropic documentation for mid-conversation system messages. Both beta headers can be combined in a single request. The Claude Platform release notes track ongoing updates to these beta features as they move toward general availability.