Programmatic Tool Callingとは？トークン削減の仕組み

Programmatic Tool Callingは、複数ツールの中間結果をコード内で処理し、Claudeへ返す情報を絞ることで、トークンとモデルの往復を抑える仕組みです。

AIエージェントに検索、データ取得、集計などを任せると、ツールを呼ぶたびに中間結果が増え、入力トークンや処理時間が膨らむことがあります。ツール数が多いシステムほど、必要のないデータまでClaudeのコンテキストへ入りやすくなるためです。

Programmatic Tool Calling（以下、PTC）は、Claudeがコード実行環境から複数のツールを呼び、取得したデータをコード内で絞り込む仕組みです。この記事では、PTCの基本、トークンが増える理由、関連機能との使い分け、導入前の測定方法を整理します。

この記事でわかること（結論）

• PTCの仕組み：複数ツールの中間結果をコード内で処理し、必要な結果だけをClaudeへ返す。
• 削減の考え方：ツール結果、ツール定義、パラメータ設計を分けて最適化する。
• 向いている処理：多数件の照会、大量データの集計、検索結果の絞り込みで効果を見込みやすい。
• 導入時の判断：トークン数だけでなく、精度、処理時間、完了率を同じ条件で比較する。

Programmatic Tool Callingとは？

Programmatic Tool Callingは、Claudeがコード実行コンテナ内から許可されたツールを呼び、複数の処理をコードでまとめて進める機能です。ツールごとにClaudeの判断へ戻る回数を減らし、中間データがコンテキストへ積み上がるのを抑えます。

従来方式は呼び出しごとにClaudeへ戻る

従来のツール呼び出しでは、「Claudeがツールを選ぶ」「ツールを実行する」「結果をClaudeへ返す」「次の処理を判断する」という流れを繰り返します。取得結果、エラー情報、次の入力に使うデータが会話履歴へ追加されるため、処理が長くなるほど入力トークンも増えます。

データ取得、集計、フィルタリング、変換を別々のツールで行う場合、最終回答に使わない中間データまでClaudeが参照する状態になりやすくなるのです。

PTCは中間処理をコード内で進める

PTCでは、Claudeがワークフローを進めるコードを生成し、コード実行環境から複数のツールを呼びます。取得したデータの並べ替え、集計、条件分岐、不要データの除外をコード内で行い、最終的な結果だけをClaudeへ返せます。

Anthropicの公式ドキュメントでは、プログラム経由のツール結果はClaudeのコンテキストへ追加されず、最終的なコード実行結果だけが入ると説明されています（出典：Anthropic「Programmatic tool calling」、2026年1月20日）。

公式実装例ではトークンを85.6％削減

Claude Cookbookの経費監査例では、従来方式の110,473トークンに対し、PTCでは15,919トークンとなり、85.6％の削減が示されています。処理対象やツール構成によって結果は変わりますが、中間データが大きい処理ほど削減効果を確認しやすい例です（出典：Claude Cookbook「Programmatic tool calling」、2025年11月24日）。

複数ツールでトークンが増える3つの理由

複数ツール連携でトークンが増える主な理由は、中間結果、ツール定義、モデルの往復処理の3つです。ツール数だけを減らすのではなく、どの部分がコンテキストを使っているかを分けて確認する必要があります。

中間結果が会話履歴へ積み上がる

複数のAPIへ順番に問い合わせる処理では、入力パラメータ、取得データ、エラー情報が呼び出しごとに増えます。最終回答に不要な行や項目でも、従来方式ではClaudeが次の判断をするために受け取る場合があります。

大量のログ、複数人分の明細、多数の検索結果を扱う処理では、中間結果をClaudeへ返す前にコードで絞る設計が有効です。

ツール定義がコンテキストを使う

ツールを利用するには、名称、説明、入力パラメータ、制約などの定義が必要です。利用可能なツールをすべて最初から読み込む設計では、実際には使わないツールの定義まで入力トークンを消費します。

この使わないツールの定義まで読み込んでしまう問題への対策として、必要なツールだけを後から読み込む方法があります。その代表例が、AnthropicのTool Searchです。

Tool Searchは、必要なツール定義だけをオンデマンドで読み込む機能です。公式ドキュメントでは、一般的な複数サーバー構成でツール定義によるトークン使用量を85％超削減し、必要な3〜5個のツールだけを読み込む例が示されています（出典：Anthropic「Tool search tool」）。

呼び出しごとにモデルの推論が入る

従来方式では、ツール結果が返るたびにClaudeが内容を読み、次のツールや条件を判断します。順番に依存する工程が多いほど、モデルの往復回数と処理時間が増えます。

ループ、条件分岐、並列実行、数値集計をコードで表現できる処理は、PTCによってモデルの往復を減らしやすい領域です。

トークン削減は原因に合わせて方法を選ぶ

複数ツール連携のトークンを減らす方法は、PTCだけではありません。どこでトークンが増えているかによって、適した対策が変わります。

