tool-design

エージェント向けツール設計

すべてのツールは、決定論的なシステムと非決定論的なエージェントの間の契約として設計してください。人間向けの API とは異なり、エージェント向けツールでは、説明だけで契約が明確に伝わる必要があります。エージェントは説明から意図を推測し、期待される形式に一致する呼び出しを生成するためです。曖昧さがあれば、どれほどプロンプトエンジニアリングを重ねても解決できない潜在的な失敗要因になります。

このスキルの作業単位は、単一のツールまたはツールカタログです。サブエージェントを導入するかどうかの判断は、multi-agent-patterns の担当範囲です。このスキルは、決定論的なコードとエージェントをつなぐインターフェース層を担当します。

有効にするタイミング

作業単位がツールの場合に、このスキルを有効にしてください。

• 新しいツールの説明、スキーマ、またはレスポンス形式を作成する場合。
• エージェントが誤ったツールを選んだり、不正な呼び出しを生成したりするケースをデバッグする場合。
• 重複するツールカタログを統合する場合（典型的な「ツールが17個あり、エージェントが半分の確率で選択を誤る」ケース）。
• エージェントが自力で修正できる、実用的なエラーメッセージを設計する場合。
• カタログ全体でツール名とパラメーター名に一貫性を持たせる場合（MCP の名前空間、動詞と名詞による命名）。
• サードパーティ製ツールを追加する前に、統合の原則に照らして評価する場合。

隣接する作業でも、以下の別スキルが担当するものには、このスキルを有効にしないでください。

• 作業をサブエージェントに分担するか、より多くのツールを使って単一のエージェントで実行するかの判断：multi-agent-patterns。
• 軌跡レベルでツール出力のトークン量を減らすこと（観測のマスキング、大規模なフォーマットオプションの選択）：context-optimization。

主な概念

統合の原則に基づいてツールを設計してください。ある状況でどのツールを使うべきかを人間のエンジニアが確実に判断できないなら、エージェントにそれ以上の判断を期待することはできません。各ツールの目的が明確に一つになるまでツール群を絞り込んでください。エージェントは説明を比較してツールを選ぶため、少しでも重複があれば選択ミスにつながります。

ツールの説明はすべて、エージェントの振る舞いを形作るプロンプトエンジニアリングとして扱ってください。説明は人間向けのドキュメントではなく、エージェントのコンテキストに挿入され、推論を直接導くものです。ツールが何をするか、いつ使うか、何を返すかを説明に含めてください。この3点こそ、エージェントがツールの選択時に評価する項目です。

詳細なトピック

ツールとエージェントのインターフェース

契約としてのツール

各ツールは、それだけで完結する契約として設計してください。人間が API を呼び出す場合は、ドキュメントを読んで規約を理解し、適切なリクエストを送れます。一方、エージェントは一つの説明ブロックから契約のすべてを推測する必要があります。形式の例、想定されるパターン、明示的な制約を含め、契約を明確にしてください。呼び出し元が知る必要のある情報は省略しないでください。エージェントは呼び出し前に確認の質問をできないためです。

プロンプトとしてのツール説明

ツールの説明は、エージェントのコンテキストに直接読み込まれ、全体として振る舞いを導くことを踏まえて記述してください。「データベースを検索する」のような曖昧な説明に不可解なパラメーター名を組み合わせると、エージェントに推測を強いることになり、誤った呼び出しにつながります。その代わり、使用する状況、パラメーター形式の例、妥当なデフォルト値を含めてください。説明の各語句は、ツール選択の精度を高めるか、下げるかのどちらかです。

名前空間と整理

コレクションが大きくなるにつれて、共通のプレフィックスを使ってツールに名前空間を設定してください。階層的に整理すると、エージェントが適切なツールを見つけやすくなります。データベース操作が必要な場合は db_* 名前空間に、ウェブ操作が必要な場合は web_* 名前空間に振り分けられます。名前空間がなければ、エージェントは平坦な一覧にあるすべてのツールを評価しなければならず、ツール数が増えるほど選択精度が低下します。

統合の原則

