ai-docs

Writing effective tools for agents — with agents

Properties1
tagstools, mcp, evals, context, agents

7 min read

一行要約

エージェント向けのツールは既存 API の薄いラッパーであってはならない。実際のワークフロー単位に統合され、返り値が高信号で、エラーが指示的であるべきで、その良し悪しは実タスクの eval を回して初めて分かる。

要点

3段階のプロセス

  1. Prototype: 素早く実装し、Claude Code / MCP サーバー / API 直叩きでローカルにテストする
  2. Evaluate: 現実的なタスクで体系的に評価する
  3. Optimize: Claude 自身に結果を分析させ、ツールを改善させる

評価の方法論

タスクの作り方

  • 現実のワークフローに根ざした prompt-response ペアを数十個作る
  • タスクは複数のツール呼び出しの連鎖（場合により数十回）を要求するものにする
  • 良いタスクの例: 「来週 Jane とのミーティングを設定し、直近の企画会議のノートを添付し、会議室を予約して」
  • 各 prompt に検証可能な outcome を対応させる

評価の実行

  • 単純な agentic loop でプログラム的に回す
  • system prompt に reasoning / feedback ブロックを入れて chain-of-thought を引き出す
  • 記録する指標: accuracy、runtime、ツール呼び出し回数、トークン消費、エラー率

結果の分析

  • エージェントの reasoning transcript を読んで、どこで混乱したかを見る
  • 述べられたフィードバックだけでなく、生のツール呼び出し transcript を見る
  • 呼び出しパターンから非効率を見つける

ツール設計 7原則

1. ツールは目的志向で選ぶ（数を増やさない）

More tools don’t always lead to better outcomes. ツールが多いほど良い結果になるとは限らない。

エージェントは従来のソフトウェアと違い context が有限。既存 API をただ包むのではなく、高インパクトなワークフローに合わせて絞り込んで作る。関連操作は統合する。

  • ❌ list_users + list_events + create_event を別々に
  • ✅ 内部で空きを探す schedule_event 1本

2. 明確な namespacing

一貫した prefix でグループ化する（asana_search、asana_projects_search）。context 負荷が減り、ツール選択が正確になる。prefix と suffix のどちらにするかで測定可能な性能差が出る。

3. 返り値は高信号な文脈にする

  • 文脈的な関連度を優先し、高信号な情報だけを返す
  • UUID や mime_type のような暗号的な識別子を、意味のある名前に置き換える
  • 英数字 ID を解釈可能な言語に解決することで「retrieval タスクにおける Claude の精度が、ハルシネーションを減らすことで著しく向上する」

4. レスポンス形式を選べるようにする

response_format の enum パラメータを用意し、エージェントが concise / detailed を選べるようにする。詳細版は後続のツール呼び出しを可能にし、簡潔版は context を節約する。

Slack の例では concise 形式が約1/3のトークン（72 vs 206 トークン）で済んだ。

5. トークン効率の最適化

  • pagination、range selection、filtering、truncation を、妥当なデフォルト付きで実装する
  • 広いクエリではなく的を絞った検索へ誘導するガイダンスを添える
  • Claude Code はツールのレスポンスをデフォルトで 25,000 トークンに制限している

6. エラーメッセージを指示的にする

不透明なエラーコードではなく、行動可能なガイダンスを返す。生の traceback を返す代わりに、正しい入力形式や利用可能な filter オプションを具体的に伝える。

7. ツールの説明文を磨く

  • 説明文は context にロードされるステアリング機構として働く
  • 新しいチームメンバーをオンボードするつもりで書き、暗黙の前提を明示する
  • パラメータ名を曖昧でなくする（user ではなく user_id）
  • Claude Sonnet 3.5 の SWE-bench における SOTA は「ツール説明文の精密な改善によってエラー率を劇的に下げた」ことに続いて達成された

裏付け

Slack と Asana の MCP サーバーについて、Claude が最適化したツールが人間の書いた実装を、held-out テストセット上で上回った。

そのまま使える具体例

評価タスクの書き方（原典の例）:

Schedule a meeting with Jane next week to discuss our latest project.
Attach notes from previous planning meeting and reserve conference room.

ツール統合の判断:

❌ list_users / list_events / create_event  （API をそのまま3本露出）
✅ schedule_event                            （空き探索を内部に隠した1本）

response_format の設計:

response_format: enum["concise", "detailed"]
  concise  → 後続処理に不要な情報を落とす（Slack 例で 72 トークン）
  detailed → 後続のツール呼び出しに必要な ID 等を含む（同 206 トークン）

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク