Claudeのtool_choiceの使い方とauto/any/tool/noneの違い

tool_choiceの4種類 — 挙動早見表

Claude APIのtool_choiceパラメータは、Claudeがツールを呼ぶかどうか、どのツールを呼ぶかを制御します。取れる値は4種類だけです。toolsパラメータと組み合わせて初めて意味を持つ設定で、どの値を選ぶかによって、応答の形そのものが変わります。

4値のうち、実装で最初に迷うのはたいていautoとanyの境界です。「ツールを使うかもしれないし使わないかもしれない」ならauto、「必ず何かしらツールを使わせたい」ならanyという判断基準で切り分けると、設計段階の迷いを減らせます。

指定方法は単純です。autoは{"type": "auto"}、anyは{"type": "any"}、toolは{"type": "tool", "name": "get_weather"}のようにtypeと(toolのときだけ)nameを渡します。

toolはもっとも強い指定です。会話の文脈に関わらず、指定したツールを必ず呼びます。ユーザーの質問がそのツールと無関係でも、Claudeは入力値を埋めて呼び出そうとするため、フォーム入力の抽出のように「この処理では常に同じツールを使う」と分かっている場面に向きます。逆に、複数の候補から適切な1つを選ばせたいルーティング処理では、toolではなくanyを使うのが定石です。anyは「どれかは必ず呼ぶ」ことだけを強制し、どのツールを選ぶかの判断はClaudeに委ねます。

anyとtoolを指定すると説明文が消える理由

tool_choiceがanyまたはtoolのとき、APIはassistantメッセージをプリフィル(先読み確定)してツール呼び出しを強制します。この結果、Claudeはtool_useブロックの前に自然文のコメントを一切出さなくなります。ユーザーが明示的に説明を求めても同じです。

auto(既定値)のときは違います。Claudeは「San Franciscoの天気を確認します」のような一言を添えてからtool_useブロックを出す挙動が一般的です。この差はツール呼び出しの精度そのものを下げないとAnthropicの検証では確認されています。

会話的な説明を保ちつつツール呼び出しを事実上強制したい場合は、tool_choiceをautoのままにして、ユーザーメッセージ側に明示的な指示を加えます。「サンフランシスコの天気は?get_weatherツールを使って回答してください」のように書けば、autoのまま説明文を残せます。

autoのレスポンスに含まれるtextブロックの扱い

autoのとき、Claudeが一言添えてからtool_useブロックを出すと、レスポンスのcontent配列は次のような形になります。「サンフランシスコの天気と現地時刻を教えて」というプロンプトに対する例です。

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "サンフランシスコの現在の天気と時刻を確認します。" },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

textブロックの言い回しはリクエストごとに変わり得るので、アプリケーション側は特定の文言に依存せず、他のアシスタント生成テキストと同じように扱う必要があります。

4値の実務での使い分け

この表は「向く場面」と「避けたほうがよい場面」を対で示していますが、実装時に効くのは後者の列です。autoを厳密なワークフローに使うと、Claudeがツールを呼ばずに終わってしまうケースを想定しないといけなくなり、anyを対話型UIに使うと、ユーザーに見せたかった説明文が消えて画面が唐突になります。迷ったら「自分のアプリが困るのは表のどちらの列か」で考えると、選ぶべき値が絞れます。

4種類の実装例

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 '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_weather",
      "description": "指定した場所の現在の天気を取得する",
      "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"]
      }
    }],
    "tool_choice": {"type": "tool", "name": "get_weather"},
    "messages": [{"role": "user", "content": "サンフランシスコの天気は?"}]
  }'

tool_choiceの行だけを{"type": "auto"}・{"type": "any"}・{"type": "none"}に差し替えれば、同じリクエストで4種類の挙動を比較できます。手元で試すときは、まずautoでレスポンスのcontent配列を確認し、そこからany・toolに切り替えてtextブロックが消える様子を見ると、挙動の違いを体感しやすくなります。

noneでツール定義を残したまま呼び出しだけ止める

noneはtoolsを渡さなかったときの既定値ですが、toolsを渡した状態で明示的にtool_choice: {"type": "none"}を指定することもできます。この使い方をすると、ツール定義自体はリクエストに含まれたままツール呼び出しだけを止められます。

デバッグ時に「このターンだけツールを使わせずに応答を確認したい」という場面や、ツール定義をプロンプトキャッシュのプレフィックスに残したまま一部のターンだけ通常応答に切り替えたい場面で使えます。ツール定義を配列ごと削除する実装より、tool_choiceの値だけを切り替える実装のほうがシンプルです。

tool_useかどうかはstop_reasonで判定する

tool_choiceの値に関わらず、Claudeがツールを呼んだレスポンスはstop_reason: "tool_use"を返し、content配列に1つ以上のtool_useブロックが含まれます。アプリケーション側でツール呼び出しを検出するときは、特定のtool_choice値を前提にするのではなく、このstop_reasonを見るのが安全です。

autoのときは、ツールを呼ばず直接応答すればstop_reasonが"end_turn"になることもあります。しかしanyやtoolのときは常にtool_useで終わります。ツールを実行した結果は、新しいtool_resultブロックを含むユーザーメッセージとして送り返し、会話を続けます。このときtools配列とtool_choiceは前のリクエストと同じ値を保つのが基本です。tool_choiceだけ値を変えると、後述のとおりメッセージ側のキャッシュが無効になります。

