Claudeのinput_examplesでツール呼び出し精度を上げる使い方

このTipsでできること

ツール定義のdescriptionをどれだけ詳しく書いても、ネストしたオブジェクトやフォーマット依存のパラメータではClaudeが型を取り違えることがあります。input_examplesは、ツール定義に具体的な入力例を1〜5個添えて、この隙間を埋めるフィールドです。この記事では書き方の基本、効くツールと効かないツールの見分け方、公式ドキュメントが示すトークンコストの実測値、そしてサーバーツールでは使えないという制約をまとめます。

input_examplesの基本 — スキーマだけでは伝わらない「使い方」を渡す

input_examplesはツール定義に追加できる省略可能な配列フィールドです。各要素はそのツールのinput_schemaに対して妥当な入力オブジェクトでなければなりません。妥当でない例を混ぜるとリクエストごと400エラーで弾かれます。

ツール定義は、Claude APIへのリクエストにtoolsパラメータを渡すと、専用のシステムプロンプトへ組み込まれます。ツールの名前・description・input_schemaをJSON Schema形式でまとめた塊が、ユーザーのシステムプロンプトやツール設定と一緒に構築される仕組みです。input_examplesもこの塊の一部としてそのままプロンプトに乗るため、例を足すほど直接プロンプトトークンが増えます。裏側で特別な圧縮や要約が入るわけではありません。

天気を調べるツールを例にすると、次のように書きます。

{
  "name": "get_weather",
  "description": "指定した地域の現在の天気を取得します",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "都市名と州、例: San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["location"]
  },
  "input_examples": [
    { "location": "San Francisco, CA", "unit": "fahrenheit" },
    { "location": "Tokyo, Japan", "unit": "celsius" },
    { "location": "New York, NY" }
  ]
}

3つ目の例だけunitを省いてあります。「unitは省略できる」という事実を、required配列の裏読みに頼らずClaudeへ直接示せます。渡した例はツールスキーマと並べてプロンプトに組み込まれ、Claudeはそこから妥当な呼び出しの具体的なパターンを読み取ります。実際にAPIへ投げる形は次のとおりです。

curl -sS https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @tool-with-examples.json

input_examplesはツール定義のプロパティとして標準化されており、有効化にベータヘッダーは要りません。2025年11月にTool Use Examplesという名で公開された時点ではanthropic-beta: advanced-tool-use-2025-11-20が必須でした。今はほかのツール定義フィールドと同列に、tools配列へ書くだけで使えます。

効くツールと効かないツールの見分け方

公式ドキュメントが繰り返し強調しているのは、精度に最も効くのは詳細なdescriptionだということです。ツールが何をするか、どんな場面で使う想定か、各パラメータが何を意味するかを3〜4文以上で書きます。input_examplesはこの代わりではなく補完に位置づけられています。ツール設計そのものの原則(命名・粒度・レスポンス設計)はエージェント向けツール設計の原則にまとめてあります。input_examplesはこの設計が固まったあとの仕上げの一手として使うのが順序として自然です。

効果が出やすいのは、descriptionの文章だけでは呼び出しの形が一意に定まりにくいツールです。具体的には次のようなツールが該当します。

• ネストしたオブジェクトや配列を受け取るツール
• 日付・座標・IDのようにフォーマットが厳密なパラメータを持つツール
• 省略可能なパラメータが多く、組み合わせパターンを文章だけで説明しにくいツール

逆に、パラメータが1〜2個で意味も明確なツールに例を足しても、トークンを消費するだけでほとんど効果は出ません。シンプルなツールほどdescriptionだけで十分です。

公式ドキュメントは、良いdescriptionと不十分なdescriptionの差を株価取得ツールの例で示しています。不十分な例は「ティッカーの株価を取得します」のように1文だけで、パラメータの説明も付いていません。良い例は、何を返すか・どんな場面で使う想定か・tickerパラメータが何を意味するかまで含めて3〜4文で書かれています。この差は、モデルがツールをいつ・どう呼ぶかを判断する材料の量そのものです。input_examplesを検討するのは、このレベルまでdescriptionを詰めてもなお型やフォーマットの取り違えが残る場合に限られます。

良い例の組み方 — 押さえておきたいパターン

例をただ並べるだけでは効果が薄くなります。公式ドキュメントの用例が示している設計意図は、それぞれの例に別々の役割を持たせることです。get_weatherの3つの例を見返すと、1つ目は必須パラメータと省略可能パラメータの両方を埋めた基本形、2つ目は同じ形の別の値、3つ目は省略可能パラメータを欠いた形になっています。3つで済ませず、次のようなパターンを意識すると網羅性が上がります。

• 必須パラメータのみを埋めた最小形
• 省略可能パラメータをすべて埋めたフル形
• enumの選択肢ごとに1つずつ(選択肢が多い場合は代表的なものだけ)
• ネストしたオブジェクトなら、ネストの深さが異なる2パターン

上限は1ツールあたり5個です。これを超えて積んでも受け付けられないため、上記のパターンから優先度の高いものを選んで絞り込みます。