包括的なツールを一つにまとめる 互いに重複する複数の限定的なツールではなく、包括的なツールを一つ構築します。list_users、list_events、create_eventを個別に実装するのではなく、空き状況を調べて一度の呼び出しで予定を設定するschedule_eventを実装します。包括的なツールがワークフロー全体を内部で処理するため、呼び出しを正しい順序で連鎖させる負担をエージェントから取り除けます。

統合が効果を発揮する理由 エージェントのコンテキストと注意力には限りがあるため、統合を適用します。ツール群の各ツールはツール選択時に注意を奪い合い、各説明はコンテキストのトークン予算を消費し、機能の重複は曖昧さを生みます。統合によって、重複する説明がなくなり、選択の曖昧さが解消され、実質的なツールセットが縮小します。Architectural Reduction Case Studyは、専門特化型のツールを、測定結果がより優れた、より小規模なプリミティブツールセットへと削減した具体例です（claim-tool-design-vercel-d0-reduction）。

統合しない場合 動作が根本的に異なる場合、異なるコンテキストで使用する場合、または個別に呼び出す必要がある場合は、ツールを分けておきます。過度な統合は別の問題を生みます。パラメーターやモードが多すぎる単一のツールは、エージェントが正しくパラメーターを指定するのが難しくなります。

アーキテクチャの削減

統合の原則を論理的な極限まで適用し、ほとんどの専門特化型ツールを取り除いて、プリミティブで汎用的な機能に置き換えます。実運用でのエビデンスによると、この方法は洗練されたマルチツールアーキテクチャを上回ることがあります。

ファイルシステムエージェントのパターン データ探索、スキーマ参照、クエリ検証のためのカスタムツールを構築する代わりに、単一のコマンド実行ツールを通じてファイルシステムへ直接アクセスできるようにします。エージェントは標準的なUnixユーティリティ（grep、cat、find、ls）を使ってシステムを調査し、操作します。この方法が有効なのは、ファイルシステムがモデルによく理解されている実証済みの抽象化であり、標準ツールの動作が予測しやすく、エージェントが定義済みのワークフローに縛られず柔軟にプリミティブを連鎖でき、ファイル内の優れたドキュメントによって要約ツールが不要になるためです。

複雑さより削減が優れる場合 データレイヤーのドキュメントが充実し、構造が一貫している場合、モデルに十分な推論能力がある場合、専門特化型ツールがモデルの能力を引き出すのではなく制限している場合、または成果の改善よりも足場の保守に多くの時間を費やしている場合は、削減を選びます。基盤となるデータが雑然としている、またはドキュメントが不十分な場合、モデルにない専門知識が必要な分野の場合、安全上の制約によってエージェントの操作を制限する必要がある場合、または構造化されたワークフローによって実際にメリットが得られる操作の場合は、削減を避けます。

将来のモデルに向けて構築する 現在の制約を固定化する洗練されたアーキテクチャではなく、モデルの進歩によってメリットが得られる最小限のアーキテクチャを設計します。各ツールが新しい機能を可能にするのか、それともモデル自身で処理できる推論を制限しているのかを考えます。「ガードレール」として構築されたツールは、モデルの進歩とともに負担になることがよくあります。

実運用でのエビデンスについては、Architectural Reduction Case Studyをご覧ください。

ツールの説明を設計する

説明の構成 各ツールの説明は、次の4つの問いに答えるように構成します。

1. ツールは何をするか。ツールが実行する内容を正確に記述し、「役立ちます」や「〜に使用できます」のような曖昧な表現は避けます。
2. いつ使用すべきか。直接的なきっかけ（「ユーザーが料金について尋ねた」など）と間接的な兆候（「最新の市場価格が必要」など）を明記します。
3. どのような入力を受け付けるか。各パラメーターの型、制約、デフォルト値、形式の例を説明します。
4. 何を返すか。出力形式、構造、成功時の応答例、エラー条件を記載します。

パラメーターのデフォルト値の選択 デフォルト値は、一般的なユースケースを反映するように設定します。デフォルト値を設定すると、不要なパラメーター指定をなくしてエージェントの負担を軽減でき、省略されたパラメーターによるエラーも防げます。エージェントがすべてのオプションを理解していなくても有用な結果が得られるデフォルト値を選びます。

