ツールの説明が選択を左右する
モデルは名前ではなく説明からツールを選択します
「ツールの説明が選択を左右する」はCoddyKit上の無料Claude Architectレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはClaude Architect学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Claude Architectコースには全4レッスンが含まれています。
モデルは読み取るのであって、推測しない
Claudeが呼び出すツールを決めるとき、ツール名だけを基準に選ぶわけではありません。各ツールの説明を読み、タスクに適したものを推論します。
これがツール設計における最も重要な事実です。説明が、ツール選択の主要な仕組みだからです。process_refundという名前でも説明が曖昧なツールは、名前が扱いにくくても明確に説明されたツールより、正しく選択するのが難しくなります。
信頼性の高い動作を望むなら、巧妙な命名ではなく、説明文の作成に力を注いでください。
名前は仕様ではない
名前は短く、曖昧です。2つのツールsearch_ordersとlookup_orderを考えてみましょう。名前だけで、どちらがIDで注文を検索するのか、どちらが日付で一覧を絞り込むのか分かるでしょうか。判断できないのは、モデルも同じです。
本当の意味を伝えるのは説明です。
- そのツールが何のためにあるか（目的）。
- 何を返すか。
- どのような入力を想定しているか、例を含めて説明する。
- エッジケースと適用範囲の境界。
ツールには適切な名前を付けてください。ただし、動作の曖昧さを解消するために名前だけを頼りにしてはいけません。
優れた説明の構成
優れたツールの説明は、モデルがそのツールを正しく選択して呼び出すために必要な情報をすべて含みます。次の内容を含めてください。
- 目的 — このツールが行う唯一の役割です。
- 戻り値 — 何が、どのような形式で返されるかです。
- 入力形式と例 — 具体的な引数の例です。
- エッジケース — 空の結果、見つからない場合、曖昧な場合です。
- 適用範囲の境界 — 使用してはいけない場合です。
この境界に関する記述が、似たツール間での誤った振り分けを防ぎます。
lookup_order = {
"name": "lookup_order",
"description": (
"Fetch a single order by its exact order_id. "
"Returns status, items, total, and ship date. "
"order_id format: 'ORD-' + 8 digits, e.g. 'ORD-10293847'. "
"Returns an empty result (not an error) if no order matches. "
"Use this ONLY when you already have a specific order_id; "
"to find orders by customer or date, use search_orders instead."
),
"input_schema": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
}曖昧な説明は誤った振り分けを引き起こす
最もよくある失敗は、簡素すぎる説明や曖昧な説明です。これは試験で頻出する典型的な誤りであり、ツールが誤って選択された理由を問われたときの、よくある誤答でもあります。
説明が不十分だとどうなるか見てみましょう。
get_data: "データを取得します。"fetch_info: "情報を取得します。"
タスクが「顧客の最新の注文を見つける」だった場合、モデルはこの2つを区別できません。誤った方を呼び出したり、選択に迷い続けたりする可能性があります。重複する説明や曖昧な説明は誤った振り分けを引き起こします。必要なのはツール名の変更ではなく、より明確で重複のない表現です。
ツール間の境界を明確にする
2つのツールがどちらも使えそうな場合、それぞれの説明で、もう一方のツールではなくこちらを使うべき状況を明示する必要があります。これにより、選択を混乱させる重複がなくなります。
それぞれの説明が、もう一方のツールに言及し、どのような場合にそちらへ委ねるべきかを示している点に注目してください。この相互の境界が、モデルを正しいツールへ導きます。
tools = [
{
"name": "search_orders",
"description": (
"List orders matching a customer_id and/or date range. "
"Returns an array of order summaries (id, status, total). "
"Use to DISCOVER orders when you do not know the order_id. "
"For full details of one known order, use lookup_order."
),
},
{
"name": "lookup_order",
"description": (
"Fetch full details of ONE order by exact order_id. "
"Use only when the order_id is already known. "
"To find orders, use search_orders first."
),
},
]説明にエッジケースを記載する
エッジケースは、単に呼び出し方だけでなく、その後のモデルの推論にも影響するため、説明に含める必要があります。
特に重要なのは、次の2つの区別です。
- アクセス失敗（システムに接続できなかったため、再試行する可能性がある）と、正常な空の結果（一致するものがないため、再試行せず、そのまま報告する）
- 曖昧な入力に対して何が起きるか。たとえば、複数の顧客が一致する場合です。
「注文が一致しない場合は空の結果を返す」と説明されていれば、モデルは「結果なし」を再試行すべきエラーとして扱いません。また、「名前が一意でない場合は複数の候補を返す」と説明されていれば、推測するのではなく、追加の識別情報を尋ねることができます。
ツールセットを小さく保つ
ツールが多すぎると、説明が完璧でも効果が落ちます。選択は推論を必要とするタスクであり、選択肢が増えるほど判断が分散するためです。
- 信頼性の高い選択には、エージェント1体あたり4〜5個のツールが最適です。
- 18個以上のツールがあると、選択の信頼性は目に見えて低下します。
つまり、適切な説明と小規模なツールセットは相互に補完し合います。各エージェントの役割に合わせてツールの範囲を絞り、その少数のツールを正確に説明してください。肥大化したツールセットは、表現だけでは救えません。
役割に合わせてツールの範囲を絞る
説明の品質と最小権限の原則は、同じ方向を示します。調査用のサブエージェントに返金ツールを持たせるべきではありません。また、読み取り専用のレビュアーにWriteやBashを持たせるべきでもありません。
役割に応じて範囲を絞ると、同時に2つの効果があります。
- 重複する候補を取り除けるため、残った説明を区別しやすくなります。
- 各エージェントを4〜5個のツールという最適な範囲に保てます。
数が少なく役割に適したツールであれば、説明もより明確で重複のないものになります。そして、それこそが正確な選択につながります。
support_agent = AgentDefinition(
name="support",
description="Resolves customer order and refund requests.",
system_prompt="Verify identity, then resolve the request.",
allowed_tools=[
"get_customer",
"lookup_order",
"process_refund",
"escalate_to_human",
], # 4 role-scoped tools, each clearly described
)説明が選択し、tool_choiceが制約する
説明は、どのツールが適しているかを決めます。tool_choiceパラメーターは別の仕組みであり、ツールを呼び出すかどうか、どのように呼び出すかを制約します。
"auto"— モデルがテキストまたはツールを選びます（選択は引き続き説明に左右されます）。"any"— モデルは必ずいずれかのツールを呼び出します。構造化された出力を保証する場合に便利です。{"type":"tool","name":"X"}— 特定の1つのツールを強制的に選びます。
ツールを強制しても、悪い説明が直るわけではありません。単に選択肢をなくすだけです。"auto"や"any"では、モデルは候補の中から選ぶために説明を読み続けるため、表現は依然として明確でなければなりません。
resp = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto"}, # model selects by reading descriptions
messages=messages,
)ツールとリソースの境界
MCPでは、すべてをツールにするべきではありません。サーバーは3種類のプリミティブを公開しており、適切なものを選ぶことで、ツールの説明を目的に集中させられます。
- ツール — 何らかの処理を実行するアクション（返金処理を行う、クエリを実行するなど）
- リソース — スキーマやカタログなど、読み取り専用のデータやコンテキスト
- プロンプト — 再利用可能なテンプレート
読み取り専用のスキーマやカタログをツールではなくリソースとしてモデル化すると、アクション選択の候補から完全に除外できます。これにより、説明内で競合する曖昧な候補が1つ減り、ツール選択が直接的に改善されます。
エラーも選択可能にする
選択は最初の呼び出しで終わるとは限りません。モデルは次に、復旧用のツールを選ぶことがよくあります。その選択は、返されたエラーに左右されます。
「操作に失敗しました」のような一般的なエラーでは、モデルは振り分けの手がかりを得られません。一方、構造化されたMCPエラーなら手がかりを得られます。
isError: trueとerrorCategory（transient / validation / business / permission）isRetryable、message、attempted_query、およびpartial_results（存在する場合）
これによりモデルは、一時的な障害なら再試行し、検証エラーなら修正し、業務上の失敗や権限エラーならエスカレーションするという判断を適切に行えます。処理が行き詰まることもありません。
{
"isError": true,
"errorCategory": "transient",
"isRetryable": true,
"message": "Order service timed out",
"attempted_query": "lookup_order(order_id='ORD-10293847')",
"partial_results": null
}理解度チェック
ツール選択を左右する要素を、実際の誤った振り分けの不具合に適用してみましょう。
まとめ
ツール選択についての重要なポイント：
- Claudeはツール名ではなく、ツールの説明を読んでツールを選択します。
- 優れた説明には、目的、戻り値、例を含む入力形式、エッジケース、適用範囲の境界が記載されています。
- 重複する説明や曖昧な説明は誤った振り分けを引き起こします。各ツールが別のツールではなく自分を選ぶべき状況を、明確な境界として示してください。
- 説明にエッジケースを記載してください。特に、空の結果とアクセス失敗の違い、および曖昧な一致について記載します。
- エージェント1体あたり4〜5個のツールに抑えてください。18個以上になると選択の信頼性が低下します。役割に合わせてツールの範囲を絞ってください。
tool_choice（auto / any / forced）は呼び出しを制約しますが、明確な説明の代わりにはなりません。- 読み取り専用のデータはMCPのリソースとしてモデル化し、モデルが復旧処理へ振り分けられるように構造化されたエラーを返してください。
AI チューターと学ぶ Python — 無料
ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。
- コース
- 26
- レッスン
- 104
よくある質問
「ツールの説明が選択を左右する」レッスンは無料ですか？
はい。「ツールの説明が選択を左右する」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Claude Architectコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Claude Architectコースには全4レッスンが含まれています。
「ツールの説明が選択を左右する」で何を学びますか？
モデルは名前ではなく説明からツールを選択します ブラウザで直接実行するハンズオンコードでClaude Architectを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
Claude Architectを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのClaude Architectは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。
「ツールの説明が選択を左右する」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このClaude Architectレッスンでコードを書いて実行できますか？
はい。すべてのClaude Architectレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- ツールの説明が選択を左右する
- 優れた説明の構造
- 重複するツールを避ける
- 入力形式と例