一行要約
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,64}$ にマッチすること |
description | 何をするか、いつ使うか、どう振る舞うかの詳細な平文 |
input_schema | JSON Schema |
input_examples | （任意）スキーマ検証される入力例の配列 |
他の任意プロパティ: cache_control、strict、defer_loading、allowed_callers。
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 を使うときは特に重要 - ツールの応答は高信号の情報だけを返す — 不透明な内部参照ではなく、意味のある安定した識別子（slug や UUID）を返し、Claude が次のステップを推論するのに必要なフィールドだけを含める
良い description と悪い description の差は、「何を返すか」「いつ使うか」「パラメータの意味」を書いているかどうか。
input_examples
複雑なツール（ネストしたオブジェクト、任意パラメータ、形式に敏感な入力）で特に有用。
- 各例はツールの
input_schemaに照らして valid でなければならない。無効な例は 400 エラー - server tool（web search、code execution など）では使えない
- トークンコスト: 単純な例で 20〜50 トークン、複雑なネストオブジェクトで 100〜200 トークン
巧いのは「フル装備 → 中間 → 最小」の3段階を見せること — Claude が任意パラメータをいつ含めるべきかを学ぶ。
tool_choice の4択
| 値 | 挙動 |
|---|---|
auto | Claude が呼ぶかどうかを決める（tools があるときの既定） |
any | いずれかのツールを必ず使う（特定はしない） |
tool | 特定のツールを必ず使う |
none | ツールを使わせない（tools がないときの既定） |
重要な副作用:
When you have
tool_choiceasanyortool, the API prefills the assistant message to force a tool to be used. This means the models will not emit a natural language response or explanation beforetool_usecontent 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.
制約:
- manual extended thinking（
{type: "enabled"}）ではanyとtoolはエラー。 adaptive thinking は強制ツール使用に対応する - Claude Mythos Preview は強制ツール使用に非対応（
any/toolは 400） tool_choiceの変更はキャッシュされたメッセージブロックを無効化する。 ツール定義と system prompt はキャッシュされたまま
Guaranteed tool calls with strict tools: Combine
tool_choice: {"type": "any"}with strict tool use to guarantee both that one of your tools will be called AND that the tool inputs strictly follow your schema. Setstrict: true. strict tools による確実なツール呼び出し:tool_choice: {"type": "any"}と strict tool use を組み合わせると、自分のツールのいずれかが必ず呼ばれることと、そのツールの入力がスキーマに厳密に従うことの両方を保証できる。strict: trueを設定する。
ツール使用時の system prompt
tools を渡すと、API がツール定義・ツール設定・ユーザーの system prompt から専用の system prompt を組み立てる。
モデル選択
- 複雑なツールと曖昧なクエリには最新の 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つ） 選択の曖昧さが減る原典で言及されている関連文書
- writing-tools-for-agents — ツール設計の深い指針（統合・命名・応答の形）
- advanced-tool-use —
input_examplesによる精度 72% → 90% - tool-search-tool — namespace が重要になる理由
- thinking — thinking と
tool_choiceの非互換 - prompt-caching —
tool_choice変更によるキャッシュ無効化