応答形式の最適化

ツールの応答サイズはコンテキストの使用量に大きく影響するため、簡潔な形式と詳細な形式の選択肢を用意します。簡潔な形式では必須フィールドのみを返し、確認に適しています。詳細な形式ではオブジェクト全体を返し、完全なコンテキストに基づいた判断に適しています。エージェントが適切に選択できるよう、ツールの説明に各形式をいつ使うべきかを記載します。

エラーメッセージの設計

問題をデバッグする開発者と、失敗から復旧するエージェントの両方を対象にエラーメッセージを設計します。エージェント向けのエラーメッセージには、実行可能な情報を必ず含めます。何が問題だったのか、どう修正すればよいのかを明記します。再試行可能なエラーには再試行の指針を、入力エラーには修正後の形式の例を、不完全なリクエストには不足しているフィールドを具体的に記載します。「失敗しました」とだけ伝えるエラーでは、復旧に役立つ情報がまったく得られません。

ツール定義スキーマ

すべてのツールで一貫したスキーマを確立します。ツール名には動詞と名詞のパターン（get_customer、create_order）を使用し、ツール間でパラメーター名（常に customer_id を使用し、id と identifier を使い分けない）と戻り値のフィールド名を統一します。一貫性により、エージェントの認知負荷が軽減され、ツール間の汎化性能が向上します。

ツールコレクションの設計

説明の重複はモデルの混乱を招き、ツールの数を増やしても常に結果が向上するわけではないため、ツールコレクションは目的が重複しない最小限のセットに絞ります。本当にツールを増やす必要がある場合は、名前空間を使って論理的にグループ化します。ドメインごとのツールグループ化、例に基づく選択のヒント、専用のサブツールに振り分けるアンブレラツールなど、選択の仕組みを実装します。

MCP ツールの命名要件

「ツールが見つからない」エラーを避けるため、MCP（Model Context Protocol）では常に完全修飾されたツール名を使用します。

形式：ServerName:tool_name

# Correct: Fully qualified names
"Use the BigQuery:bigquery_schema tool to retrieve table schemas."
"Use the GitHub:create_issue tool to create issues."

# Incorrect: Unqualified names
"Use the bigquery_schema tool..."  # May fail with multiple servers

サーバーのプレフィックスがないと、複数の MCP サーバーが利用可能な場合に、エージェントがツールを見つけられないことがあります。すべてのツール参照でサーバーのコンテキストを含める命名規則を確立します。

エージェントを使用したツールの最適化

観測されたツールの失敗をエージェントにフィードバックし、問題の診断と説明の改善に活用します。報告された効率向上は、対象のツールカタログで再現するまでは、特定のワークロードに限られるものとして扱います。

ツールテストエージェントのパターン：

def optimize_tool_description(tool_spec, failure_examples):
    """
    Use an agent to analyze tool failures and improve descriptions.

    Process:
    1. Agent attempts to use tool across diverse tasks
    2. Collect failure modes and friction points
    3. Agent analyzes failures and proposes improvements
    4. Test improved descriptions against same tasks
    """
    prompt = f"""
    Analyze this tool specification and the observed failures.

    Tool: {tool_spec}

    Failures observed:
    {failure_examples}

    Identify:
    1. Why agents are failing with this tool
    2. What information is missing from the description
    3. What ambiguities cause incorrect usage

    Propose an improved tool description that addresses these issues.
    """

    return get_agent_response(prompt)

この仕組みによりフィードバックループが生まれます。ツールを使うエージェントが失敗データを生成し、そのデータを使ってエージェントがツールの説明を改善することで、今後の失敗が減少します。

ツール設計のテスト

明確性、完全性、復旧可能性、効率性、一貫性の5つの基準に照らして、ツール設計を評価します。代表的なエージェントのリクエストを提示し、期待される動作に照らして生成されたツール呼び出しを評価することでテストします。

実践的なガイダンス

ツール選択のフレームワーク

ツールコレクションを設計する際は、次の手順に従います。