中間結果が大きい場合はPTC、最初に読み込むツール定義が多い場合はTool Searchというように、問題ごとに役割を分けて考えると整理しやすくなります。

方法	主な役割	向いている状況
Programmatic Tool Calling	中間結果とモデルの往復を減らす	多数件の照会、集計、検索結果の絞り込み
Tool Search	必要なツール定義だけを読み込む	利用できるツールが多い環境
スキーマ整理	説明文やパラメータの重複を減らす	似た定義を持つツールが多い環境
Tool Use Examples	複雑な入力方法をClaudeへ示す	入れ子構造や任意項目が多いツール

Tool Use Examplesは、直接トークンを減らす機能ではなく、複雑なツールを正しく使わせるための補助策です。入力例を増やすほどプロンプトも長くなるため、必要なツールへ限定して使います。

効果測定はトークン数だけで判断しない

PTCの導入効果は、入力トークンの削減率だけでは判断できません。出力品質の低下やリトライの増加を見落とさないため、同じタスクで複数の指標を比較します。

最低限、次の4項目を記録します。

1. 入力・出力トークン：従来方式とPTC方式で、請求対象の使用量を比較します。
2. 処理時間：モデルの往復、コード実行、外部APIの待ち時間を含めて測ります。
3. ツール呼び出し回数：直接呼び出しとプログラム経由の呼び出しを分けて記録します。
4. タスク品質：正答率、完了率、再実行率、人による修正量を確認します。

同一のタスクセットでA/Bテストを行い、利用モデル、ツール数、データ量、測定期間をそろえると比較しやすくなります。単発の成功例ではなく、実際の業務に近い複数ケースで確認することが重要です。

Anthropicのエージェント検索ベンチマークでは、基本的な検索ツールへPTCを加えた結果、入力トークンを24％減らしながら、平均性能が11％向上したと報告されています。ベンチマーク結果は自社環境へそのまま当てはめず、同じ測定軸で再現性を確認してください（出典：Anthropic「Programmatic tool calling」、2026年1月20日）。

実務上の注意

PTCを実務へ組み込む際は、ログ、機能の役割分担、外部データの検証という3点を先に設計します。

中間処理を追跡できるログを残す

PTCでは、中間結果の大部分がClaudeのコンテキストへ入りません。トークンを減らせる一方で、どのツールがどの入力で失敗したかを会話履歴だけでは追いにくくなります。

ツール名、入力、結果、エラー、呼び出し元、実行時刻をログへ残し、ツール単体でもテストできる状態にします。Anthropicの公式ドキュメントも、すべてのツール呼び出しと結果を記録し、呼び出し元を示すcallerフィールドを確認する方法を案内しています（出典：Anthropic「Programmatic tool calling」）。

PTCとTool Searchを混同しない

PTCはツール実行後の中間結果とモデル往復を減らす機能で、Tool Searchは実行前に読み込むツール定義を減らす機能です。トークン増加の原因が異なるため、片方だけでは解決しない場合があります。

ツール定義が大きい場合はTool Search、ツール結果が大きい場合はPTC、入力パラメータのミスが多い場合はTool Use Examplesを優先すると、導入目的を整理しやすくなります。

外部ツールの結果を実行前に検証する

プログラム経由で受け取るツール結果は文字列であり、外部入力や実行可能な内容を含む可能性があります。ツール結果をコードやコマンドとして扱う場合は、形式、許可値、文字列の内容を検証する必要があります。

外部データをそのまま実行せず、JSONスキーマによる検証、許可リスト、エスケープ処理、実行権限の制限を組み合わせます（出典：Anthropic「Programmatic tool calling」）。

まとめ

Programmatic Tool Callingは、複数ツールの中間結果をコード内で処理し、Claudeへ返す情報を必要最小限にする方法です。

まずは大量データの集計や多数件の照会など、効果を測りやすい一つの処理へ限定し、トークン、処理時間、完了率、修正量を従来方式と比較してみてください。

よくある質問

関連する用語・出典

• Programmatic Tool Calling：Claudeがコード実行環境から複数のツールを呼び、中間結果を処理する機能です（Anthropic公式ドキュメント）。
• Tool Search：必要なツール定義を検索し、オンデマンドで読み込む機能です（Anthropic公式ドキュメント）。
• Tool Use Examples：ツール定義へ具体的な入力例を追加し、複雑なパラメータの使い方を示す方法です（Anthropic公式解説）。
• Claude Cookbook：Claude APIの実装例を確認できる公式資料です（PTCの実装例）。
• コンテキストウィンドウ：AIが回答を作る際に一度に参照できる情報の範囲です。ツール定義や中間結果も、この範囲を使用します。

※本文中のベンチマーク結果は、Anthropicが示した特定条件での評価です。実際の削減率や処理性能は、利用モデル、ツール数、戻り値の大きさ、処理順序によって変わります。公式情報の確認日：2026年8月17日。