---
title: Can you add or remove tools mid-conversation with Claude?
url: https://deepthinkingai.org/claude-mid-conversation-tool-changes/
published: 2026-09-24
author: Shekhar Singh
topic: AI Engineering
tags: claude-api, tool-use, prompt-caching, langchain, agents
site: DeepThinking AI
---

# Can you add or remove tools mid-conversation with Claude?

**Summary:** Anthropic's mid-conversation-tool-changes-2026-07-01 beta lets a system-role message add or remove already-declared tools partway through a conversation without invalidating the cached prefix above it. LangChain wired this into ChatAnthropic on 23 September 2026, and its wrapper silently drops any other content type from that message with only a logged warning.

## 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](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages)
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**

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 --- (tool_addition or tool_removal here)
4. Later turns, tools change here on

The feature only ever appends after the breakpoint. Editing anything above that line, including a system message you already sent, is what invalidates the cache instead.

## 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**

```mermaid
sequenceDiagram
    participant Client as Client
    participant ClaudeAPI as Claude API
    Client->>ClaudeAPI: user turn
    ClaudeAPI->>Client: assistant turn
    Client->>ClaudeAPI: system: tool_removal(get_weather)
    ClaudeAPI->>Client: assistant turn, tool gone
    Client->>ClaudeAPI: system: tool_addition(get_weather)
    ClaudeAPI->>Client: assistant turn, tool back
```

- user turn: cache breakpoint sits above this
- system: tool_removal(get_weather): beta header auto-sent
- system: tool_addition(get_weather): re-offers the same declared tool

Both system messages sit after a user turn and before the next assistant turn, the only place the API accepts a tool_addition or tool_removal block.

## 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](https://github.com/langchain-ai/langchain/pull/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](/prompt-caching-economics/)
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](/claude-compaction-modes/) 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](/auto-permission-policy-intent-channel/) 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.

<ReadNext
  href="/prompt-caching-economics/"
  kicker="Go deeper"
  title="When does prompt caching actually save money?"
  note="The break-even math behind cache reads and writes, the mechanism a mid-conversation tool change is built to protect."
/>

## 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.

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **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.
7. **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.


## Sources
- [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages). Anthropic
- [feat(anthropic,openai): mid-conversation tool changes on SystemMessage (#40758)](https://github.com/langchain-ai/langchain/pull/40758). LangChain, 2026-09-22
- [langchain-anthropic==1.7.4 release notes](https://github.com/langchain-ai/langchain/releases/tag/langchain-anthropic%3D%3D1.7.4). LangChain, 2026-09-23
- [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching). Anthropic

---
Canonical HTML: https://deepthinkingai.org/claude-mid-conversation-tool-changes/