1. エージェントが実行する必要のある個別のワークフローを特定します
2. 関連するアクションを包括的なツールにまとめます
3. 各ツールの目的を明確かつ曖昧さのないものにします
4. エラーケースと復旧手順を記載します
5. 実際のエージェントとのやり取りでテストします

ツール監査チェックリスト

エージェントに追加する前に、すべてのツールについてこのチェックリストを使用してください。

1. 名前：動詞＋名詞の形式にし、カタログに複数のドメインがある場合は名前空間を付けます。
2. 説明：ツールが何をするのか、いつ使用するのか、何を返すのかを記載します。
3. スキーマ：すべてのパラメーターに型、制約、デフォルト値、値の例を指定します。
4. 戻り値の形式：成功時とエラー時のペイロードを文書化し、機械で読み取れる形式にします。
5. 復旧：各エラーで、再試行する前にエージェントが何を変更すべきかを示します。
6. 重複：同じ起動条件を持つツールが他にないようにします。
7. 統合の判断：個別の呼び出しが必要でない限り、関連する小規模なツールを統合します。
8. トークンへの影響：大きな応答には、簡潔モードまたはファイル参照モードを用意します。

例

例 1：適切に設計されたツール

def get_customer(customer_id: str, format: str = "concise"):
    """
    Retrieve customer information by ID.

    Use when:
    - User asks about specific customer details
    - Need customer context for decision-making
    - Verifying customer identity

    Args:
        customer_id: Format "CUST-######" (e.g., "CUST-000001")
        format: "concise" for key fields, "detailed" for complete record

    Returns:
        Customer object with requested fields

    Errors:
        NOT_FOUND: Customer ID not found
        INVALID_FORMAT: ID must match CUST-###### pattern
    """

例 2：設計のよくないツール

この例では、ツール設計におけるいくつかのアンチパターンを示します。

def search(query):
    """Search the database."""
    pass

この設計の問題点：

1. 曖昧な名前：「search」は曖昧です。何を、どのような目的で検索するのでしょうか？
2. パラメーターの不足：どのデータベースを使うのでしょうか？クエリはどのような形式で指定すべきでしょうか？
3. 戻り値の説明がない：この関数は何を返すのでしょうか？リストでしょうか、文字列でしょうか？エラー処理はどうなっているのでしょうか？
4. 使用状況の説明がない：エージェントは、ほかのツールではなくこのツールをいつ使用すべきでしょうか？
5. エラー処理がない：データベースを利用できない場合、どうなるのでしょうか？

失敗のパターン：

• より具体的なツールを使うべき場面で、エージェントがこのツールを呼び出す可能性があります
• エージェントが正しいクエリ形式を判断できません
• エージェントが結果を解釈できません
• エージェントが失敗から復旧できません

ガイドライン

1. 何をするのか、いつ使うのか、何を返すのかが分かる説明を書きます
2. 統合によって曖昧さを減らします
3. トークン効率を高めるため、応答形式のオプションを実装します
4. エージェントが復旧できるエラーメッセージを設計します
5. 一貫した命名規則を確立し、それに従います
6. ツールの数を抑え、整理のために名前空間を使用します
7. 実際のエージェントとのやり取りでツール設計をテストします
8. 観察された失敗のパターンに基づいて反復改善します
9. 各ツールがモデルの能力を高めるのか、制約するのかを検討します
10. 特化したラッパーよりも、プリミティブで汎用的なツールを優先します
11. ツールの高度化よりも、ドキュメントの品質向上に投資します
12. モデルの改善を活かせる、最小限のアーキテクチャを構築します

注意点

