プログラマティックツールコーリングのコスト削減効果 — 効くワークロードと効かないワークロード

プログラマティックツールコーリングは、ツール呼び出しの中間結果をClaudeの文脈に流さずコードで処理することで、トークン消費と往復回数を減らす仕組みです。ただし削減幅は一律ではありません。開示されている実測値では、75ツール構成のベンチマークで入力トークンが38%減る一方、逐次的なツール呼び出しが中心のτ²-benchでは逆に8%のコスト増になっています。同じ機能が正反対の結果を出す理由は、ワークロードの形にあります。

呼び出しの途中でトークンが減る仕組み

Claudeがツールを直接呼ぶ方式では、ツールを1回呼ぶたびにモデルへ戻り、結果が丸ごと文脈に積まれます。プログラマティックな呼び出しでは、この往復がコード実行の内側に移ります。

手順

1回のコード実行で何が起きるか

1. 1

   Claudeが Python を書く

   ツールを非同期のPython関数として呼ぶコードです。複数のツール呼び出しと、前後の加工処理を1本にまとめられます。

2. 2

   サンドボックスのコンテナで実行する

   コード実行ツールのコンテナ上で走ります。

3. 3

   ツールが呼ばれるたびに一時停止する

   APIがtool_useブロックを返し、コードは待機します。

4. 4

   アプリが結果を返す

   結果はコードに渡るだけで、Claudeの文脈には入りません。

5. 5

   最終出力だけがClaudeに届く

   コードが最後まで走り、出力されたものだけをClaudeが読んで作業を続けます。

文脈に載らないので、プログラマティックな呼び出しの結果は入力・出力のトークン使用量にも数えられません。数えられるのは、最終的なコード実行結果とClaudeの応答です。「10ツールを直接呼ぶと、プログラマティックに呼んで要約だけ返す場合の約10倍のトークンを使う」という説明もありますが、これは10ツールすべてをコード内で処理しきる理想条件での比較です。実際のワークロードで同じ倍率が出るわけではなく、導入判断には次節以降の実測値のほうが向いています。

具体例で見る削減の仕組み — 20人分の経費チェック

公式の例は、20人の従業員について予算超過をチェックするタスクです。従来の方式では、1人ずつ経費データを問い合わせるため20回分のモデルとの往復が発生し、各従業員の経費明細が数千行単位でそのまま文脈に流れ込みます。プログラマティックツールコーリングでは、1本のスクリプトが20回分の照会をまとめて実行し、予算を超えた従業員だけを返します。Claudeが最終的に読むのは数百キロバイトの生データではなく、数行の結果です。

この例が示しているのは、削減幅が「呼び出し回数」と「1回あたりの結果サイズ」の掛け算で決まるという構造です。呼び出しが1〜2回で結果も小さいなら、掛け算の答えそのものが小さく、コンテナ起動などの固定オーバーヘッドの比重が相対的に大きくなります。

実測値は38%削減から8%増加まで割れている

Anthropicの社内評価と本番トラフィックの集計で示されている数字は、次の4つです。

数字

プログラマティックツールコーリングの実測

• 75ツールのPM エージェント

  入力 約38%減

  精度は変化なし

• ツール定義 10〜49個の本番リクエスト

  20〜40%減

  典型的なトークン削減幅

• τ²-bench(逐次1〜2回/ターン)

  約8%増

  スコアは変化なし

• BrowseComp / DeepSearchQA

  入力 24%減

  平均11%の性能改善

75ツールの例は、プロジェクト管理を題材にしたエージェントのベンチマークです。単一のベンチマークだけでなく、tools配列に10〜49個のツール定義を含む実運用に近いリクエストでレンジが示されている点は、実装判断の参考になります。

BrowseCompとDeepSearchQAは、複数ステップのWeb調査や複雑な情報検索を評価するベンチマークです。基本的な検索ツールにプログラマティックツールコーリングを重ねた結果で、web_searchのdynamic filteringが使う仕組みとも関係します。トークン削減だけでなく精度側にも効果が及ぶケースがあることを示す例です。

反対側にあるのがτ²-benchです。航空・小売・通信ドメインを扱い、1ターンにつき1〜2回の連続したツール呼び出しが中心のため、スコアは変わらずコストだけが増えました。公式はこの結果を「Sequential single-call workflows do not benefit.」と総括しています。コンテナの起動とコード生成には固定のオーバーヘッドがかかり、1ターンに1〜2回しかツールを呼ばない構成では、この固定費用が節約分を上回りうることが、公式の挙げる理由です。

効くワークロードと効かないワークロード

向く条件と向かない条件は、公式のベストプラクティスで明示的に切り分けられています。

くらべる

プログラマティックツールコーリングの向き不向き

ファンアウト・集約型

向く

• 多数の項目への並列処理。50エンドポイントの死活監視、20件のレコード照会など
• フィルタ・集計・要約してから文脈に渡したい大きなツール結果
• 反復的なクエリと絞り込みが中心の検索・情報収集

逐次・小規模型

向かない

• 各呼び出しがClaudeの推論結果に依存する、厳密な逐次ワークフロー
• レスポンスの小さいツール呼び出しが少数だけの構成。特に会話の最初のターン
• 呼び出しの合間にユーザーの即時フィードバックが必要なツール

会話の最初のターンが向かない側に入っているのは、コンテナの起動とスクリプト生成のオーバーヘッドが、節約分を上回りうるためです。

