tool-design

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

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

このスキルの作業単位は、単一のツールまたはツールカタログです。プロジェクトの形態、パイプラインアーキテクチャ、タスクとモデルの適合性、プロジェクトレベルでのコストに関する判断は、project-development の担当です。サブエージェントを導入するかどうかの判断は、multi-agent-patterns の担当です。このスキルが担うのは、決定論的なコードとエージェントをつなぐインターフェイス層です。

有効にするタイミング

作業単位がツールの場合に、このスキルを有効にします。

• 新しいツールの説明、スキーマ、または応答形式を作成するとき。
• エージェントが誤ったツールを選んだり、不正な形式の呼び出しを生成したりするケースをデバッグするとき。
• 重複するツールカタログを整理するとき（典型的な例は、「ツールが 17 個あるのに、エージェントが半分の確率で間違ったものを選ぶ」というケースです）。
• エージェントが自力で修正できる、実行可能なエラーメッセージを設計するとき。
• カタログ全体でツール名とパラメーター名を一貫させるとき（MCP の名前空間、動詞と名詞による命名など）。
• 第三者製ツールを追加する前に、統合の原則に照らして評価するとき。

他のスキルが担当する、関連作業にはこのスキルを有効にしないでください。

• プロジェクトでそもそも LLM を使用するべきか、またはパイプラインの各段階をどうするべきかを判断するとき：project-development。
• 作業をサブエージェントに分割するか、より多くのツールを持つ単一のエージェントを実行するかを判断するとき：multi-agent-patterns。
• トラジェクトリーレベルでツール出力のトークン量を減らすとき（観測のマスキング、規模に応じた形式オプションの選択など）：context-optimization。

中核となる概念

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

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

詳細なトピック

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

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

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

名前空間と整理 ツール群が増えるにつれて、共通の接頭辞でツールに名前空間を付けます。階層的にグループ化すると、エージェントがツールを選びやすくなるためです。データベース操作が必要な場合、エージェントは db_* 名前空間へ振り分けます。ウェブ操作が必要な場合は、web_* へ振り分けます。名前空間がなければ、エージェントは平坦なリストにあるすべてのツールを評価しなければならず、ツール数の増加に伴って選択精度が低下します。

統合の原則

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

統合が効果を発揮する理由 エージェントのコンテキストと注意力には限りがあるため、統合を適用します。ツールコレクション内の各ツールはツール選択時に注意を奪い合い、それぞれの説明がコンテキストのトークン予算を消費し、機能の重複が曖昧さを生みます。統合により、冗長な説明をなくし、選択時の曖昧さを解消し、実質的なツールセットを縮小できます。Vercelのd0事例研究は、専門化されたツールをより小さなプリミティブなツールセットに減らし、測定可能な成果を向上させた具体例です（claim-tool-design-vercel-d0-reduction）。

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

アーキテクチャの縮減

専門化されたツールの大半を削除し、プリミティブで汎用的な機能に置き換えることで、統合の原則を論理的な極限まで推し進めます。実運用の実績から、このアプローチは高度なマルチツールアーキテクチャを上回ることが示されています。

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

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

将来のモデルに向けて構築する 現在の制約を固定化する高度なアーキテクチャではなく、モデルの改善から恩恵を受ける最小限のアーキテクチャを設計します。各ツールが新しい機能を可能にしているのか、それともモデルが単独で処理できる推論を制約しているのかを確認してください。「ガードレール」として構築されたツールは、モデルの改善に伴って負担になることがよくあります。

実運用の実績については、アーキテクチャ縮減の事例研究を参照してください。

ツールの説明の設計

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

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

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

応答形式の最適化

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

エラーメッセージの設計

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

ツール定義スキーマ

すべてのツールで一貫したスキーマを確立します。ツール名には動詞と名詞のパターン（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. 過度な統合：単一のツールで多くのワークフローに対応させると、パラメーターリストが非常に長くなり、エージェントが適切な組み合わせを選ぶのに苦労します。8～10 個を超えるパラメーターが必要な場合や、根本的に異なるユースケースに対応する場合は、ツールを分割してください。
8. パラメーターの過剰な増加：省略可能なパラメーターが多すぎると、エージェントの判断を妨げます。エージェントが評価しなければならないパラメーターが増えるたびに、認知負荷も増加します。適切なデフォルト値を設定し、関連するオプションを形式プリセットにまとめ、使用頻度の低いパラメーターは options オブジェクトに移してください。
9. エラーコンテキストの不足：どの入力がなぜ失敗したのか、有効な入力がどのようなものかを示さず、「失敗しました」や「無効な入力」とだけ伝えるエラーメッセージでは、エージェントは自力で修正できません。すべてのエラー応答に、無効な値、想定される形式、具体例を含めてください。

統合

このスキルが担当するのはツールインターフェース層です。関連する判断は別の場所で扱います。

• project-development：プロジェクトの構成、パイプラインの各ステージの選択、タスクとモデルの適合性、プロジェクトレベルでのコスト見積もり。「適切なツール API は何か」ではなく「適切なパイプラインアーキテクチャは何か」という質問の場合は、そちらに案内してください。
• multi-agent-patterns：ツールの多いエージェント 1 つと、ツールカタログの小さいエージェント 2 つのどちらが適切かの判断。「これをサブエージェントに分割すべきか」という質問の場合は、そちらに案内してください。
• context-optimization：軌跡レベルでのトークン効率、観測のマスキング、複数のツール呼び出しにおける応答形式オプションの選択。「蓄積されたツール出力のトークン量をどう減らすか」という質問の場合は、そちらに案内してください。
• context-fundamentals：ツール定義が注意予算をどのように消費するかという概念的な質問。「ツールを追加するとルーティング精度が低下するのはなぜか」という質問の場合は、まずそちらを確認してください。
• evaluation：ツールセットによってエージェント全体の成果が改善したかどうかの評価。

参考資料

内部資料：

• ベストプラクティスの参考資料 - 読むタイミング：新しいツールを一から設計するとき、または既存のツール群を監査して品質上の不足を確認するとき
• アーキテクチャの簡素化に関する事例研究 - 読むタイミング：プリミティブを優先して特化型ツールを削除することを検討するとき、または複雑なツールアーキテクチャが妥当かどうかを評価するとき

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

• context-fundamentals - ツールとコンテキストのやり取り
• evaluation - ツールのテストパターン

外部リソース：

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

---

スキルのメタデータ

作成日: 2025-12-20 最終更新日: 2026-05-15 作成者: Agent Skills for Context Engineering のコントリビューター バージョン: 2.2.0