1. 曖昧な説明：「顧客情報を求めてデータベースを検索する」のような説明では、疑問が多く残ります。対象のデータベース、クエリの形式、返却されるデータの形式を明確にしてください。
2. 分かりにくいパラメーター名：x、val、param1のような名前のパラメーターでは、エージェントが意味を推測しなければなりません。ドキュメントを読み進めなくても用途が分かる、説明的な名前を使ってください。
3. エラーからの復旧方法に関する説明不足：「エラーが発生しました」のような汎用メッセージで失敗するツールでは、復旧の手掛かりが得られません。すべてのエラー応答で、何が問題だったのか、次に何を試せばよいのかをエージェントに伝える必要があります。
4. ツール間での命名の不統一：あるツールではid、別のツールではidentifier、さらに別のツールではcustomer_idを使うと、混乱を招きます。ツールコレクション全体でパラメーター名を統一してください。
5. MCP 名前空間の衝突：複数の MCP ツールプロバイダーが似た名前のツールを登録している場合（例：2 つのサーバーがどちらもsearchを公開する）、エージェントは区別できません。常に完全修飾形式のServerName:tool_nameを使い、新しいプロバイダーを追加する際は衝突がないか監査してください。
6. 古くなったツールの説明：基盤となる API の進化に伴い、説明が不正確になります。パラメーターが追加され、返却形式が変わり、エラーコードも変更されます。説明もコードと同様に扱い、バージョン管理し、API の変更時にレビューし、現在の動作と照らし合わせてテストしてください。
7. 過度な統合：1 つのツールに多くのワークフローを処理させると、パラメーターリストが非常に長くなり、エージェントは適切な組み合わせを選ぶのに苦労します。ツールに 8～10 個を超えるパラメーターが必要な場合、または根本的に異なるユースケースに対応する場合は、分割してください。
8. パラメーターの増えすぎ：省略可能なパラメーターが多すぎると、エージェントの意思決定を妨げます。エージェントが評価しなければならないパラメーターが増えるたびに、認知的負荷が増します。適切なデフォルト値を設定し、関連するオプションを形式のプリセットにまとめ、あまり使わないパラメーターはoptionsオブジェクトに移してください。
9. エラーコンテキストの不足：どの入力が、なぜ失敗したのか、正しい入力形式は何かを示さず、「失敗しました」や「無効な入力」としか伝えないエラーメッセージでは、エージェントは自力で修正できません。すべてのエラー応答に、無効な値、期待される形式、具体例を含めてください。

インテグレーション

このスキルはツールインターフェース層を担当します。関連する判断は、ほかの箇所が担当します。

• multi-agent-patterns：ツール数の多い 1 つのエージェントと、ツールカタログの小さい 2 つのエージェントのどちらが適切かを判断します。「これをサブエージェントに分割すべきか」という質問は、こちらに振り分けてください。
• context-optimization：軌跡レベルのトークン効率、観測のマスキング、多数のツール呼び出しにおける応答形式オプションの選択を担当します。「蓄積されたツール出力のトークン量を減らすにはどうすればよいか」という質問は、こちらに振り分けてください。
• context-optimization（references/fundamentals.md）：ツール定義がアテンションの予算をどのように消費するかという概念的な質問を扱います。「ツールを追加すると、なぜルーティングの精度が低下するのか」という質問は、こちらから確認してください。
• evaluation：ツールセットによってエージェントの全体的な成果が向上したかどうかを評価します。

参考資料

内部資料：

• ベストプラクティスのリファレンス - 読むタイミング：新しいツールをゼロから設計するとき、または既存のツールコレクションの品質上の不足を監査するとき
• アーキテクチャの縮小に関するケーススタディ - 読むタイミング：プリミティブを優先して専門化されたツールを削除することを検討するとき、または複雑なツールアーキテクチャが正当化されるかを評価するとき

このコレクション内の関連スキル：

• context-optimization（基礎資料）- ツールのコンテキストに関するやり取り
• evaluation - ツールのテストパターン

外部リソース：

• MCP（Model Context Protocol）のドキュメント - 読むタイミング：複数サーバーのエージェント環境向けのツールを実装するとき、またはツールのルーティング障害をデバッグするとき
• フレームワークのツール規約 - 読むタイミング：新しいエージェントフレームワークを導入し、ツール設計の原則をフレームワーク固有の API に対応付ける必要があるとき
• エージェント向け API 設計のベストプラクティス - 読むタイミング：既存の人間向け API をエージェント向けのツールインターフェースに変換するとき
• エージェントアーキテクチャのケーススタディ - 読むタイミング：ツールを統合するか評価するとき、またはアーキテクチャ縮小に関する本番環境での根拠を求めるとき