Can you add or remove tools mid-conversation with Claude?
AI Architect
Key takeaways
- A mid-conversation system message can add or remove a tool without invalidating the cached prefix that precedes it.
- langchain-anthropic 1.7.4, released 23 September 2026, drops unrecognized content blocks on a mid-conversation SystemMessage with only a warning.
- Editing or deleting a system message already sent invalidates the cache from that point forward.
- On Claude Fable 5.1 and Opus 5.5, editing an old system message also invalidates thinking blocks in every later assistant turn.
- Claude Sonnet 5 does not support mid-conversation tool changes; only Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5.5, Opus 4.8 and Opus 5 do.
Adding a tool mid-conversation used to mean editing the top-level system
field or resending the whole tools array, either of which changes the start
of the prompt and throws away the cached prefix. Anthropic shipped a narrower
mechanism for this in a beta most people have not read, and LangChain wired it
into ChatAnthropic on 23 September 2026 with a breaking change buried in the
release notes.
What is Claude’s mid-conversation tool changes feature?
It lets you append a {"role": "system"} message partway through a
conversation that adds or removes tool availability, instead of rewriting the
top-level system field where new instructions normally go. The distinction
matters because the top-level field sits at the very start of the prompt: any
edit there changes every byte after it, so the whole cached prefix has to be
recomputed. A mid-conversation system message is appended after the point
you already cached, so the documentation
states plainly that it leaves earlier turns “byte-identical,” preserving the
cache hit. Plain system-message text needs no beta header at all. Only the
tool_addition and tool_removal block types, which change what the model
can call rather than what it is told, sit behind the dated
mid-conversation-tool-changes-2026-07-01 header.
What a mid-conversation tool change can touch
Show as text
| # | Layer | Note |
|---|---|---|
| 1 | Declared tools array | Never edited, only referenced |
| 2 | Top-level system field | Unchanged by this feature |
| 3 | Messages up to the cache breakpoint | Byte-identical, cache survives |
| · | appended system message (breakpoint) | tool_addition or tool_removal here |
| 4 | Later turns, tools change here on |
How do tool_addition and tool_removal blocks actually work?
You never edit the tools array itself. Instead you declare every tool you
might need upfront, then send a role: "system" message whose content is a
tool_addition or tool_removal block naming one already-declared tool by
reference: {"type": "tool_reference", "name": "get_weather"} for a custom
tool, or mcp_tool_reference and mcp_toolset_reference for individual MCP
tools and whole MCP toolsets. Naming a tool that was never declared, or was
mistyped, returns a 400 with error_code: tool_reference_unresolved. A tool
marked defer_loading: true stays hidden from the model until a
tool_addition block surfaces it, and a tool_removal is not permanent:
a later tool_addition can re-offer the exact tool an earlier removal took
away, which is what makes this useful for scoping a capability to one phase
of a task rather than the whole conversation.
Removing and re-adding a tool mid-conversation
Show as text
| # | From | To | Message |
|---|---|---|---|
| 1 | Client | Claude API | user turn. cache breakpoint sits above this |
| 2 | Claude API | Client | assistant turn |
| 3 | Client | Claude API | system: tool_removal(get_weather). beta header auto-sent |
| 4 | Claude API | Client | assistant turn, tool gone |
| 5 | Client | Claude API | system: tool_addition(get_weather). re-offers the same declared tool |
| 6 | Claude API | Client | assistant turn, tool back |
Where in a conversation can a tool-change message go?
Placement is stricter than a normal system message, because the API needs to
know the change applies cleanly to the next model turn. A tool_addition or
tool_removal block must follow a user turn, including one that ends in a
tool_result, or an assistant turn that ended in a server tool result, and it
must precede the next assistant turn or end the array. It cannot sit between a
tool_use block and its matching tool_result, and it cannot appear as the
first message in the conversation at all, since that position is what the
top-level system field already covers. There is one exception worth
remembering: after a paused assistant turn, tool-change blocks are rejected
outright, so if your agent pauses mid-turn, resume it with a plain text system
message first and change tools only once a new turn has started cleanly.
What did LangChain’s mid-conversation tool changes support add?
langchain-anthropic 1.7.4, released 23 September 2026 through
PR #40758, lets
ChatAnthropic and ChatOpenAI construct these blocks from a SystemMessage
instead of hand-building the raw JSON. The PR’s own description states the
mechanism plainly: “system content is narrowed to what the API documents,
text everywhere, tool changes in place, anything else is dropped with a
warning.” That is a breaking change for anyone who was previously attaching a
custom content type to a mid-conversation SystemMessage and having it
forwarded verbatim; it now vanishes silently, with only a log line to notice.
The beta header is handled for you: it is appended automatically, but only
once a tool-change block genuinely reaches the wire, so a plain-text system
message still needs no header at all, matching the underlying API’s own
rule.
What breaks if you edit an old system message instead of appending one?
Two things, and the second is easy to miss. Editing or removing a system message you already sent invalidates the prompt cache from that point in the conversation forward, the same rule that governs any other edit to an already-cached prefix. On Claude Fable 5.1 and Opus 5.5 specifically, the documentation adds a second consequence: it also invalidates thinking blocks in every assistant turn that came after the edit, even turns that had nothing to do with the tool you changed. Claude’s compaction feature has the same shape of rule, where thinking survives only when the turns kept afterward are unchanged from what produced them. If an instruction or a tool set needs to evolve, append a new system message rather than rewriting the old one, even though rewriting feels like the smaller edit.
Which Claude models actually support this?
Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5.5, Opus 4.8 and Opus 5, on
the Claude API, Amazon Bedrock and Google Cloud Vertex AI. Claude Sonnet 5 is
explicitly excluded, with the documentation directing callers back to the
top-level system field for that model. That is a real constraint if your fleet mixes models by cost tier. A pattern
built and tested against Opus or Fable fails to change tools at all on
Sonnet 5, and the top-level workaround it falls back to pays the full cache
cost every time. Check the model list before you build a scoping mechanism
around this feature. The failure mode gives no error message: a Sonnet 5
call simply keeps every tool available when you intended to remove one.
Should you use this instead of an allow list for restricting tools?
No, and the distinction is worth stating clearly. Mid-conversation tool
changes controls what the model can call at a given point in a
conversation, the same kind of decision Anthropic’s auto permission
policy makes about whether a call
that was already offered is allowed to run. Removing a tool here stops the
model from seeing it as an option; it does nothing to a call already in
flight, and it is not a security boundary, since anyone who controls the
request stream can always re-add the tool with another tool_addition block.
Use it to scope which capabilities are relevant to the current phase of a
task, which keeps the model’s decision space smaller and its cache stable.
Keep a real permission layer, server-side, for the question of whether a call
that is offered should actually be allowed to execute.
Do this
Change Claude's available tools mid-conversation without losing your cache
The ordering rules exist to protect the cached prefix, so treat every step below as protecting that boundary.
Declare every tool you might need upfront
Put everything in the tools array at the start, including tools you plan to withhold with defer_loading true. tool_addition and tool_removal only reference tools that already exist; they cannot introduce a new one unless you use inline definitions.
Place the system message right after a user turn
A tool_addition or tool_removal block must follow a user turn, including one ending in a tool_result, and precede the next assistant turn. It cannot sit between a tool_use block and its tool_result, and it is rejected outright after a paused assistant turn.
Reference tools by name and expect a 400 on typos
Use tool_reference for a custom tool or mcp_tool_reference for one MCP tool. An unresolved name returns error_code tool_reference_unresolved, which is the signal to check the exact name you declared.
Send the beta header, or let your SDK send it
mid-conversation-tool-changes-2026-07-01 is required on any request where a tool-change block reaches the wire. langchain-anthropic 1.7.4 appends it automatically once a block is actually sent.
Never edit or delete a system message you already sent
Append a new one instead. Editing an earlier one invalidates the cache from that point forward, and on Fable 5.1 and Opus 5.5 it also invalidates thinking blocks in every later assistant turn.
Check what your SDK silently drops
On langchain-anthropic 1.7.4+, a mid-conversation SystemMessage keeps only text and tool-change blocks. Anything else is dropped with a logged warning rather than a raised error, so turn logging up before you rely on a custom content type surviving.
Confirm your model is on the supported list
Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5.5, Opus 4.8 and Opus 5 support this. Claude Sonnet 5 does not, and falls back to editing the top-level system field, which does cost the cache.
Frequently asked questions
- What beta header does mid-conversation tool changes need?
- mid-conversation-tool-changes-2026-07-01, sent on any request where a tool_addition or tool_removal block actually reaches the API. Inline tool definitions need a second header, inline-tools-2026-09-15, and adding an MCP server mid-conversation needs mcp-client-2026-09-15 alongside it.
- Can I add back a tool I removed earlier in the same conversation?
- Yes. A later tool_addition block can re-offer a tool an earlier tool_removal withdrew, as long as it still names a tool declared in the original tools array or an inline definition sent since.
- Does changing tools mid-conversation break my prompt cache?
- No. Appending a system message after the cache breakpoint leaves every earlier turn byte-identical, so the cached prefix survives. Editing or removing a system message you already sent is what breaks it.
- Which Claude models support mid-conversation tool changes?
- Claude Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5.5, Opus 4.8 and Opus 5, on the Claude API, Amazon Bedrock and Google Cloud Vertex AI. Claude Sonnet 5 is not on the list; use the top-level system field there instead.
- What happens if LangChain drops a content block from my SystemMessage?
- ChatAnthropic logs a warning and sends only the text and tool-change blocks it recognizes. Anything else you attached to that message, such as a custom content type, never reaches the API and there is no error to tell you it happened.
- Is mid-conversation tool changes a stable feature?
- No. It ships behind a dated beta header, which Anthropic uses for features still subject to change, and the underlying inline-tools and MCP-server betas carry a September 2026 date, newer than the tool-change beta itself.