ツール設計のベストプラクティス ─ description・命名・レスポンス設計

結論から言うと、ツール設計の善し悪いはdescriptionの質でほぼ決まります。モデルはdescriptionを読んでツールを選び、引数を組み立てます。どんなに便利なAPIをつなげても、説明が貧弱だとモデルは使い方を誤ります。Anthropicの公式ドキュメントも「descriptionはツールパフォーマンスに影響する最大の要素」と強調しています。

なぜdescriptionが最重要なのか

エージェントが使えるツールが複数あるとき、モデルは「どのツールを、いつ、どう呼ぶか」を自分で判断します。このとき頼りにするのがdescriptionです。コードを読むわけでも、実際に試すわけでもありません。

Anthropicのドキュメントによると、良いdescriptionには4つの要素が必要とされています。

• 何をするか: ツールの目的を一文で
• いつ使うか（使わない状況も）: 呼び出しの判断基準
• 各パラメータの意味と形式: 例を添えると尚良い
• 重要な制限事項: 返さない情報・対応しないケース

下の比較を見てください。

// 悪い例
{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker."
}

// 良い例
{
  "name": "get_stock_price",
  "description": "NYSE/NASDAQに上場する企業の最新株価（USD）を取得する。ユーザーが特定銘柄の現在値を尋ねたときに使う。他の財務情報（時価総額・業績）は返さない。tickerはアルファベット大文字例: AAPL。"
}

良い例はモデルに「何を返さないか」まで伝えています。制限を明示すると、モデルが誤った期待で結果を解釈する失敗が減ります。

命名のコツ ─ プレフィックスを付ける

ツールが増えてくると名前の衝突や混乱が起きます。Anthropicのエンジニアリングブログでは、サービス名をプレフィックスに付けることを推奨しています。

github_list_prs
github_create_branch
slack_send_message
slack_read_channel

こうすると「どのサービスの何をする」が名前だけで一目瞭然になり、モデルが正しいツールを選びやすくなります。

ツール数を減らす ─ 関連操作はまとめる

PRの作成・レビュー・マージをそれぞれ別ツールにすると、モデルはどれを使えばいいか迷います。代わりに github_pr という1つのツールに action パラメータを持たせると、選択の曖昧さが減ります。

{
  "name": "github_pr",
  "input_schema": {
    "properties": {
      "action": { "type": "string", "enum": ["create", "review", "merge"] },
      "pr_number": { "type": "integer" }
    }
  }
}

レスポンスは「必要な情報だけ」に絞る

ツールが返す値も設計のうちです。UUIDのような不透明な識別子より意味のある名前を返す、不要なフィールドを省く、長いリストにはページネーションを使う、といった工夫でコンテキストウィンドウの無駄遣いを防げます。レスポンスが肥大すると、モデルが次のステップを考えるための情報が埋もれてしまいます。

まとめ

ツール設計の4大原則は「詳細なdescription・サービスプレフィックスの命名・関連操作のまとめ・必要最小限のレスポンス」です。新しいツールを追加するたびに「モデルの立場でdescriptionを読み返す」だけで、エージェントの精度と安定性が大きく改善するとされています。