ツール使用のトラブルシューティング - Claude API Docs

最も一般的なツール使用エラーの症状から解決策への表。各修正は、その機能を所有するページへの相互参照があります。

Claudeが間違ったツールを呼び出す

症状	考えられる原因	修正
Claudeが希望するツールBではなくツールAを呼び出す	説明の曖昧性	説明を明確にします。ツールが「何をするか」だけでなく「いつ使うか」で区別します。ツールの定義を参照してください。
Claudeがツールを呼び出さない	ツール名の衝突またはスキーマが一般的すぎる	ツールリスト全体で重複する名前がないか確認します。`input_examples`を追加して、意図された使用方法を具体的にします。
Claudeが間違ったパラメータ型で呼び出す	曖昧なスキーマでのモデルの推測	`strict: true`を追加します（スキーマがサポートされているサブセットにある場合）、または`input_examples`を追加します。

Claudeがツールパラメータを作成する

症状	考えられる原因	修正
スキーマに存在しないパラメータ	ストリクトモードなしでのモデルの過度な生成	スキーマがサポートされているサブセットにある場合は`strict: true`を追加します。
列挙型の外側のパラメータ値	ストリクトモードの欠落または列挙型が大きすぎる	列挙型を縮小するか、有効な選択肢を示す`input_examples`を追加します。

並列ツール呼び出しが機能しない

症状	考えられる原因	修正
Claudeが並列の方が良い場合に順序立ててツールを呼び出す	メッセージ履歴のフォーマット	複数の`tool_result`ブロックを1つのユーザーメッセージで送信します。ターンごとに1つではなく。並列ツール使用を参照してください。
`disable_parallel_tool_use`が無視されているように見える	会話の後半で設定されている	`tool_use`を返すリクエストで設定する必要があります。後のリクエストで設定すると、以前のツール呼び出しには影響がありません。

キャッシュが無効化され続ける

症状	考えられる原因	修正
すべてのリクエストがキャッシュミス	リクエスト間で`tool_choice`が変動する	`tool_choice`を安定させるか、`cache_control`ブレークポイントを変動ポイントの前に配置します。プロンプトキャッシング付きツール使用を参照してください。
会話の途中でツールを追加するとキャッシュが破損する	ツールがツール配列の先頭に追加される	`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`ブロックをテキストの前に配置します。ツール呼び出しの処理と並列ツール使用を参照してください。
`Input schema is not compatible with strict mode: string patterns are not supported`	`strict: true`で`pattern`を使用している	パターンを削除するか、`strict: true`を削除します。`pattern`キーワードはまだサポートされているJSON Schemaサブセットに含まれていません。

JSONエスケープの違い（Opus 4.6以降）

症状	原因	修正
ツール入力での文字列比較が新しいモデルで失敗する	モデルバージョン間でUnicodeとフォワードスラッシュのエスケープが異なる	`json.loads()`または`JSON.parse()`で解析します。シリアル化された入力での生の文字列マッチングは決して行わないでください。

次のステップ

ツールの定義

Claudeを正しいツールに導くスキーマと説明を作成します。

ツール呼び出しの処理

ツールを実行し、必要なメッセージ形式で結果を返します。

ツールリファレンス

Anthropicスキーマツールとそのバージョン文字列の完全なディレクトリ。