Claude tool useで必須パラメータを省略するとどうなるか — OpusとSonnetの違い

Claude tool useで必須パラメータが省略されるとどう動くか

Claudeのtool useとは、Claudeに外部の関数やAPIを呼び出させ、その結果を会話に組み込ませる仕組みです。呼び出すツールはinput_schemaでパラメータの型とrequired(必須)配列を定義し、Claudeはその定義に沿って呼び出しを組み立てます。ですが、ユーザーの発言だけでは必須パラメータが埋まらないことがあります。このときOpusとSonnetでは挙動が変わります。Tool useのリファレンスがモデル名を挙げてこの差を扱っています。Opusは欠落に気づいて聞き返しやすく、Sonnetは推測で値を埋めがちです。この差は賢さの優劣ではなく、確認してから進むか、埋めてから進むかという既定の姿勢の違いです。

対象になるのは、ツール定義のrequired配列に入れたパラメータが、ユーザーの発言だけでは埋まらないケースです。

get_weatherツールで見る実際の違い

具体例で見ます。locationを必須パラメータに持つget_weatherツールに対し、場所を指定せず「天気は?」とだけ聞いたとします。

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

先ほどのリファレンスに載っている実例そのものです。Sonnetは、ユーザーが一度も口にしていない「New York, NY」をlocationに入れ、呼び出しを完成させます。存在しない情報を捏造しているわけではありません。もっともらしい値で埋めて処理を先に進める、という既定の振る舞いです。

Opusでは同じ状況でもパラメータ不足に気づき、場所を聞き返す確率が高くなります。ただしリファレンスは「ツール要求を出す前に考えるよう促されていれば、Sonnetも聞き返すことがある」とも述べています。差は固定ではありません。プロンプトの作り方で動く程度のものです。この挙動自体も「保証されたものではなく、曖昧なプロンプトや能力の低いモデルほど起きやすい」とリファレンスは留保しています。

実装上の見分け方も押さえておきます。Opusが聞き返すときの応答はtool_useブロックを含まないテキストで返り、stop_reasonはend_turnになります。ツール呼び出しのループ(stop_reasonがtool_useである間ツールを実行してターンを返す仕組み)には入りません。呼び出し側のコードは、レスポンスにtool_useブロックが無ければ質問として扱い、そのままユーザーへ転送する分岐を用意しておく必要があります。

Sonnetの厳密な指示追従と矛盾しないのか

Sonnet 5のプロンプト設計ガイドは、別の顔も示します。「指示を文字通り厳密に解釈し、頼んでいないことを勝手に推測しない」という説明です。一見、ツール呼び出しで値を推測する挙動と食い違って見えます。

矛盾ではありません。指しているレイヤーが違うからです。指示追従の厳密さは、タスクの範囲や適用対象について「頼まれていないことをしない」という話です。一方の値の推測は、必須パラメータという形式的な制約を満たすために、スキーマの型に合う値を1つ作る話です。前者はタスクの外に出ないための厳密さ、後者はスキーマの内側を埋めるための補完で、比べる対象がそもそも違います。

実務向けに言い直すと次のようになります。Sonnetに「指示の範囲を広げるな」という制御は効きます。ですが「必須パラメータが空なら止まれ」という制御は、指示範囲の話とは別に明示しないと効きません。

strict: trueを付けても推測は止まらない

必須パラメータの欠落対策としてstrict: trueを思い浮かべる人もいます。効果は限定的です。

strict tool useが保証するのは、Claudeが返す値がJSON Schemaの型・列挙値・必須フィールドの有無に準拠していることだけです。ツール定義にrequired: ["location"]とstrict: trueを両方指定すれば、locationフィールドが必ず存在する応答は保証されます。ですが、その値が実在の地名かどうか、ユーザーの意図と合っているかまでは検証しません。文字列として妥当なら、"New York, NY"という推測値もスキーマ準拠として通ります。

保証の範囲と、保証しない範囲の詳しい仕様はClaudeのstrict tool useが保証すること・しないことにまとめています。ここで押さえておきたいのは、スキーマ準拠と値の正しさは別物という一点です。

混同しやすい隣接問題もあります。トラブルシューティングの早見表では、strict: trueとinput_examplesを「あいまいなスキーマに対してモデルが型を推測してしまう」問題への対策として挙げています。数値を期待するpassengersに文字列の"two"が入る、といったケースです。これは値そのものが宙に浮いている今回の問題とは別物です。パラメータに何らかの値は入っているものの、型や形式が合っていない、という状況を指します。型のズレには効く対策が、値そのものの欠落には効かない、という切り分けを混同しないようにします。

呼び出し後にis_error: trueで返すとどうなるか

