tool result clearingの設定オプション完全ガイド

tool result clearingとは何を自動化する機能か

clear_tool_uses_20250919 は、会話が長くなり古いtool_resultが不要になったタイミングで、その内容を自動的にプレースホルダテキストへ置き換えるサーバーサイド機能です。ファイルの中身や検索結果のような、Claudeが一度処理してしまえば以後は要らなくなるツール結果を、API側が古い順に自動でクリアします。クライアント側の会話履歴自体は変更されず、送信するたびに全文をそのまま渡し続けて構いません。

有効化にはベータヘッダー context-management-2025-06-27 が必要です。設定を何も指定せず {"type": "clear_tool_uses_20250919"} とだけ書けば、すべてのパラメータが既定値で動作します。

5つの設定パラメータ

trigger — いつクリアを始めるか

trigger はクリアが発動する条件です。プロンプト全体がこのしきい値を超えたときにクリアが始まります。単位は input_tokens(トークン数)と tool_uses(ツール呼び出しの回数)のどちらかを選べます。既定は入力100,000トークンです。

keep — 直近何件を残すか

keep はクリア発生時に、直近のtool use/resultペアを何件残すかを指定します。既定は3件で、APIは古いツールのやり取りから順に削除し、直近の分だけを残します。ツールの出力をClaudeが継続的に参照する必要があるワークフローでは、この値を大きくして残す量を増やせます。

clear_at_least — 最低限クリアする量を保証する

clear_at_least を設定すると、1回のクリア発動で最低限このトークン数を確実にクリアします。指定した量をクリアできない場合、そのクリア自体が適用されません。この仕組みは、プロンプトキャッシュを壊してまでクリアする価値があるかどうかを判断する材料になります。

exclude_tools — 特定ツールを保護する

exclude_tools に列挙したツール名の呼び出しと結果は、クリア対象から常に除外されます。重要な文脈を保持しておきたいツール(例えばシステムの状態を保持するツールや、後続のターンで参照され続けるツール)を守るのに使います。

clear_tool_inputs — ツール呼び出しの引数も消すか

既定ではクリアされるのはtool_resultだけで、Claudeが送ったツール呼び出し自体(引数を含む)は履歴に残ります。clear_tool_inputs を true にすると、結果だけでなく呼び出しの引数も一緒に消します。

実装例 — 5パラメータをすべて指定する

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-5",
        "max_tokens": 4096,
        "messages": [
            {"role": "user", "content": "Create a simple command line calculator app using Python"}
        ],
        "tools": [
            {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool", "max_characters": 10000},
            {"type": "web_search_20250305", "name": "web_search", "max_uses": 3}
        ],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {"type": "input_tokens", "value": 30000},
                    "keep": {"type": "tool_uses", "value": 3},
                    "clear_at_least": {"type": "input_tokens", "value": 5000},
                    "exclude_tools": ["web_search"]
                }
            ]
        }
    }'

この設定は「入力30,000トークンを超えたら、直近3件のtool use/resultだけ残して古いものから消す。ただし1回で最低5,000トークンをクリアできないなら発動しない。web_searchツールは常に保護する」という意味になります。text_editorツールの古い編集結果はクリア対象ですが、web_searchの検索結果はexclude_toolsで保護され続けます。

コマンドラインでPythonの電卓アプリを作らせるようなタスクでは、text_editorツールがファイルの読み書きを繰り返し、古い版のファイル内容が延々と会話に残り続けます。exclude_toolsでweb_searchだけを保護しつつtext_editorの古い結果は自動でクリアする、という組み合わせは、検索結果のように後から参照したい情報と、ファイル内容のように一度反映すれば不要になる情報とで扱いを分けたいケースにそのまま当てはまります。

クリアされたことをレスポンスで確認する

クリアが実際に適用されたかどうかは、レスポンスの context_management.applied_edits フィールドで確認できます。

