ai-docs

Define tools

Properties1
tagstools, api, prompting, thinking

原典: Define tools ／ 日本語版

一行要約

Provide extremely detailed descriptions. This is by far the most important factor in tool performance.

極めて詳細な説明を書け。これがツールの性能を左右する、群を抜いて最も重要な要因である。

ツール1つにつき最低3〜4文。複雑なら input_examples を足す。

要点

ツール定義のフィールド

パラメータ内容
name^[a-zA-Z0-9_-]{1,128}$ にマッチすること（以前の取得では {1,64}）
description何をするか、いつ使うか、どう振る舞うかの詳細な平文
input_schemaJSON Schema
input_examples（任意）スキーマ検証される入力例の配列

他の任意プロパティ: cache_control、strict、defer_loading、allowed_callers。computer use と browser use は client toolset（name を持たない1つのエントリが決まったメンバーツール群を宣言する）で、エントリには cache_control と allowed_callers を付けられ、defer_loading はメンバーごとに設定する。

description のベストプラクティス

description に書くべきこと:

  • 何をするか
  • いつ使うべきか（そしていつ使うべきでないか）
  • 各パラメータが何を意味し、挙動にどう影響するか
  • 重要な注意点や制限。特にツール名が曖昧な場合、そのツールが返さない情報

Aim for at least 3–4 sentences for each tool description, more if the tool is complex.

ツールの説明は、それぞれ最低でも3〜4文を目安にせよ。ツールが複雑ならさらに増やす。

その他の原則:

  • 関連する操作を少数のツールに統合する — create_pr / review_pr / merge_pr を別々にせず、action パラメータを持つ1つのツールにする

Fewer, more capable tools reduce selection ambiguity and make your tool surface easier for Claude to navigate.

数が少なく高機能なツールは選択の曖昧さを減らし、Claude がツール群を辿りやすくする。

  • ツール名に意味のある namespace を使う（github_list_prs、slack_send_message）。tool search を使うときは特に重要
  • パラメータには推論ではなく説明を求める —— Claude がなぜその呼び出しをするのかを聞くパラメータなら、短い説明か裏付けとなる証拠を求める。モデルの thinking や段階的な推論を求めるパラメータは reasoning_extraction の拒否を招きうる
  • ツールの応答は高信号の情報だけを返す — 不透明な内部参照ではなく、意味のある安定した識別子（slug や UUID）を返し、Claude が次のステップを推論するのに必要なフィールドだけを含める

良い description と悪い description の差は、「何を返すか」「いつ使うか」「パラメータの意味」を書いているかどうか。

input_examples

複雑なツール（ネストしたオブジェクト、任意パラメータ、形式に敏感な入力）で特に有用。

  • 各例はツールの input_schema に照らして valid でなければならない。無効な例は 400 エラー
  • server tool（web search、code execution など）と client toolset（computer use・browser use）では使えない。使えるのはユーザー定義のツールと、toolset 以外の Anthropic スキーマの client tool
  • トークンコスト: 単純な例で 20〜50 トークン、複雑なネストオブジェクトで 100〜200 トークン

巧いのは「フル装備 → 中間 → 最小」の3段階を見せること — Claude が任意パラメータをいつ含めるべきかを学ぶ。

tool_choice の4択

値挙動
autoClaude が呼ぶかどうかを決める（tools があるときの既定）
anyいずれかのツールを必ず使う（特定はしない）
tool特定のツールを必ず使う
noneツールを使わせない（tools がないときの既定）

重要な副作用:

Note that when you have tool_choice as any or tool, the API prefills the assistant message to force a tool to be used. This means that the models will not emit a natural language response or explanation before tool_use content blocks, even if explicitly asked to do so.

tool_choice を any または tool にすると、API は assistant のメッセージを prefill してツールの使用を強制する。つまりモデルは、明示的にそう頼まれていたとしても、tool_use のコンテンツブロックより前に自然言語の応答や説明を出さない。

自然言語の説明も欲しいなら、tool_choice は auto のままにして、user メッセージで明示的に指示する — What's the weather like in London? Use the get_weather tool in your response.

制約:

強制ツール使用（any / tool）が使えない場合、auto（既定）と none は引き続き使える。

モデル・設定制約代わりに使うもの
manual extended thinking（thinking: {type: "enabled"}）any と tool はエラーauto か none。adaptive thinking そのものは強制ツール使用を妨げない（Opus 5 は thinking オンのまま使える）。次の行のモデルは thinking の設定に関わらず強制ツール使用を拒否する
Opus 5.5 / Sonnet 5.5 / Fable 5.1 / Mythos 5.1any と tool は thinking の設定に関わらず 400auto に strict tool use（ツール入力がスキーマに合うことを保証）か、決まった JSON の形の応答が要るなら structured outputs。auto がどのツールを選ぶかは、それでも prompt で誘導できる

以前の取得にあった「Mythos Preview は強制ツール使用に非対応」は、その後の取得では原典から消えている。

キャッシュへの副作用:

  • tool_choice の変更はキャッシュされたメッセージブロックを無効化する。 ツール定義と system prompt はキャッシュされたまま

strict tool と組み合わせてツール呼び出しを保証する:

On models that support forced tool use, combine tool_choice: {"type": "any"} with strict tool use to guarantee both that one of your tools is called and that the tool inputs strictly follow your schema. Set strict: true on your tool definitions to enable schema validation.

強制ツール使用に対応するモデルでは、tool_choice: {"type": "any"} と strict tool use を組み合わせると、自分のツールのいずれかが必ず呼ばれることと、そのツールの入力がスキーマに厳密に従うことの両方を保証できる。ツール定義に strict: true を設定してスキーマ検証を有効にする。

ツール使用時の system prompt

tools を渡すと、API がツール定義・ツール設定・ユーザーの system prompt から専用の system prompt を組み立てる。

ツールを呼ぶ前の前置きを当てにしない

ツールを使うとき、Claude はツールを呼ぶ前に、何をするかを述べたり自然に応答したりすることが多い。その文体と中身は system prompt と prompt 内の <examples> で誘導できる。ただし言い回しは毎回変わりうる。

Your code should treat these responses like any other assistant-generated text, and not rely on specific formatting conventions.

コードはこれらの応答を他の assistant 生成テキストと同じに扱い、特定の書式の慣習に依存してはならない。

以前の取得にあった「モデル選択」の節（複雑なツールには最新の Opus、単純なツールには Haiku）は、その後の取得では原典から消えている。

そのまま使える具体例

良い description（何を返し、何を返さないかまで書く）:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {"type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."}
    },
    "required": ["ticker"]
  }
}

悪い description（短すぎて疑問が残る）:

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {"ticker": {"type": "string"}},
    "required": ["ticker"]
  }
}

input_examples（3段階を見せる）:

"input_examples": [
    {"location": "San Francisco, CA", "unit": "fahrenheit"},
    {"location": "Tokyo, Japan", "unit": "celsius"},
    {"location": "New York, NY"},  # 'unit' is optional
],

ツールを強制する:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

説明も欲しいときは auto + user メッセージで指示する:

What's the weather like in London? Use the get_weather tool in your response.

ツールを統合する（別々に作らない）:

  • ❌ create_pr / review_pr / merge_pr —— 3つの別ツール
  • ✅ github_pr（action パラメータを持つ1つ）—— 選択の曖昧さが減る

原典で言及されている関連文書

バックリンク