Messagesツール
ツール使用のトラブルシューティング
症状から修正方法を導く診断表を使って、最も一般的なツール使用のエラーを修正します。
最も一般的な「tool use」（ツール使用）のエラーに対する、症状から修正方法を導く表です。各修正方法は、その機能を扱うページを相互参照しています。
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 ブロックに対して1つずつ tool_result を返します。tool_result ブロックはテキストより前に配置します。ツール呼び出しの処理および並列ツール使用を参照してください。 |
was found without a corresponding <name>_tool_result block | 直前のアシスタントターンに、結果ブロックのない server_tool_use ブロックがあり（多くの場合、Claudeがクライアントツールと同時にそれを呼び出した）、かつ次のユーザーメッセージがそのターンを終了させた（たとえば tool_result ブロックの後にテキストがある）か、再開リクエストでそのサーバーツールが定義されなくなっている（その場合メッセージは but no <name> tool was provided で終わります） | クライアントの tool_use idに対する tool_result ブロックのみを含むユーザーメッセージを送信し、同じ tools 配列を維持します。停止理由とフォールバックを参照してください。 |
Unsupported regex feature in pattern field: ... | strictツールの input_schema 内の pattern が、後方参照、先読み・後読み、単語境界、大きな {n,m} 範囲など、strictモードでコンパイルできない正規表現機能を使用している | パターンを簡素化します。基本的な量指定子、文字クラス、グループを使ったアンカー付きパターンはサポートされています。JSON Schemaの制限を参照してください。 |
All tools have defer_loading: true | モデルから見えるツールがない | 少なくとも1つのツールは即時ロードされる必要があります。ツール検索ツール自体には決して defer_loading: true を設定してはいけません。 |
エラー: thinkingブロックは変更できません
ツール呼び出し後に会話を継続する際、リクエストが400 invalid_request_error で失敗し、そのメッセージに `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified が含まれている場合、アプリケーションがアシスタントのthinkingブロックを送り返す前に変更しています。アシスタントメッセージ全体を変更せずにそのまま送り返し、その後に tool_result を追加してください。
完全なエラーと修正手順については、thinkingブロックは変更できませんを参照してください。
Claudeがツール結果をプロンプトインジェクションとしてフラグ付けする
| 症状 | 考えられる原因 | 修正方法 |
|---|---|---|
| Claudeがツール結果に基づく行動を拒否する、またはツール結果に含まれていた指示についてユーザーに確認を求める | 独自の指示が tool_result のコンテンツ内で渡されている | Claudeは、ツール結果内の指示を信頼できない可能性のあるサードパーティコンテンツとして扱うよう訓練されています。指示をツール結果の外に移動してください。tool_result ブロックの後の user ターンで送信するか、サポート対象のモデルでは会話途中のシステムメッセージで送信します。ツール結果にはデータのみを含めるようにします。ジェイルブレイクとプロンプトインジェクションの軽減を参照してください。 |
JSONエスケープの違い（Opus 4.6以降）
| 症状 | 原因 | 修正方法 |
|---|---|---|
| 新しいモデルでツール入力の文字列比較が失敗する | Unicodeおよびスラッシュのエスケープがモデルバージョン間で異なる | json.loads() または JSON.parse() でパースします。シリアライズされた入力に対して生の文字列マッチングを行わないでください。 |
次のステップ
Claudeを適切なツールへ導くスキーマと説明を記述します。
ツールを実行し、必要なメッセージ形式で結果を返します。
Anthropic提供のツールとそのバージョン文字列の完全な一覧です。
Was this page helpful?