{
  "context_management": {
    "applied_edits": [
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

cleared_tool_uses はクリアされたツール呼び出しの件数、cleared_input_tokens はクリアで削減された入力トークン数です。ストリーミングレスポンスでは、この情報は最後の message_delta イベントに含まれます。この数値をログに残しておけば、trigger や keep の値を実際のワークロードに合わせてチューニングできます。サーバーツールの結果が5分TTLで別途自動キャッシュされる仕組みとは独立した機能なので、両者を混同しないようサーバーツール結果の自動キャッシュも併せて確認しておくと切り分けやすくなります。

プロンプトキャッシュとの関係でつまずきやすい点

tool result clearingが発動すると、クリアした位置から後ろのキャッシュプレフィックスは無効化されます。クリアのたびにキャッシュ書き込みコストが発生し、その後のリクエストで新しいプレフィックスとして再びヒットするようになります。clear_at_least は、この無効化のコストに見合うだけの量を毎回まとめてクリアするための調整弁です。頻繁に少量だけクリアする設定にすると、キャッシュの無効化ばかりが起きて再ヒットの恩恵が薄くなります。

よくあるつまずき

• ベータヘッダーを忘れて設定が無視される: context-management-2025-06-27 ヘッダーを付け忘れると context_management フィールドそのものが無視され、クリアが一切発動しない。エラーにはならないため気づきにくい
• triggerの単位を勘違いする: input_tokens のつもりで数値を入れたら tool_uses(回数)として解釈され、意図した閾値よりはるかに早く、あるいは遅く発動する
• clear_at_leastを大きくしすぎて発動しなくなる: clear_at_least の値がそのリクエストで実際にクリアできる量を上回っていると、戦略自体が適用されないまま素通りする。applied_edits に何も現れない場合は、まずこの値を疑う
• exclude_toolsの綴りをツール定義と一致させていない: ツール名はリクエストの tools 配列で定義した name と完全一致させる必要があり、表記揺れがあると保護されない
• clear_tool_inputsを有効にしたままデバッグする: 引数まで消えると、後から会話履歴を見返してもClaudeが元々何を呼び出そうとしていたか分からなくなる。デバッグ中は false(既定)のままにしておくと調査しやすい

compactionとの使い分け

context_management.edits には clear_tool_uses_20250919 以外の戦略も同じ配列に並べられます。代表例が会話全体を要約で置き換える compact_20260112(compaction)です。公式ドキュメントはcompactionを「長時間の会話やエージェントワークフローで推奨される既定の戦略」と位置づけ、tool result clearingはそれよりも「クリアする対象を細かく制御したい特定シナリオ」向けと整理しています。

エージェントが大量のファイル読み込みや検索ツールを繰り返すワークフローでは、要約で文脈を潰すよりも「古い結果だけプレースホルダに置き換える」ほうが、直近のツール呼び出しの整合性を保ちやすいという判断でtool result clearingが選ばれます。ツール利用そのものがどれだけトークンを消費するかはClaudeのツール利用で増えるトークン数、tool_resultの整形ルールでつまずく場合はtool_resultとtool_useの400エラーで扱っています。

exclude_toolsとclear_tool_inputsを一緒に考える

exclude_tools は「クリアするかどうか」を丸ごと切り替えるツール単位のスイッチですが、clear_tool_inputs は「クリアするときにどこまで消すか」を決める粒度のスイッチです。両者は独立に効くため、exclude_tools で保護していないツールに対しては clear_tool_inputs の設定がそのまま適用されます。例えばclear_tool_inputs: trueにすると、exclude_toolsに列挙していない全ツールで呼び出しの引数まで消える点に注意します。特定のツールだけ引数は残したいが結果は消したい、という細かい制御はこの2パラメータの組み合わせでは表現できず、そのツールを丸ごとexclude_toolsに入れるか、諦めるかの二択になります。

クライアント側の会話履歴は変えなくていい

context editingはリクエストがClaudeに届く前にサーバー側で適用されます。クライアントアプリケーションは会話履歴をそのまま保持し続ければよく、クリアされた版と同期を取り直す必要はありません。次のリクエストでも、あなたのコードは通常どおり全文を送信し、サーバー側が毎回そのリクエストの内容に応じてクリアするかどうかを判断します。この「クライアントは何も変えなくていい」という設計は、tool result clearingの導入コストを小さくしている理由の一つです。長時間のエージェントセッションをローカルで完全な履歴として保存しつつ、API側だけがコストと文脈量を制御する構成が組めます。

対応モデル

context editing自体は、サポートされているすべてのClaudeモデルで利用できます。thinking block clearingのようにモデルクラスごとにデフォルトの挙動が異なる戦略もありますが、tool result clearingの5パラメータの意味自体はモデルによって変わりません。

まとめ

tool result clearingは trigger / keep / clear_at_least / exclude_tools / clear_tool_inputs の5つのパラメータで挙動を制御します。何も指定しなければ入力100,000トークンで発動し直近3件を残す既定動作になり、キャッシュ効率を優先するなら clear_at_least で最低クリア量を保証し、重要なツールは exclude_tools で保護します。適用結果は context_management.applied_edits で確認できるので、実運用のログを見ながら閾値を調整するのが実践的な使い方です。