数字が割れる理由をどう読むか

38%削減と8%増加を並べると、プログラマティックツールコーリングは「効果のある機能」というより「ワークロードの形を測る機能」と捉えるほうが実態に近く見えます。ファンアウトや並列処理が多いエージェントほど、モデルの推論を挟まずコードで完結させる余地が大きくなります。1ステップずつClaudeの判断を挟む必要があるワークフローでは、コード実行という別レイヤーを挟むこと自体が純粋なオーバーヘッドです。

この機能の初出は2025年11月のAdvanced Tool Useです。当時示されていたのは、複雑な調査タスクで平均43,588トークンから27,297トークンへ37%削減、という単一の数字でした。現在のドキュメントは、75ツールのベンチマークとτ²-benchという性質の異なる2つの実測を並べ、「実際の削減幅はワークロードの形で変わる」と明記しています。

向くワークロードでも有効にできない構成がある

ワークロードが向いていても、API側の制約で有効にできない構成があります。トークン削減の試算に入る前に、次の項目に当たらないかを見ておくと手戻りを避けられます。

• strict: trueのツール: 厳格なツール使用を設定したツールは、プログラマティックな呼び出しに対応していません
• tool_choiceでの強制: 特定のツールをプログラマティックに呼ぶようtool_choiceで強制はできません。allowed_callersに"direct"を含まないツールをtool_choiceで指名すると、HTTP 400のinvalid_request_errorになります
• disable_parallel_tool_use: true: 併用できません。disable_parallel_tool_useの挙動を使っている構成では、削減効果の前提そのものが外れます
• MCPコネクタのツール、computer use、browser use: プログラマティックには呼べません。computer useとbrowser useのツールセットは、allowed_callersが"direct"のみを受け付けます
• 再帰する$refを持つスキーマ: input_schemaが自己参照を含むツールでallowed_callersにコード実行を入れると、Circular $ref detectedを含む400エラーになります。同じスキーマを直接呼び出しで使うことはできます

MCPコネクタ経由のツールを中心にした構成では、対象外であること自体が導入の壁になります。ZDR(ゼロデータリテンション)についても、この機能は対象外と表示されています。コンテナ内の実行成果物や出力は、最長30日間保持されます。

往復の途中で起きる時間切れと、戻し方のルール

コードがツール結果を待っている間は、時計が動いています。結果が約4分以内に届かないと、待機中の呼び出しはコード内でTimeoutErrorになります。Claudeはstderrでそのエラーを見て、多くの場合は呼び出しをやり直します。アイドル状態のコンテナも約5分で回収されるため、長いDBクエリやバッチを内側に置くツールでは、再試行がそのままトークンと時間の追加コストになります。

返し方にも決まりがあります。

• 一時停止中の呼び出しがあるときは、応答メッセージにtool_resultブロックだけを入れます。結果の後ろにもテキストは足せません
• その継続リクエストには、一時停止した応答に付いていたコンテナIDを渡します。渡さないとAPIはリクエストを拒否します
• ツールがエラーを返したときは、エラー文字列をそのままtool_resultに入れると、コードの側でそれを処理できます

コンテナIDの受け渡しを含む往復の組み立ては、一時停止から再開まで1つのループにまとめるのが基本形です。

コード実行のオーバーヘッドと組み合わせて考える

プログラマティックツールコーリングはコード実行ツールの上に成り立つ機能で、料金もコード実行と同じです。コード実行は、web_search_20260209以降またはweb_fetch_20260209以降を同じリクエストに含めると、標準のトークン料金を超える追加課金がありません。それ以外の使い方では実行時間で課金され、実行時間は最低5分、組織ごとに月1,550時間までが無料、超過分はコンテナ1つあたり1時間$0.05です。

トークン削減の数字だけで導入を決めると、この実行時間課金を見落とします。逐次ワークフロー寄りの構成に無理に入れると、τ²-benchの実測が示すとおり、トークンの面でコストが増える可能性があります。

導入する場合に効果を底上げする2点

向くワークロードだと判断して導入する場合でも、実装の仕方で削減幅は変わります。公式のパフォーマンス最適化に挙がっているのは次の2点です。

• 関連するリクエストではコンテナを再利用する: 同じコンテナIDを渡すと、状態を維持したままファイルやインタープリタの中身を引き継げます。毎回新規コンテナを作ると起動コストが積み上がります
• 似た操作は1回のコード実行にまとめる: 複数の操作を1本のスクリプトに詰め込むと、呼び出しの起動・停止に伴うオーバーヘッドの回数が減ります

38%削減や20〜40%削減という数字は「機能を有効にしただけ」で得られる保証値ではなく、実装の組み方で変動する幅です。ツール設計そのものの原則(エージェント向けツール設計の原則)を満たしたうえで、この2点を意識して初めて、示されている削減幅に近づけます。Claudeがコードで結果を読む以上、ツールの戻り値のJSON構造とフィールドの型を説明に書いておくことも、公式のツール設計の指針に入っています。

まとめ

プログラマティックツールコーリングは、多数の呼び出しと大きな結果を1回のコード実行に畳める構成で効き、1ターンに1〜2回しか呼ばない逐次型ではコストが増える機能です。導入前に、ツールが非対応の構成に当たっていないかを見たうえで、allowed_callersの有無で課金対象トークンを実測してから広げるのが判断の筋道になります。