Claude API のツール定義（Define tools）の書き方

Claude API でツールを使うとき、モデルの挙動をいちばん大きく左右するのは description の書き方です。本記事は公式ドキュメント「Define tools」の非公式日本語訳として、ツール定義の各フィールド、input_examples の使いどころ、tool_choice の4つの値の違いを整理します。

ツール定義のフィールド

クライアントツール（Anthropic 定義のスキーマを使うものと、自分で定義するものの両方）は、API リクエストのトップレベルの tools パラメータで指定します。ツール定義は次のフィールドを持ちます。

cache_control・strict・defer_loading・allowed_callers といった任意プロパティの一覧は、公式の Tool reference を参照してください。

モデルの選び方について、公式は次のように書いています。複雑なツールや曖昧なクエリには最新の Claude Opus モデル（Claude Opus 5）を使う。こちらは複数ツールの扱いに優れ、必要なときには確認を求めます。単純なツールなら Claude Haiku 系でもよいが、不足しているパラメータを推測することがある点に注意してください。

説明の書き方（公式のベストプラクティス）

tools パラメータを付けて Claude API を呼ぶと、API はツール定義・ツール設定・ユーザー指定のシステムプロンプトから、専用のシステムプロンプトを組み立てます。ここに、どう書けば効くかの理由があります。

公式が挙げているツール定義のベストプラクティスは次のとおりです。

• 極めて詳細な説明を書く。 これがツールの性能を決める最大の要因です。何をするか、いつ使うべきか（そしていつ使うべきでないか）、各パラメータが何を意味し挙動にどう影響するか、そのツールが返さない情報は何かといった注意点まで書きます。1つのツールにつき最低3〜4文、複雑なら更に多くを目安にしてください。
• 説明を優先しつつ、複雑なツールには input_examples を検討する。 入力が複雑・入れ子・書式に敏感な場合、スキーマ検証つきの例を渡せます。
• 関連する操作は少数のツールにまとめる。 create_pr / review_pr / merge_pr のように操作ごとにツールを分けるのではなく、action パラメータを持つ1つのツールにまとめます。ツールの数が減るほど選択の曖昧さが減ります。
• ツール名に意味のある名前空間を付ける。 複数のサービスにまたがるなら github_list_prs・slack_send_message のようにサービス名を前置します。ツールが増えたときの選択が明確になり、ツール検索を使う場合には特に重要です。
• ツールの応答は情報密度の高いものだけを返す設計にする。 内部の不透明な参照ではなく、slug や UUID のような意味のある安定した識別子を返し、Claude が次の一手を考えるのに必要なフィールドだけを含めます。応答が肥大するとコンテキストを浪費します。

公式は良い説明と悪い説明の対比を挙げています。良い例は「何をするか・いつ使うか・何を返すか・パラメータの意味」を明示しており、悪い例は「Gets the stock price for a ticker.」のように短すぎて、挙動や使いどころについて Claude に多くの疑問を残します。

input_examples と tool_choice

入力例（input_examples）を渡す

ツール定義に任意の input_examples フィールドを追加し、有効な入力例の配列を渡せます。各例はそのツールの input_schema に照らして妥当でなければなりません。不正な例は 400 エラーになります。

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit of temperature"}
    },
    "required": ["location"]
  },
  "input_examples": [
    {"location": "San Francisco, CA", "unit": "fahrenheit"},
    {"location": "Tokyo, Japan", "unit": "celsius"},
    {"location": "New York, NY"}
  ]
}

例はツールのスキーマと並べてプロンプトに含まれ、整った形のツール呼び出しの具体的なパターンを Claude に示します。任意パラメータをいつ含めるか、どの書式を使うか、複雑な入力をどう構成するかの理解を助けます。

制限は3つです。スキーマ検証（不正な例は 400 エラー）、サーバー側ツールでは未対応（Web 検索やコード実行のようなサーバーツールには使えません。ユーザー定義ツールと Anthropic スキーマのクライアントツールで動きます）、トークンコスト（単純な例で約20〜50トークン、複雑な入れ子オブジェクトで約100〜200トークン）。

tool_choice で呼び出しを制御する

Claude が通常なら直接答えてしまう場面でも、特定のツールを使わせたいことがあります。その場合はリクエストの tool_choice フィールドで指定します。値は4つです。

• auto … ツールを呼ぶかどうかを Claude に任せます。tools を渡したときの既定値です。
• any … 渡したツールのいずれかを必ず使わせます。ただし特定のツールは強制しません。
• tool … 特定のツールを常に使わせます。
• none … ツールを一切使わせません。tools を渡さないときの既定値です。

tool_choice が any または tool のとき、API はツールを使わせるために assistant メッセージをプリフィルします。その結果、たとえ明示的に指示しても、tool_use コンテンツブロックの前に自然言語の応答や説明は出力されません。説明も欲しい場合は auto（既定）のままにして、user メッセージ側に「回答では get_weather ツールを使ってください」のように明示的な指示を入れる方法が公式に示されています。

いくつか注意点があります。プロンプトキャッシュを使っている場合、tool_choice の変更はキャッシュ済みのメッセージブロックを無効化します（ツール定義とシステムプロンプトはキャッシュされたままです）。また手動の拡張思考（thinking: {type: "enabled"}）とツール使用を組み合わせる場合、any と tool は非対応でエラーになります。対応するのは auto と none だけです。適応的な思考（Claude Opus 5 のように既定で思考が有効なモデルを含む）では、強制的なツール使用に対応しています。

なお、tool_choice: {"type": "any"} と strict tool use を組み合わせると、いずれかのツールが必ず呼ばれることとツール入力がスキーマに厳密に従うことの両方を保証できます。ツール定義に strict: true を設定するとスキーマ検証が有効になります。

まとめ

要点は4つです。

• ツール定義の性能は description でほぼ決まる。1ツールあたり3〜4文以上を目安に、使うべきでない場面や返さない情報まで書く
• 操作ごとにツールを分けず、action パラメータでまとめる。名前にはサービス名の名前空間を付ける
• 入力が複雑なツールには input_examples を足す。スキーマ検証が効き、トークンコストは単純な例で20〜50程度
• tool_choice の既定値は、tools を渡せば auto、渡さなければ none。any / tool を使うと自然言語の前置きが出なくなる

本記事は Anthropic 公式ドキュメントの「Define tools」を非公式に日本語訳・要約したものです。仕様は更新されるため、実装前に公式ドキュメントで最新の内容をご確認ください。