モデル別の対応状況 — Fable 5.1とMythos 5.1は強制呼び出し非対応

すべてのモデル・設定でanyとtoolが使えるわけではありません。使えない組み合わせではautoとnoneだけが動作し、anyとtoolはエラーになります。

Fable 5.1・Mythos 5.1へtool_choice: {"type": "any"}や{"type": "tool", "name": "..."}を送ると、公式ドキュメントに明記された次のエラーメッセージが返ります。

tool_choice: type "tool" and "any" are not supported for this model.

このエラーはトークンカウントのエンドポイントでも同様に返ります。auto(既定値)とnoneは引き続き使えるため、これらのモデルでツール入力の型を保証したい場合は、strict: trueを付けたツール定義でautoを使うか、固定のJSON形状で結果だけが欲しいなら構造化出力に切り替えます。プロンプト側の指示はautoでもどのツールが選ばれるかに影響し続けます。

なぜ拡張思考とany/toolは両立しないか

手動の拡張思考(thinking: {"type": "enabled"})でanyやtoolが使えないのは、単なる仕様上の制限ではなく構造的な理由があります。拡張思考が有効な間、assistantの応答をプリフィルすることはできません。しかしanyとtoolは、いずれもツール呼び出しを強制するためにassistantメッセージをプリフィルする仕組みです。この2つは原理的に両立しません。

一方、適応的思考(Opus 5を含む多くの現行モデルで既定)は同じ制約を受けず、強制ツール呼び出しと組み合わせられます。例外はClaude Fable 5.1とClaude Mythos 5.1で、この2モデルは適応的思考の有無に関わらず、あらゆるリクエストで強制ツール呼び出しそのものを拒否します。

auto + strict tool useが埋める隙間

強制呼び出しが使えないモデル・場面で「ツール入力の型だけは保証したい」というニーズに応えるのがstrict: trueです。ツール定義にstrict: trueを付けると、Claudeの出力トークンのサンプリング自体をJSON Schemaに適合する範囲へ制約します。grammar-constrained samplingと呼ばれる技術で、tool_choiceとは独立したプロパティです。anyやtoolと組み合わせなくても、autoのままツール入力の型を保証できます。

例えば予約システムでpassengers: intを受け取るツールを定義したとき、strictを付けなければClaudeが"2"のような文字列や"two"のような曖昧な値を返すことがあります。strict: trueを付ければ、返る値は常に整数の2になります。auto(またはnone)しか使えないFable 5.1・Mythos 5.1のようなモデルでも、strict: trueを組み合わせれば、呼び出し自体は強制できなくても、呼ばれたときの入力値の型安全性は確保できます。なお、強制ツール呼び出しに対応しているモデルであれば、tool_choice: {"type": "any"}とstrict tool useを組み合わせるのが第一候補です。ツールのどれかが必ず呼ばれることと、入力がスキーマに厳密に従うことの両方を同時に保証できます。

disable_parallel_tool_useはtool_choiceの中に入れる

並列ツール呼び出しは既定で有効です。1回の応答で複数のtool_useブロックを同時に返せます。これを無効化するdisable_parallel_tool_use: trueは、独立したトップレベルパラメータではなく、tool_choiceオブジェクトの中に入れるフィールドです。

効果はtool_choiceのtypeによって変わります。

指定方法はシンプルで、tool_choiceオブジェクトにフィールドを1つ足すだけです。

"tool_choice": {"type": "auto", "disable_parallel_tool_use": true}

anyやtoolと組み合わせる場合も書き方は同じですが、Fable 5.1・Mythos 5.1ではそもそもany/tool自体が使えないため、この組み合わせは選べません。並列呼び出しを禁止しつつ何を呼ぶかはClaudeに委ねたいならauto側、常に1つだけ確実に呼ばせたいならany/tool側、という使い分けになります。

プロンプトキャッシュへの影響

tool_choiceの値を変更すると、キャッシュ済みのメッセージブロックは無効になります。ツール定義自体とシステムプロンプトのキャッシュは保持されますが、メッセージ本文は再処理の対象になります。デバッグ中にtool_choiceをリクエストごとに切り替える運用では、この再処理コストを見込んでおく必要があります。プロンプトキャッシュの基本的な仕組みはPrompt Cachingを理解するで扱っています。

まとめ

tool_choiceという1つのパラメータの中には、応答形式(自然文の有無)・モデルごとの対応可否・並列呼び出しの制御・プロンプトキャッシュへの影響という、性質の異なる論点がいくつも同居しています。autoのまま何も設定しない選択も含めて、実装するアプリケーションの要件に合わせて意識的に選ぶ価値があります。

tool_choiceの既定値はtoolsの有無でautoとnoneが自動的に切り替わります。ツールを確実に呼ばせたいならanyかtoolですが、この2つを指定した瞬間にassistantメッセージがプリフィルされ、自然文の説明は消えます。説明を残したまま呼び出しを促したいなら、autoのままユーザーメッセージで指示するのが公式の書き方です。Fable 5.1・Mythos 5.1のようにany/tool自体が使えないモデルもあるため、Anthropic API完全ガイドでモデル選定と合わせて確認しておくと実装時のエラーを避けられます。