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

このTipsでできること

ツール定義のdescriptionをどれだけ詳しく書いても、ネストしたオブジェクトやフォーマット依存のパラメータではClaudeが型を取り違えることがあります。input_examplesは、ツール定義に具体的な入力例を添えて、この隙間を埋めるフィールドです。書き方、効くツールと効かないツールの見分け方、トークンコストの目安、そして使えないツールの種類を順に見ていきます。

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

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

toolsパラメータを付けてClaude APIを呼ぶと、ツール定義・ツール設定・ユーザーのシステムプロンプトから、ツール使用専用のシステムプロンプトが組み立てられます。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へ直接示せます。実際に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

define-toolsの例では、ベータヘッダーなしでinput_examplesを指定しています。2025年11月にTool Use Examplesという名で公開された時点では、anthropic-beta: advanced-tool-use-2025-11-20が必須でした。

当時の名残で、ベータヘッダーを前提にしたクライアントとの組み合わせでつまずいた報告があります。Claude Code 2.0.42でclaude -pがtools.3.custom.input_examples: Extra inputs are not permittedという400エラーで止まったというGitHubのissueです。コメントでは、プロキシがanthropic-betaヘッダーを落としているのが原因だという指摘が並びました。ゲートウェイ側でヘッダーを素通しにする対処です。ゲートウェイ越しにこの400が出たら、まずヘッダーの転送を疑う手があります。

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

精度に最も効くのは詳細なdescriptionで、input_examplesはその補完です。ツールが何をするか、どんな場面で使うか、各パラメータが何を意味するかを3〜4文以上で書くよう、公式ドキュメントは求めています。ツール設計そのものの原則(命名・粒度・レスポンス設計)はエージェント向けツール設計の原則にまとめてあります。この設計が固まってからinput_examplesを足すのが筋です。

右側の3項目は、Anthropicのエンジニアリングブログが効果の小さい場面として挙げた内容の言い換えです。公式ドキュメントの良い例と悪い例の差は、株価取得ツールで示されています。悪い例は説明がGets the stock price for a ticker.の1文だけで、tickerに説明もありません。良い例は返す内容、使う場面、tickerの意味、返さない情報まで書いてあります。例を足すのは、ここまでdescriptionを詰めてもなお型や書式の取り違えが残るときです。

良い例の組み方 — 例ごとに役割を持たせる

例をただ並べても効果は薄くなります。get_weatherの3つの例を見返すと、1つ目は必須と省略可能の両方を埋めた基本形、2つ目は別の値、3つ目は省略可能パラメータを欠いた形です。ブログの勧めは4点です。現実的な値を使う("string"や"value"のような仮の値は避ける)。最小・一部指定・全指定で変化をつける。ツールあたり1〜5個に収める。スキーマだけでは使い方が分からない箇所に絞る。

「1〜5個」はブログが示した目安です。APIリファレンスやツール定義のページには個数の上限が書かれていないので、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を含むフル形です。

トークンコストの目安と、効果の数字

input_examplesは入力トークンを消費します。ツール定義のページが示す目安と、ブログが内部テストとして報告した精度の変化を並べます。

複雑な例を5個渡すと、単純計算で500〜1,000トークンになります。10個のツールにそれぞれ複雑な例を2〜3個添えると、2,000〜6,000トークンが定義側に乗る計算です。ツール定義は毎回のリクエストで送られるため、同じツールセットを何千回も呼ぶバッチ処理や分類パイプラインでは、この固定コストが積み上がります。

プロンプトキャッシングでツール定義をキャッシュ対象にすれば、2回目以降は読み取り単価で済みます。注意したいのは無効化の範囲です。公式の表では、ツール定義を変更するとキャッシュ全体(ツール・システム・メッセージ)が無効になります。例を足したり直したりするたびに、キャッシュは作り直しです。一方、tool_choiceの変更で無効になるのはメッセージ部分だけで、ツール定義とシステムプロンプトのキャッシュは残ります。

効果が出なかった実例 — 自分のツールで測ってから足す

72%から90%への改善は、記述が弱い状態を基準にした報告です。すでにdescriptionを整えたツールでは同じ伸びは出ないことがあります。MCPサーバーのGitHubリポジトリに、その実測が公開されています。

intervals-icu-mcpのissueによると、複雑な5つのツールにinput_examplesを足して、35ケースのスモーク評価を回した結果です。mainが28点、descriptionを削ったブランチが30点、その上でinput_examplesを足したブランチが29点でした。改善した例は0件、悪化した例が1件で、この変更はv3.0.0への採用が見送られています。

issueの書き手は、この結果をAnthropicの数字への反証とは見ていません。理由は4つです。ベースラインがすでに80%を超えていた。失敗の中心が引数の組み立てではなく、「そもそもツールを呼ばない」判断だった。実行が1回きりだった。使ったモデルがHaiku 4.5で、Anthropicの測定とは位置が違うかもしれない。input_examplesが効くのは引数の形を間違える失敗で、ツールを選ぶ判断の失敗には届きません。足す前に、自分の失敗がどちらの型かを評価ケースで確かめるのが安全です。

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

input_examplesが対応するのは、ユーザーが定義したクライアントツールと、Anthropicのスキーマを持つクライアントツールのうち、次の2種類を除いたものです。

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

ツールセットのエントリにinput_examplesかstrict: trueを付けると、APIはinvalid_request_errorで拒否します。混在構成でクライアントツールとサーバーツールを同じリクエストに入れる場合も、input_examplesを書けるのはクライアントツールのエントリだけです。

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

トラブルシューティングガイドは、input_examplesを単独の機能ではなく、他の対処法と並ぶ選択肢として扱っています。

型の取り違えにはstrict: trueという別の手があります。strict: trueは、トークンのサンプリングをスキーマに合う出力へ制約する仕組みで、passengers: 2が"two"や"2"で返る事態をなくします。input_examplesは例を見せるだけなので、守られる保証まではありません。スキーマがstrictの対応範囲(JSON Schemaのサブセット)に収まるならstrict: true、収まらない複雑なスキーマではinput_examplesが実質的な代替になります。strictの仕組みと制約はstrict tool useの解説にまとめています。

「意図したツールを呼ばない」症状には、もう1つ事情があります。Claude Opus 5.5、Sonnet 5.5、Fable 5.1、Mythos 5.1では、tool_choiceにanyかtoolを指定すると400エラーになり、ツールの強制呼び出しができません。manual extended thinking(thinking: enabled)を使うときも、anyとtoolはエラーになります。代わりにautoのまま、descriptionやinput_examples、strictで呼び出しの質を上げる方向になります。

Advanced Tool Useは、Tool Search Tool・Programmatic Tool Callingとこのinput_examplesを合わせて扱った記事です。ブログの使い分けは次のとおりです。ツール発見の問題にはTool Search、中間結果が文脈を圧迫するならProgrammatic Tool Calling、パラメータの誤りにはTool Use Examplesを当てます。

まとめ

input_examplesはdescriptionを詰め切ったあと、ネストや書式依存の型取り違えが残るツールにだけ足す補助です。ツールごとに数十〜数百トークンが毎回乗り、定義を直すたびにキャッシュも作り直しになるので、足す前後で自分の評価ケースの結果を比べると判断を誤りにくくなります。