座席予約のように複数のネストしたフィールドを持つツールなら、次のように書きます。

{
  "name": "book_flight",
  "input_examples": [
    {
      "origin": "NRT",
      "destination": "SFO",
      "passengers": [
        { "name": "Taro Yamada", "seat_class": "economy" }
      ]
    },
    {
      "origin": "HND",
      "destination": "JFK",
      "passengers": [
        { "name": "Hanako Sato", "seat_class": "business" },
        { "name": "Jiro Sato", "seat_class": "business", "meal_preference": "vegetarian" }
      ]
    }
  ]
}

1つ目の例は乗客1名の最小形、2つ目は乗客2名かつ省略可能なmeal_preferenceを含むフル形です。passengers配列の要素数や、省略可能フィールドの有無をコード側のバリデーションだけで説明するより、この2例を並べたほうがClaudeにとって具体的です。

トークンコストの実測値

input_examplesはプロンプトトークンを消費します。公式ドキュメントが示す目安は次のとおりです。

例は1つのツールにつき最大5個まで積めます。複雑なネスト構造を持つツールに5個の例を渡すと、単純計算で500〜1,000トークン近くまで積み上がります。10個のツールそれぞれに複雑な例を2〜3個添える構成なら、それだけで1,000〜3,000トークンをツール定義側で消費する計算です。

この上乗せが効いてくるのは、同じツールセットを何千回・何万回と呼び出す構成です。ツール定義は会話のたびに繰り返し送られる部分なので、単発呼び出しを大量に捌くバッチ処理や分類パイプラインでは、リクエストあたりの固定コストが積み重なります。プロンプトキャッシングでツール定義をキャッシュ対象に含めておけば、2回目以降のリクエストではこのコストの大半をキャッシュ読み取りの単価で吸収できます。逆に、ツール定義そのものやtool_choiceの設定を毎回変えるような使い方では、キャッシュが当たらずフルコストがそのままかかります。

サーバーツールとcomputer use / browser useでは使えない

input_examplesが対応するのは、ユーザーが定義したクライアントツールと、Anthropicが提供するクライアントツールの一部だけです。次の2種類には使えません。

• サーバーツール: web検索やコード実行のように、Anthropicのサーバー側で実行されるツール
• computer useとbrowser useのツールセット: クライアント側で動くものの、computer_toolset_20260801・browser_toolset_20260801という専用のツールセット形式を持つため対象外

対応するのは自分でinput_schemaを書いた通常のクライアントツールだけ、と考えて設計するのが実務的です。この制約はトークンコストの制約とセットで効いてきます。サーバーツールに寄せたエージェント構成では、そもそもinput_examplesの出番自体が限られるからです。混在構成でクライアントツールとサーバーツールを同じリクエストに含める場合も、input_examplesを書けるのはクライアントツール側のエントリだけになります。

要件と制約をまとめると次のとおりです。

どんな症状のときにinput_examplesが挙がるか

公式のトラブルシューティングガイドは、input_examplesを単独の機能としてではなく、他の対処法と並ぶ選択肢として扱っています。3つの典型症状と、それぞれで挙がる対処の候補は次のとおりです。

input_examplesが候補として挙がるのは、descriptionの曖昧さを実例で埋める即効性のある手段だからです。スキーマがstrict tool useの対応範囲(サポート対象のJSON Schemaサブセット)に収まる場合はstrict: trueのほうが確実です。対応範囲外の複雑なスキーマでは、input_examplesが実質的な代替になります。両者は排他ではなく、strict: trueとinput_examplesを同じツールに同時設定することもできます。

Advanced Tool Useは、Tool Search Tool・Programmatic Tool Callingと合わせてこのinput_examples(Tool Use Examples)を含む3つの機能をまとめて解説した記事です。共通の課題はコンテキスト圧迫と精度低下です。本記事はその3つ目の機能に絞り、トークンコストと適用対象という実装判断に直結する部分を深掘りしています。

input_examplesを書く作業には、もう1つ副次的な効果があります。ツール定義のJSONファイル自体が、そのままチーム内のリファレンスとして読めることです。descriptionの文章だけでは「結局どんなJSONを送ればいいのか」を実装者が毎回スキーマから逆算する必要がありますが、妥当な入力例が2〜5個並んでいれば、コピーして書き換えるだけで済みます。Claude向けの説明とエンジニア向けのサンプルコードを1つのフィールドで兼ねられる点は、コスト以上に運用上の利点です。

まとめ

input_examplesはdescriptionを補う位置づけで、ネストしたオブジェクトやフォーマット依存のパラメータを持つ複雑なツールに効きます。シンプルなツールには不要です。追加コストはシンプルな例で約20〜50トークン、複雑な例で約100〜200トークンで、5個まで積めば1ツールあたり1,000トークン近くまで積み上がります。サーバーツールとcomputer use / browser useのツールセットには使えません。ツール定義を書くときは、まずdescriptionを詳細に書き切り、それでも取り違えが残る複雑なツールだけにinput_examplesを足す順番がコストと効果のバランスに合っています。