ツール使用のトラブルシューティング
症状から修正方法を導く診断表を使って、最も一般的なツール使用のエラーを修正します。
表示されている症状またはエラーを見つけ、それに対して記載されている修正方法を適用してください。
Claudeが間違ったツールを呼び出す
| 症状 | 考えられる原因 | 修正方法 |
|---|---|---|
| ツールBを使ってほしいのにClaudeがツールAを呼び出す | 説明の曖昧さ | 説明を明確にします。ツールが「何をするか」だけでなく、「いつ使うか」によってツールを区別します。ツールの定義を参照してください。 |
| Claudeがツールをまったく呼び出さない | ツール名の衝突、またはスキーマが汎用的すぎる | ツールリスト全体で名前が重複していないか確認します。input_examplesを追加して、意図した使い方を具体的にします。 |
| Claudeが間違ったパラメータ型で呼び出す | スキーマがあいまい | strict: trueを追加する(スキーマがサポートされているサブセットに含まれる場合)か、input_examplesを追加します。 |
Claudeがツールパラメータを捏造する
| 症状 | 考えられる原因 | 修正方法 |
|---|---|---|
| スキーマに存在しないパラメータ | strictモードなしでのモデルの過剰生成 | スキーマがサポート対象のサブセットに含まれる場合は strict: true を追加します。 |
| enumの範囲外のパラメータ値 | strictモードの欠如、または大きすぎるenum | enumを縮小するか、有効な選択肢を示す input_examples を追加します。 |
並列ツール呼び出しが機能しない
| 症状 | 考えられる原因 | 修正方法 |
|---|---|---|
| 並列のほうが適切な場面でClaudeがツールを順次呼び出す | メッセージ履歴のフォーマット | 複数の tool_result ブロックを、ターンごとに1つずつではなく、1つのユーザーメッセージにまとめて送信します。並列ツール使用を参照してください。 |
disable_parallel_tool_useが無視されているように見える | 会話内で設定するのが遅すぎる | tool_useを返すリクエストで設定します。後のリクエストで設定しても、それ以前のツール呼び出しには影響しません。 |
キャッシュが無効化され続ける
| 症状 | 考えられる原因 | 修正方法 |
|---|---|---|
| すべてのリクエストがキャッシュミスになる | tool_choice、思考の設定、または output_config.effort がリクエスト間で変化している | tool_choice を一定に保つか、cache_control のブレークポイントを変化点より前に配置します。キャッシュされた会話の存続期間中は、思考の設定とeffortレベルを一定に保ちます。プロンプトキャッシングを伴うツール使用および思考とプロンプトキャッシングを参照してください。 |
| 会話の途中でツールを追加するとキャッシュが壊れる | ツールがtools配列の先頭に追加されている | 後から配列に追加する代わりに、最初のリクエストから defer_loading: true を指定してツールを宣言し、ツール検索にインラインでロードさせます。 |
リクエスト時のエラー
エラー列には各メッセージの一部が表示されており、... は内容が変わるテキストを表します。
| エラー | 原因 | 修正方法 |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | 一部のtool_use IDに対するtool_resultが欠落している、またはtool_resultがユーザーメッセージ内の最初のコンテンツブロックになっていない | アシスタントの応答内のすべてのtool_useブロックに対して、tool_resultを1つずつ返します。tool_resultブロックはテキストより前に配置します。ツール呼び出しを処理するおよび並列ツール使用を参照してください。 |
was found without a corresponding ... block | フォローアップリクエストによって、待機中のサーバーツールの実行が妨げられている | サーバーツール呼び出しに結果ブロックがないを参照してください。 |
Unsupported regex feature in pattern field: ... | strictツールの pattern が、後方参照、単語境界、大きな {n,m} 範囲など、strictモードでコンパイルできない正規表現機能を使用している | パターンを簡素化します。JSON Schemaの制限を参照してください。 |
Invalid regex in pattern field: ... | strictツールの pattern に先読み、後読み、または構文エラーが含まれている | 先読みや後読みを削除し、構文エラーを修正します。JSON Schemaの制限を参照してください。 |
All tools have defer_loading: true | モデルから見えるツールがない | 少なくとも1つのツールは即時ロードされる必要があります。ツール検索ツール自体には決して defer_loading: true を設定してはいけません。 |
サーバーツール呼び出しに結果ブロックがない
サーバーツールは、そのserver_tool_useまたはmcp_tool_useブロックに結果ブロックがない場合、まだ実行を待機している状態です。エラーwas found without a corresponding ... blockは、フォローアップリクエストによって待機中のツールの実行が妨げられていることを意味します。その理由はエラーメッセージと直前のstop_reasonからわかります。最初に該当するケースを適用してください。
- メッセージが
but no `<name>` tool was providedまたはis not available after the last messageで終わる場合: ここで、<name>はweb_searchなどのツール名です。リクエストでそのツールが定義されなくなっています。以前と同じtools配列を送信し、MCPツールの場合は同じmcp_serversも送信します。 - 直前の
stop_reasonがtool_useだった場合: ユーザーメッセージのtool_resultブロックの後にコンテンツがありました。クライアントのtool_useブロックごとに1つずつ、tool_resultブロックのみを送信します。 - 直前の
stop_reasonがpause_turnだった場合: ユーザーメッセージを追加しています。それを削除し、リクエストが一時停止されたレスポンスを含むassistantメッセージで終わるようにします。
詳しい手順については、サーバーツールがまだ待機している場合およびpause_turn停止理由を参照してください。
エラー: 思考ブロックは変更できません
ツール呼び出し後に会話を継続する際、リクエストが400 invalid_request_error で失敗し、そのメッセージに `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified が含まれている場合、アプリケーションがアシスタントの思考ブロックを送り返す前に変更しています。アシスタントメッセージ全体を変更せずにそのまま送り返し、その後に tool_result を追加してください。
完全なエラーと修正手順については、思考ブロックは変更できませんを参照してください。
Claudeがツール結果をプロンプトインジェクションとしてフラグ付けする
| 症状 | 考えられる原因 | 修正方法 |
|---|---|---|
| Claudeがツール結果に基づく行動を拒否する、またはツール結果に含まれていた指示についてユーザーに確認を求める | 独自の指示が tool_result のコンテンツ内で渡されている | Claudeは、ツール結果内の指示を信頼できない可能性のあるサードパーティコンテンツとして扱うよう訓練されています。指示をツール結果の外に移動してください。tool_result ブロックの後の user ターンで送信するか、サポート対象のモデルでは会話途中のシステムメッセージで送信します。ツール結果にはデータのみを含めるようにします。ジェイルブレイクとプロンプトインジェクションの軽減を参照してください。 |
モデルバージョン間のJSONエスケープの違い
| 症状 | 原因 | 修正方法 |
|---|---|---|
| 新しいモデルでツール入力の文字列比較が失敗する | Unicodeおよびスラッシュのエスケープがモデルバージョン間で異なる | json.loads() または JSON.parse() でパースします。シリアライズされた入力に対して生の文字列マッチングを行わないでください。 |
次のステップ
Claudeを適切なツールへ導くスキーマと説明を記述します。
ツールを実行し、必要なメッセージ形式で結果を返します。
Anthropic提供のツールとそのバージョン文字列の完全な一覧です。
このページは役に立ちましたか?