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 — いつクリアを始めるか

単位は input_tokens(トークン数)と tool_uses(ツール呼び出しの回数)から選べます。表の既定値は入力トークン数で数えた100,000です。

keep — 直近何件を残すか

単位は tool_uses で、後述の実装例では3を指定しています。残す件数の決め方は、count_tokens で3、5、10と変えて削減量を比べる手順で扱います。

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

1回のクリアで最低限消すトークン数を input_tokens で指定します。キャッシュとの関係は、後述のつまずきやすい点で扱います。

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

列挙したツール名の呼び出しと結果は、クリア対象から常に除外されます。後続のターンで参照され続けるツールを守るのに使います。

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

既定で消えるのはtool_resultだけで、Claudeが送ったツール呼び出し(引数を含む)は履歴に残ります。true にすると、結果と一緒に引数も消えます。設定表にあるのは編集1件ごとの clear_tool_inputs だけで、ツールごとに切り替える項目はありません。exclude_tools に入れたツールは引数も結果も残り、入れていないツールには clear_tool_inputs の値がそのまま適用されます。

実装例 — 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-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がファイルの読み書きを繰り返し、古い版のファイル内容が会話に残り続けます。これはクリアしてよい結果です。後で引用したい検索結果は exclude_tools で守ります。

発動する前に、クリア後のトークン数を試算する

token countingエンドポイント(/v1/messages/count_tokens)も context_management を受け取ります。クリアを適用した後のトークン数を、実際にメッセージを送らずに見積もれます。trigger や keep の候補を試すときに使います。

curl https://api.anthropic.com/v1/messages/count_tokens \
    --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-5",
        "messages": [{"role": "user", "content": "Continue our conversation..."}],
        "context_management": {
            "edits": [
                {
                    "type": "clear_tool_uses_20250919",
                    "trigger": {"type": "input_tokens", "value": 30000},
                    "keep": {"type": "tool_uses", "value": 5}
                }
            ]
        }
    }'

レスポンスの input_tokens がクリア後の値、context_management.original_input_tokens がクリア前の値です。2つの差が、その設定で削れるトークン数になります。実際の会話履歴を messages に入れて、keep を3、5、10と変えながら差を比べると、残す件数の目安をつけやすくなります。

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

クリアが適用されたかどうかは、レスポンスの 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 イベントに入ります。

サーバーツールの結果の自動キャッシュはサーバーツール結果の自動キャッシュで扱っています。

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

tool result clearingは、クリアしたときにキャッシュ済みのプロンプトプレフィックスを無効化します。クリアのたびにキャッシュ書き込みコストが発生し、その後のリクエストは新しいプレフィックスを再利用できます。

clear_at_least は、この無効化に見合う量をまとめてクリアするための項目です。thinking blockのクリアは性質が逆で、blockを残している間はキャッシュが保たれ、クリアした位置でキャッシュが無効になります。

memory toolと組み合わせて、消える前に書き出させる

context editingは、memory toolと併用できます。会話がクリアのしきい値に近づくと、Claudeは重要な情報を保存するよう自動で警告を受け取ります。これにより、tool_resultが消える前に必要な内容をmemoryファイルへ書き出せます。

{
  "tools": [{"type": "memory_20250818", "name": "memory"}],
  "context_management": {
    "edits": [{"type": "clear_tool_uses_20250919"}]
  }
}

ファイル編集を何十回も重ねるワークフローなら、完了した変更の要約をmemoryに残させ、古い編集結果はクリアする、という分担になります。消えた情報は、必要になったときにmemoryファイルから引き直せます。

thinking block clearingと併用する(順序に注意)

拡張思考を使うエージェントでは、clear_thinking_20251015 と同じ edits 配列に並べられます。clear_thinking_20251015 は配列の先頭に置く必要があります。

{
  "edits": [
    {"type": "clear_thinking_20251015", "keep": {"type": "thinking_turns", "value": 2}},
    {
      "type": "clear_tool_uses_20250919",
      "trigger": {"type": "input_tokens", "value": 50000},
      "keep": {"type": "tool_uses", "value": 5}
    }
  ]
}

thinking blockの既定の扱いはモデルによって違います。Opus 4.5以降、Sonnet 4.6以降、FableとMythosは過去のthinkingをすべて残します。Opus 4.1以前、Sonnet 4.5以前、Haiku 4.5までは直近ターンのthinkingだけを残します。複数のモデル階層で同じコードを動かすなら、keep を明示すると挙動がそろいます。

compactionとの使い分け

context_management.edits には clear_tool_uses_20250919 以外の戦略も並べられます。context editingのページは、長い会話の文脈管理ではサーバーサイドのcompaction(要約による圧縮)が主要な戦略で、クリアは「何を消すかを細かく制御したい場面」向けと位置づけています。

compactionは現在2種類あり、どちらもベータです。1つはアプリケーション側が要約を依頼するタイミングを決めるオンデマンド型(ベータヘッダー compact-2026-09-04、トップレベルの compaction パラメータ)です。もう1つは入力トークンが設定したしきい値に達したときにAPIが自動で要約するしきい値型で、edits に compact_20260112 を足して使います(ベータヘッダー compact-2026-01-12)。

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

よくあるつまずき

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

context editingは、リクエストがClaudeに届く前にサーバー側で適用されます。クライアントは完全な履歴を持ち続け、毎回全文を送ります。クリア後の履歴との同期は要りません。

ただし、クライアント側で過去のターンを書き換えるのは別の話です。Claude Fable 5.1、Claude Opus 5.5、Claude Sonnet 5.5では、サーバー側のコンテキスト管理がthinking blockを無効にすることはありません。一方、クライアント側での過去ターンの編集は、それ以降のassistantターンすべてのthinking blockを無効にしえます。2026年8月31日以降に作成されたアカウントでは、無効になったblockを再送するリクエストは、破棄を明示的に選ばない限り拒否されます。

対応モデル

context editing自体は、サポートされているすべてのClaudeモデルで使えます。

まとめ

まず既定値のまま動かして applied_edits の削減量を見て、そのうえで trigger と keep を詰めると外しにくくなります。