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

エージェント向けツール設計 は何をしますか？

すべてのツールを、決定論的なシステムと非決定論的なエージェント間の契約として設計してください。人間向けAPIとは異なり、エージェント向けツールは説明文だけで契約を明確にする必要があります。エージェントは説明文から意図を推測し、期待される形式に一致する呼び出しを生成します。あいまいさはすべて、プロンプトエンジニアリングでは修正できない潜在的な障害モードになります。

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

いつアクティブにするか

作業単位がツールである場合にこのスキルをアクティブにします。

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

他のスキルが担当する、隣接する作業ではこのスキルをアクティブにしないでください。

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

中核概念

統合の原則に基づいてツールを設計します。人間のエンジニアが特定の状況でどのツールを使用すべきかを明確に言えないのであれば、エージェントがより良い判断をできると期待すべきではありません。各ツールが明確な目的を一つだけ持つまでツールセットを削減します。なぜなら、エージェントは説明文を比較してツールを選択し、重複があると選択エラーが発生するからです。

すべてのツール説明文は、エージェントの動作を形成するプロンプトエンジニアリングとして扱ってください。説明文は人間向けのドキュメントではありません。エージェントのコンテキストに注入され、推論を直接導きます。ツールが何をするか、いつ使用するか、何を返すかという3つの質問に答える説明文を書いてください。これらの質問はまさに、エージェントがツール選択時に評価するものだからです。

詳細トピック

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

ツールとしての契約 各ツールを自己完結型の契約として設計します。人間がAPIを呼び出すときは、ドキュメントを読み、規約を理解し、適切なリクエストを行います。エージェントは単一の説明ブロックから契約全体を推測する必要があります。形式の例、期待されるパターン、明示的な制約を含めることで、契約を明確にします。呼び出し元が知る必要がある情報は何も省略しないでください。エージェントは呼び出しを行う前に確認の質問をすることができないからです。

プロンプトとしてのツール説明文 ツール説明文は、直接エージェントのコンテキストにロードされ、集合的に動作を導くことを認識して書いてください。「データベースを検索」のような曖昧な説明文と難解なパラメータ名では、エージェントは推測せざるを得ず、誤った呼び出しを生成します。代わりに、使用コンテキスト、パラメータ形式の例、適切なデフォルト値を含めてください。説明文のすべての単語は、ツール選択の精度を向上させるか、低下させるかのどちらかです。

名前空間と整理 コレクションが大きくなるにつれて、共通のプレフィックスの下でツールに名前空間を付けてください。エージェントは階層的なグループ化の恩恵を受けるためです。エージェントがデータベース操作を必要とする場合、db_* 名前空間にルーティングされます。ウェブ操作が必要な場合は web_* にルーティングされます。名前空間がない場合、エージェントはフラットなリスト内のすべてのツールを評価する必要があり、数が増えるにつれて選択精度が低下します。

統合の原則

単一の包括的なツール 複数の狭いツールを重複させるのではなく、単一の包括的なツールを構築します。list_users、list_events、create_event を個別に実装する代わりに、空き状況を見つけて一度にスケジュールする schedule_event を実装します。包括的なツールは内部で完全なワークフローを処理し、エージェントが正しい順序で呼び出しを連鎖させる負担を取り除きます。

統合が効果的な理由 エージェントは限られたコンテキストと注意力しか持たないため、統合を適用します。コレクション内の各ツールはツール選択中に注意を競い合い、各説明文はコンテキストバジェットトークンを消費し、機能の重複はあいまいさを生み出します。統合は冗長な説明文を排除し、選択のあいまいさを取り除き、実効的なツールセットを縮小します。Vercel の d0 ケーススタディは、専門化されたツールをより小さなプリミティブなツールセットに削減し、測定可能な成果が向上した具体的な例です（claim-tool-design-vercel-d0-reduction）。

統合すべきでない場合 ツールが根本的に異なる動作を持ち、異なるコンテキストで使用される場合、または独立して呼び出し可能である必要がある場合は、ツールを個別に維持します。過度の統合は別の問題を引き起こします。パラメータとモードが多すぎる単一のツールは、エージェントが正しくパラメータ化するのが難しくなります。

アーキテクチャの縮小

統合の原則を論理的な極限まで押し進め、ほとんどの専門化されたツールを削除し、プリミティブで汎用的な機能に置き換えます。本番環境での証拠は、このアプローチが洗練されたマルチツールアーキテクチャよりも優れたパフォーマンスを発揮できることを示しています。

ファイルシステムエージェントパターン データ探索、スキーマ検索、クエリ検証のためのカスタムツールを構築する代わりに、単一のコマンド実行ツールを通じてファイルシステムへの直接アクセスを提供します。エージェントは標準のUnixユーティリティ（grep、cat、find、ls）を使用してシステムを探索および操作します。これは、ファイルシステムがモデルが深く理解している実証済みの抽象化であり、標準ツールは予測可能な動作を持ち、エージェントは事前定義されたワークフローに制約されることなくプリミティブを柔軟に連鎖でき、ファイル内の適切なドキュメントが要約ツールを不要にするため、効果的です。

