mid-conversation-system-messages changedbuild-with-claude/mid-conversation-system-messages
Nearest release: v2.1.282, published an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+21added
Lines−16removed
From line
17
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits11to this page, all time
The whole hunk
from line 17, old and new numbered
/
from line 17
1717
1818 This feature is available on Claude Fable 5.1, [Claude Mythos 5.1](https://anthropic.com/glasswing), Claude Fable 5, [Claude Mythos 5](https://anthropic.com/glasswing), Claude Opus 5.5, Claude Opus 4.8, and Claude Opus 5. No beta header is required for mid-conversation system messages. This feature is not available on Claude Sonnet 5. Use the top-level `system` field there instead.
1919
20 [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) are in beta and require the `mid-conversation-tool-changes-2026-07-01` beta header. They are available on the same models, on the Claude API, Amazon Bedrock, and Google Cloud. [Defining a tool inside a `tool_addition` block](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta) uses the `inline-tools-2026-09-15` beta header in place of that one, and is available on the Claude API. [Adding an MCP server that way](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta) also needs the `mcp-client-2026-09-15` beta header.
20 [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) are in beta on the same models. On the Claude API, send the `inline-tools-2026-09-15` beta header, which also covers [defining a tool inside a `tool_addition` block](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta). Defining a tool in a message is available on the Claude API only, and [adding an MCP server that way](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta) needs the `mcp-client-2026-09-15` beta header as well. The older `mid-conversation-tool-changes-2026-07-01` header still works for changes that name a tool by reference, on the Claude API, Amazon Bedrock, and Google Cloud.
2121
2222 [Turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at`) are in beta and require the `mid-conversation-system-clear-at-2026-08-21` beta header, on the same models and platforms as mid-conversation system messages.
2323</Note>
from line 24
2424
2525## Mid-conversation tool changes
2626
27The `tools` array sits even earlier in the hashed request prefix than the top-level `system` field, so editing it invalidates the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for the entire conversation. Mid-conversation tool changes are the tools counterpart to mid-conversation system messages. Instead of fixing the tool list for the lifetime of the conversation, you change which tools are offered to the model between turns: declare the full tool set in `tools` up front, then use `tool_addition` and `tool_removal` blocks to offer a tool to the model, or withdraw it, from a specific point in the conversation onward. The `tools` array itself never changes, so the cached prefix stays intact.
27The `tools` array sits even earlier in the hashed request prefix than the top-level `system` field, so editing it invalidates the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for the entire conversation. Mid-conversation tool changes are the tools counterpart to mid-conversation system messages. Instead of fixing the tool list for the lifetime of the conversation, you change which tools are offered to the model between turns: declare the full tool set in `tools` up front, then use `tool_addition` and `tool_removal` blocks to offer a tool to the model, or withdraw it, from a specific point in the conversation onward. The `tools` array itself never changes, so the cached prefix stays intact. Mid-conversation tool changes are in beta and use the `inline-tools-2026-09-15` beta header on the Claude API. On Amazon Bedrock and Google Cloud, use the older `mid-conversation-tool-changes-2026-07-01` header, which covers changes that name a tool by reference.
2828
29`tool_addition` and `tool_removal` are content blocks in the `content` array of a `role: "system"` message, and they can be mixed with `text` blocks in the same message. The message follows the placement rules for any mid-conversation system message, with one extra restriction after a paused turn (see [Limitations](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)), and the change applies from that point in the conversation onward. Each block's `tool` field references a tool rather than defining one: `{"type": "tool_reference", "name": "..."}` names a tool declared in the request's `tools` array, and [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) tools can be referenced individually with `mcp_tool_reference` (`server_name` and `name`) or as a whole toolset with `mcp_toolset_reference` (`server_name`). Referencing a name that is not declared in `tools` returns a 400 error (on the Claude API, with `error.details.error_code` set to `tool_reference_unresolved`). With the `inline-tools-2026-09-15` beta header, a `tool_addition` block can instead [carry the tool's full definition](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).
29`tool_addition` and `tool_removal` are content blocks in the `content` array of a `role: "system"` message, and they can be mixed with `text` blocks in the same message. The message follows the placement rules for any mid-conversation system message, with one extra restriction after a paused turn (see [Limitations](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)), and the change applies from that point in the conversation onward. Each block's `tool` field references a tool rather than defining one: `{"type": "tool_reference", "name": "..."}` names a tool declared in the request's `tools` array, and [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) tools can be referenced individually with `mcp_tool_reference` (`server_name` and `name`) or as a whole toolset with `mcp_toolset_reference` (`server_name`). Referencing a name that is not declared in `tools` returns a 400 error (on the Claude API, with `error.details.error_code` set to `tool_reference_unresolved`). A `tool_addition` block can instead [carry the tool's full definition](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta), which the older `mid-conversation-tool-changes-2026-07-01` header doesn't support.
3030
3131Every tool declared in `tools` is offered to the model from the start of the conversation unless it is declared with `defer_loading: true`, which keeps it withheld until a `tool_addition` block surfaces it. `tool_addition` also re-offers a tool that an earlier `tool_removal` withdrew.
3232
33The following request declares `get_weather` in `tools`, then withdraws it after the first user turn with a `tool_removal` block. Mid-conversation tool changes are in beta, so the request sends the `mid-conversation-tool-changes-2026-07-01` beta header.
33The following request declares `get_weather` in `tools`, then withdraws it after the first user turn with a `tool_removal` block. The request sends the `inline-tools-2026-09-15` beta header.
3434
3535<CodeGroup>
3636 ```bash cURL
from line 38
3838 -H "content-type: application/json" \
3939 -H "x-api-key: $ANTHROPIC_API_KEY" \
4040 -H "anthropic-version: 2023-06-01" \
41 -H "anthropic-beta: mid-conversation-tool-changes-2026-07-01" \
41 -H "anthropic-beta: inline-tools-2026-09-15" \
4242 -d '{
4343 "model": "claude-opus-5-5",
4444 "max_tokens": 1024,
from line 74
7474 ```
7575
7676 ```bash CLI
77 ant beta:messages create --beta mid-conversation-tool-changes-2026-07-01 \
77 ant beta:messages create --beta inline-tools-2026-09-15 \
7878 --transform 'content.#(type=="text").text' --raw-output <<'YAML'
7979 model: claude-opus-5-5
8080 max_tokens: 1024
from line 107
107107 response = client.beta.messages.create(
108108 model="claude-opus-5-5",
109109 max_tokens=1024,
110 betas=["mid-conversation-tool-changes-2026-07-01"],
110 betas=["inline-tools-2026-09-15"],
111111 # The full tool set is declared up front and never changes, so the
112112 # cached prefix stays intact.
113113 tools=[
from line 154
154154 const response = await client.beta.messages.create({
155155 model: "claude-opus-5-5",
156156 max_tokens: 1024,
157 betas: ["mid-conversation-tool-changes-2026-07-01"],
157 betas: ["inline-tools-2026-09-15"],
158158 // The full tool set is declared up front and never changes, so the
159159 // cached prefix stays intact.
160160 tools: [
from line 198
198198 ```
199199
200200 ```csharp C#
201 using Anthropic.Models.Beta;
201202 using Anthropic.Models.Beta.Messages;
202203 using Messages = Anthropic.Models.Messages;
203204
from line 208
207208 {
208209 Model = Messages::Model.ClaudeOpus5_5,
209210 MaxTokens = 1024,
210 Betas = ["mid-conversation-tool-changes-2026-07-01"],
211 Betas = [AnthropicBeta.InlineTools2026_09_15],
211212 // The full tool set is declared up front and never changes, so the
212213 // cached prefix stays intact.
213214 Tools =
from line 262
261262 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
262263 Model: anthropic.ModelClaudeOpus5_5,
263264 MaxTokens: 1024,
264 Betas: []anthropic.AnthropicBeta{"mid-conversation-tool-changes-2026-07-01"},
265 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaInlineTools2026_09_15},
265266 // The full tool set is declared up front and never changes, so the
266267 // cached prefix stays intact.
267268 Tools: []anthropic.BetaToolUnionParam{
from line 307
306307 ```
307308
308309 ```java Java
310 import com.anthropic.models.beta.AnthropicBeta;
309311 import com.anthropic.models.beta.messages.BetaContentBlockParam;
310312 import com.anthropic.models.beta.messages.BetaMessage;
311313 import com.anthropic.models.beta.messages.BetaMessageParam;
from line 335
333335 MessageCreateParams params = MessageCreateParams.builder()
334336 .model(Model.CLAUDE_OPUS_5_5)
335337 .maxTokens(1024)
336 .addBeta("mid-conversation-tool-changes-2026-07-01")
338 .addBeta(AnthropicBeta.INLINE_TOOLS_2026_09_15)
337339 .addTool(weatherTool)
338340 .addUserMessage("Say OK.")
339341 // Withdraw get_weather from this point onward. The block references
from line 357
355357 ```
356358
357359 ```php PHP
360 use Anthropic\Beta\AnthropicBeta;
361 // ...
362
358363 $client = new Client();
359364
360365 $response = $client->beta->messages->create(
361 model: 'claude-opus-5-5',
366 model: Model::CLAUDE_OPUS_5_5,
362367 maxTokens: 1024,
363 betas: ['mid-conversation-tool-changes-2026-07-01'],
368 betas: [AnthropicBeta::INLINE_TOOLS_2026_09_15],
364369 // The full tool set is declared up front and never changes, so the
365370 // cached prefix stays intact.
366371 tools: [
from line 412
407412 client = Anthropic::Client.new
408413
409414 response = client.beta.messages.create(
410 model: "claude-opus-5-5",
415 model: Anthropic::Model::CLAUDE_OPUS_5_5,
411416 max_tokens: 1024,
412 betas: ["mid-conversation-tool-changes-2026-07-01"],
417 betas: [Anthropic::AnthropicBeta::INLINE_TOOLS_2026_09_15],
413418 # The full tool set is declared up front and never changes, so the
414419 # cached prefix stays intact.
415420 tools: [
No line in this hunk matches that.