Mid-conversation tool changes

会話全体でツール一覧を固定せず、tools に宣言したツールを tool_addition / tool_removal ブロックで会話の特定の位置から提示したり取り下げたりします。tools 配列自体は変わらないため、キャッシュされたプロンプトのプレフィックスはそのまま保たれます。

この機能では、ツール一覧を会話全体で固定する代わりに、ターン間でモデルに提示するツールを変更します。

• tool_addition と tool_removal は、role: "system" メッセージの content 配列に入れるコンテンツブロックです。
• tools に宣言したツールは、defer_loading: true を付けない限り会話の最初から提示されます。
• tool_addition は、以前の tool_removal で取り下げたツールを再び提示する用途にも使えます。
• MCP コネクタのツールは、mcp_tool_reference(server_name と name)で個別に、または mcp_toolset_reference(server_name)でツールセット全体として参照できます。
• tools 配列自体は変わらないため、キャッシュされたプレフィックスは保たれます。

inline-tools-2026-09-15 ベータヘッダーを使うと、tool_addition ブロックでツールを参照ではなく値として、完全な定義ごと指定できます。定義は tool_definition 型の tool オブジェクトで包み、definition には通常の tools の項目(カスタムツール、または Anthropic 定義のクライアントツール・サーバーツール)を、cache_control や defer_loading を含む通常の設定のまま指定します。

• 定義した位置以降、モデルは tools に宣言したツールと同じようにそのツールを呼び出せます。
• 同一の定義を再送しても何も変わらないため、リトライ時などに安全に再送できます。
• 同じ名前で異なる定義を送ると、その位置以降は新しい定義が以前の定義を置き換えます。スキーマの変更やサーバーツールの新バージョンへの移行に使います。
• tool_removal は引き続き参照で指定します。削除したツールは、後で再定義・再提示できます。

会話の途中で MCP コネクタのサーバーを追加するには、inline-tools-2026-09-15 に加えて mcp-client-2026-09-15 ベータヘッダーを送ります。

• サーバーの接続情報は通常どおり mcp_servers に記載し、サーバーを使えるようにしたい位置に mcp_toolset を定義とする tool_addition を追加します。
• tool_addition ブロックにはサーバーの URL やトークンを含めません。これらは mcp_servers に置いたままにします。
• API がサーバーのツール一覧を取得したレスポンスは、取得したサーバーごとに 1 つの mcp_tool_listing ブロックで始まります。
• assistant メッセージを mcp_tool_listing ブロックを含めて変更せずに送り返し、そのブロックを含むすべてのリクエストで mcp-client-2026-09-15 を送り続けます。送り返した一覧は固定され、以降のリクエストはサーバーに再度問い合わせず、記録された一覧を使います。

• tools に宣言されていない名前を参照すると 400 エラーになります。Claude API では error.details.error_code が tool_reference_unresolved になります。
• 別の種類のツールの名前を再利用する定義は、error.details.error_code が tool_name_conflict の 400 エラーになります。
• ベータ期間中は、computer use tool を含む一部のツール種別をメッセージ内で定義できず、400 エラーになります。これらは tools に宣言し、参照で追加します。
• tools 配列に deferred でないツールが 1 つも無い場合、値で定義した最初のツールがレンダリングされるプロンプトの先頭を変えるため、そのリクエストで 1 回、キャッシュが完全にミスします。
• 一時停止した(paused)assistant ターンの直後には、text ブロックは受け付けられますが、tool_addition と tool_removal ブロックは受け付けられません。先に一時停止したターンを再開し、次の system メッセージでツール変更を送ります。
• ターン単位の system メッセージ(turn-scoped)に tool_addition / tool_removal を入れると 400 エラーになります。これらには clear_at を付けない別の role: "system" メッセージを使います。

この機能はベータとして提供されています。会話途中のツール変更は、Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 5 でベータ提供されました。メッセージ内でのツール定義は、inline-tools-2026-09-15 ベータヘッダーにより Claude API でベータ提供されています。対象プランについては、公式のリリースノートには記載がありません。

ここでは、あらかじめ宣言したツールを参照で追加・削除する流れを示します。

1. リクエストに inline-tools-2026-09-15 ベータヘッダーを付けて送ります。
2. 会話で使う可能性のあるツールをすべて、最初から tools に宣言します。defer_loading: true を付けたツールは、tool_addition ブロックで提示されるまでモデルに提示されません。
3. role: "system" メッセージに tool_addition または tool_removal ブロックを入れ、各ブロックの tool フィールドを {"type": "tool_reference", "name": "..."} の形にして、tools に宣言したツール名を指定します。これらのブロックは同じメッセージ内で text ブロックと混在できます。