複雑さよりも縮小が有効な場合 データ層が適切に文書化され一貫して構造化されている場合、モデルに十分な推論能力がある場合、専門化されたツールがモデルを制約していて有効にしていなかった場合、または成果を改善するよりもスキャフォールディングの維持により多くの時間を費やしている場合に、縮小を選択します。基礎となるデータが乱雑で文書化が不十分な場合、ドメインにモデルが欠いている専門知識が必要な場合、安全性の制約でエージェントのアクションを制限する必要がある場合、または操作が構造化されたワークフローから真に恩恵を受ける場合には、縮小を避けます。

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

本番環境での証拠については、Architectural Reduction Case Study を参照してください。

ツール説明文エンジニアリング

説明文の構造 すべてのツール説明文を、次の4つの質問に答えるように構成します。

1. このツールは何をするのか？ツールが正確に何を達成するかを記述します。「役立つ」や「使用できる」のような曖昧な言葉は避けてください。
2. いつ使用すべきか？直接的なトリガー（「ユーザーが価格について尋ねる」）と間接的なシグナル（「現在の市場レートが必要」）を指定します。
3. どのような入力を受け付けるか？各パラメータを、型、制約、デフォルト値、形式の例とともに記述します。
4. 何を返すか？出力形式、構造、成功した応答の例、エラー条件を文書化します。

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

応答形式の最適化

ツールの応答サイズはコンテキストの使用量に大きく影響するため、応答形式のオプション（簡潔版と詳細版）を提供します。簡潔形式は確認に適しており、必須フィールドのみを返します。詳細形式は完全なオブジェクトを返し、完全なコンテキストが意思決定を促進する場合に適しています。各形式をいつ使用すべきかをツール説明文に文書化し、エージェントが適切に選択できるようにします。

エラーメッセージの設計

エラーメッセージは、問題をデバッグする開発者と障害から回復するエージェントの2つの対象者向けに設計します。エージェントにとって、すべてのエラーメッセージは実用的でなければなりません。つまり、何が問題で、どのように修正するかを述べる必要があります。再試行可能なエラーには再試行ガイダンスを、入力エラーには修正された形式の例を、不完全なリクエストには具体的な不足フィールドを含めます。「失敗」とだけ言うエラーは、回復のためのシグナルをまったく提供しません。

ツール定義スキーマ

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

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

ツールコレクションは、目的が重複しない最小限のセットに制限します。説明文の重複はモデルの混乱を引き起こし、ツールの数が多いほど常に良い結果につながるとは限らないためです。真により多くのツールが必要な場合は、名前空間を使用して論理的なグループを作成します。選択メカニズム（ドメインによるツールグループ化、例ベースの選択ヒント、専門化されたサブツールにルーティングする包括的ツール）を実装します。

MCPツール命名要件

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

形式: ServerName:tool_name

# 正しい：完全修飾名
「テーブルスキーマを取得するには、BigQuery:bigquery_schema ツールを使用してください。」
「イシューを作成するには、GitHub:create_issue ツールを使用してください。」

# 誤り：非修飾名
「bigquery_schema ツールを使用してください...」  # 複数のサーバーがあると失敗する可能性があります

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

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

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

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

def optimize_tool_description(tool_spec, failure_examples):
    """
    エージェントを使用してツールの失敗を分析し、説明文を改善します。

    プロセス:
    1. エージェントが多様なタスクにわたってツールを使用しようとする
    2. 障害モードと摩擦点を収集する
    3. エージェントが失敗を分析し、改善案を提案する
    4. 改善された説明文を同じタスクでテストする
    """
    prompt = f"""
    このツール仕様と観測された失敗を分析してください。

    ツール: {tool_spec}

    観測された失敗:
    {failure_examples}

    以下を特定してください:
    1. エージェントがこのツールで失敗している理由
    2. 説明文に欠けている情報
    3. 誤った使用法を引き起こすあいまいさ

    これらの問題に対処する、改善されたツール説明文を提案してください。
    """

    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"):
    """
    IDによって顧客情報を取得します。

    使用する場合:
    - ユーザーが特定の顧客詳細について尋ねる場合
    - 意思決定のために顧客コンテキストが必要な場合
    - 顧客IDを確認する場合

    Args:
        customer_id: 形式 "CUST-######" (例: "CUST-000001")
        format: "concise" はキーフィールドのみ、"detailed" は完全なレコード

    Returns:
        要求されたフィールドを持つ顧客オブジェクト

    Errors:
        NOT_FOUND: 顧客IDが見つかりません
        INVALID_FORMAT: IDは CUST-###### パターンに一致する必要があります
    """

例2: 不適切なツール設計

この例は、いくつかのツール設計のアンチパターンを示しています:

def search(query):
    """データベースを検索します。"""
    pass

この設計の問題点:

1. 曖昧な名前: 「search」は曖昧です。何を、どのような目的で検索するのでしょうか？
2. パラメータの欠如: どのデータベースですか？クエリはどのような形式を取るべきですか？
3. 戻り値の説明なし: この関数は何を返しますか？
4. エラー処理なし: 検索が失敗したらどうなりますか？
5. 使用ガイダンスなし: このツールをいつ使用するか、いつ使用しないかについての情報がありません。