必須パラメータの欠落には、もう一つの現れ方があります。値を推測で埋めるのではなく、フィールドそのものがinputから丸ごと抜け落ちるケースです。この場合は、呼び出し前の指示よりも、呼び出し後の検証が効きます。

自分のツール実行コードで必須フィールドの有無を確かめ、欠けていればtool_resultをis_error: trueにして返します。エラーメッセージは具体的に書きます。

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "content": "Error: Missing required 'location' parameter",
  "is_error": true
}

この形でエラーを返すと、Claudeは欠けていた情報を埋めて再試行します。ツール呼び出しが無効だったり必須パラメータが欠けていたりする場合、Claudeは2〜3回まで訂正を試みます。それでも直らなければ、ユーザーに謝って終えるという上限があります。無限にリトライし続けることはありません。

この仕組みとstrict: trueは役割が重なりません。strict: trueはフィールドの欠落そのものを未然に防ぎます。is_errorによるやり直しは、欠落や型の不一致が実際に起きた後の回復手段です。両方を組み合わせれば、欠落を防ぎつつ、すり抜けたケースも会話の中で回収できます。開発中にこうした無効な呼び出しを見つけたときは、まずdescriptionの書き込みを詳しくします。

推測を防ぐ効き目を早見表で見る

必須パラメータの推測を防ぐ手段は、効くタイミングが手前・最中・後の3つに分かれます。

もっとも効くのはツール呼び出し前に考えさせる指示です。descriptionに確認を明記するのは、この『前に考えさせる』を実装する最も手軽な手段です。

description全体の書き込み量も効きます。「ツール性能に最も影響する要素」は詳細な説明文で、1ツールにつき最低3〜4文を目安とします。何をするか・いつ使う場面か(使わない場面か)・各パラメータが呼び出しにどう影響するかを書き込めば、確認を促す一文もその流れの中に自然に収まります。

ただしtool_choiceをanyやtoolで強制していると、この対策は効きません。APIがアシスタントメッセージを事前に埋めてツール呼び出しを強制するため、確認を促す自然文を挟む余地自体が無くなります。この場合はtool_choiceをautoに戻すか、確認そのものを専用のツールとして設計する必要があります。コピーして使える形は次のとおりです。

{
  "name": "get_weather",
  "description": "指定した地域の天気を取得する。locationが指定されていない場合はツールを呼ばず、先にユーザーに場所を尋ねること。",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  }
}

一方のinput_examplesは、ネストしたオブジェクトやフォーマット依存のパラメータで型の取り違えを防ぐための機能です。必須パラメータの欠落そのものには向きません。使い分けはClaudeのinput_examplesでツール呼び出し精度を上げる使い方で扱っています。説明文や例をツール定義に足すたびにプロンプトトークンが増える点も忘れないようにします。

デフォルト値をツール側に仕込むと何が起きるか

もう一つの対策として、unitのような非必須パラメータにツール側で既定値を持たせるやり方があります。呼び出しは安定します。ただし副作用もあります。

Claudeがこの既定値を「ユーザーが指定した値」であるかのように扱ったまま会話を進めると、確認する機会そのものが消えます。unitが省略されたときに常に華氏で答える実装は、摂氏を期待する読者に気づかれないまま誤った単位で答え続けることになります。既定値は呼び出しを通すためのものであって、意図を確認したことにはなりません。この2つを混同した設計は、後からバグ報告として返ってきます。

よくある質問

Haikuでも同じように推測しますか

リファレンスが名指ししているのはOpusとSonnetだけです。Haikuについての明言はありません。ただし「曖昧なプロンプトや能力の低いモデルほど起きやすい」という留保がある以上、Haikuで推測が起きない保証もありません。モデルを問わず、確認を促す一文をdescriptionに入れておくのが安全な設計です。

extended thinkingを有効にすれば防げますか

直接そう明言されているわけではありません。ただしリファレンスは「ツール要求を出す前に考えるよう促されていれば、Sonnetも聞き返すことがある」としています。extended thinkingはツール呼び出しの前に考える一手間を強制する機能なので、方向としては同じ効果が期待できます。過信はできず、description側の確認指示と併用するのが現実的です。

まとめ

Claudeのtool useで必須パラメータが埋まらないとき、Opusは聞き返しやすく、Sonnetは推測しがちです。ドキュメントに明記された差ですが、固定された仕様ではありません。ツール呼び出し前に考えさせる指示をdescriptionに添えれば、Sonnetでも聞き返す方向に動きます。strict: trueやinput_examplesは型と形式を守るための機能で、欠落した情報を埋める手段ではありません。ツール定義に確認の一文を足すことが、効果が確認されている数少ない対策です。Messages API全体の仕組みはAnthropic API完全ガイドで押さえられます。