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

Claude tool useで必須パラメータが埋まらないとき、モデルは何をするか

Claudeのtool useとは、Claudeに外部の関数やAPIを呼び出させ、その結果を会話に組み込ませる仕組みです。呼び出すツールはinput_schemaでパラメータの型とrequired(必須)配列を定義します。ところが、ユーザーの発言だけでは必須パラメータが埋まらないことがあります。

Tool useの概要ページには、この場面を扱う「When required parameters are missing」の項があります。OpusとSonnetの違いは、賢さの優劣ではなく、聞き返してから進むか、埋めてから進むかという既定の姿勢です。

locationを必須にしたget_weatherツールに、場所を言わず「天気は?」とだけ聞いた例が、概要ページに載っています。

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

ユーザーが一度も口にしていない「New York, NY」がlocationに入っています。この推測は、特にSonnetで起きやすい挙動として示されています。

ただし差は固定ではありません。Sonnetも、ツール要求を出す前に考えるよう促されていれば聞き返すことがあります。同じ項には「この挙動は保証されたものではなく、曖昧なプロンプトや能力の低いモデルほど起きやすい」とも書かれています。

聞き返しが来たとき、呼び出し側のコードはどう分岐するか

Opusが聞き返す場合、応答にツール呼び出しは含まれません。ツール呼び出しのループはstop_reasonがtool_useである間だけ回り、それ以外のend_turnなどでは抜けます。この仕組みは「How tool use works」のページにあります。

聞き返しの質問は、ループを抜けたあとの「最終回答」と同じ形で返ってきます。そのため、tool_useブロックが無い応答はそのままユーザーへ転送する分岐を用意しておくと、質問が握りつぶされません。

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

Sonnet 5のプロンプト設計ガイドは、Sonnet 5について「プロンプトを文字通り明示的に解釈し、頼んでいないリクエストを推測しない」と説明しています。値を推測するという話と食い違って見えるかもしれません。

矛盾しないと読めます。指しているレイヤーが違うためです。指示追従の厳密さは、頼まれていない作業までやらないという、タスクの範囲の話です。値の推測は、必須パラメータという形式上の穴を、型に合う値で埋めるという、スキーマの内側の話です。

実務では次のように分けると扱いやすくなります。

• 「指示の範囲を広げるな」は、Sonnetで効きやすい制御と考えられます。
• 「必須パラメータが空なら止まれ」は、範囲の話とは別に、明示しておきたい制御です。

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

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

strict tool useが保証するのは、Claudeが返す値がJSON Schemaの型・列挙値・必須フィールドの有無に準拠していることです。required: ["location"]とstrict: trueを両方指定すれば、locationが必ず存在する応答になります。Handle tool callsのページも、strictが欠落パラメータと型の不一致を防ぐと述べています。ですが、その値が実在の地名か、ユーザーの意図と合っているかは検証しません。文字列として妥当なら、"New York, NY"もスキーマ準拠として通ります。

保証する範囲と、しない範囲の詳しい仕様はClaudeのstrict tool useが保証すること・しないことにまとめています。

隣接する問題とも区別が要ります。トラブルシューティングの早見表は、strict: trueとinput_examplesを、あいまいなスキーマで型を推測してしまう問題への対策として挙げています。たとえば数値の2が文字列の"2"で返る、といった型のズレです。値そのものが宙に浮いている今回の問題とは別物です。

症状別に見る:推測された場合と、フィールドが抜けた場合

必須パラメータの問題は、現れ方で打ち手が変わります。

1. 値が推測で埋まった: スキーマには合っているので、API側のエラーにはなりません。防ぐなら呼び出し前、つまりdescriptionで手を打ちます。
2. フィールドがinputから抜け落ちた: 呼び出し後の検証で拾えます。「Handle tool calls」のページが、この場合の手順を示しています。

この手順は、同ページの「Invalid tool name」の項に載っています。無効な呼び出しの例として、必須パラメータの欠落が挙げられています。返すtool_resultは次の形です。

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

このエラー返却は、開発中に無効な呼び出しを見つけたときの2番目の手段です。1番目は、descriptionをより詳しく書き直してもう一度試すことです。一方でstrict: trueは、欠落や型の不一致を、起きる前に防ぐ手段です。両方を組み合わせれば、防ぎつつ、すり抜けた分も会話の中で回収できます。

どのタイミングの対策が効くか

対策は、効くタイミングが呼び出しの前・最中・後に分かれます。

description全体の書き込み量も効きます。ツール性能に最も影響する要素は詳細な説明で、1ツールにつき最低3〜4文が目安とされています。何をするか、いつ使うか(使わない場面も)、各パラメータが挙動にどう影響するかを書けば、確認を促す一文もその流れに収まります。コピーして使える形は次のとおりです。

{
  "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でツール呼び出し精度を上げる使い方で扱っています。説明文や例を足すたびにプロンプトトークンが増える点にも注意が要ります。

ツール呼び出しを強制するtool_choiceでは、この対策が効かない

tool_choiceをanyやtoolにすると、APIがアシスタントメッセージを事前に埋めて、ツール呼び出しを強制します。このときモデルは、tool_useブロックの前に自然文の説明を出しません。明示的に頼んでも同じです。確認を促す自然文を挟む余地が、そもそも無くなります。

しかも、強制自体が使えないモデルがあります。forced tool useの表では、次の4モデルでanyとtoolが400エラーになります。

• Claude Opus 5.5
• Claude Sonnet 5.5
• Claude Fable 5.1
• Claude Mythos 5.1

代わりに使うのは、autoにstrict tool useを組み合わせる構成です。strictで「スキーマに合う入力」を保証し、確認の一文はdescriptionやプロンプトで効かせます。どのツールを選ぶかも、autoのままプロンプトで影響を与えられます。つまり、強制を使わなくても、確認と選択の誘導は自然文の側に寄せられます。

手動のextended thinking(thinking: {type: "enabled"})でも、anyとtoolはエラーになります。

強制を外せない場合は、確認そのものを専用のツールとして設計するという選択肢もあります。

ツールが当てはまらないときの一文

Opus 5のプロンプト設計ガイドには、thinkingを無効にして使う場合の一文が載っています。「ツールで表現できない依頼なら、推測せずにそう伝える」という趣旨です。

When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing.

この一文は、ツール呼び出しの前に一言話す許可と、内部タグを出さない規則とまとめて挙げられています。必須パラメータの欠落と同じ「推測しない」方向の指示ですが、対象は「ツールが無い」場面です。パラメータが足りない場面は、先のdescriptionの一文で別に押さえます。

ツール側に既定値を持たせると何が起きるか

unitのような非必須パラメータに、ツール側で既定値を持たせるやり方もあります。呼び出しは通りやすくなります。

ただし、Claudeがその既定値を「ユーザーが指定した値」のように扱って会話を進めると、確認の機会が消えることがあります。たとえばunitの既定値を華氏にした実装では、摂氏を期待する読者に気づかれないまま、華氏で答え続ける場合があります。既定値は呼び出しを通すためのもので、意図を確かめたことにはなりません。

よくある質問

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

公式の記述が名指ししているのは、OpusとSonnetです。「能力の低いモデルほど起きやすい」という留保はあるので、モデルを問わず、descriptionに確認の一文を入れる設計が無難です。

まとめ

強制できないモデルがある以上、確認を促す仕組みは最終的にdescriptionの一文に集まります。スキーマが守れるのは形式までで、値が意図に合うかどうかは、聞き返す設計で確かめます。

Messages API全体の仕組みはAnthropic API完全ガイドで押さえられます。