エージェント向けの効果的なツールを書く ― エージェントとともに

この記事は Anthropic Engineering Blog の Writing effective tools for agents — with agents（2025年9月11日公開）を日本語に翻訳したものです。

ツールとは何か？

ツールは決定論的なシステムと非決定論的なエージェントを橋渡しする新しいソフトウェアパラダイムを表しています。同じ入力に対して常に同じ出力を生成する従来の API とは異なり、エージェント向けのツールは予測不可能な LLM の振る舞いを考慮する必要があります。エージェントは幻覚を見たり、指示を誤解したり、代替戦略を追求したりする可能性があるのです。

ツールの書き方

プロトタイプの構築

効果的なツール開発は、素早いプロトタイピングから始まります：

1. Claude Code を使用して素早くプロトタイプを作成する
2. LLM フレンドリーなドキュメントを提供する（公式サイトで llms.txt ファイルを確認）
3. ローカル MCP サーバーまたは Desktop 拡張機能でツールをラップしてテストする
4. 手動でテストし、ユーザーフィードバックを収集する

MCP サーバーを追加するコマンド：

claude mcp add <name> <command> [args...]

評価の実行

現実的な評価タスクを生成し、複数のツール呼び出しを必要とするものを用意します。

良い例：

「Jane と Acme Corp プロジェクトについて話し合うミーティングをスケジュールし、企画ノートを添付し、会議室を予約してください」

悪い例：

「来週 [email protected] とミーティングをスケジュールして」

評価には以下を含めます：

• プロンプトと対になる検証可能な結果
• シンプルなエージェントループを使用したプログラム的な評価実行

結果の分析

• エージェントの推論とトランスクリプトをレビューして混乱ポイントを特定
• ツール呼び出しメトリクスで非効率性を検査
• トランスクリプト分析に基づいてツールをリファクタリングするため、エージェント（Claude Code 経由）と協力

効果的なツールを書くための原則

適切なツールの選択

すべての API エンドポイントをツールとしてラップすることは避けてください。エージェントのコンテキスト制限を考慮してツールを設計します。

設計例：

重要な原則：

• ツールは複数ステップの操作を統合すべき
• 少数の適切に設計されたツールは、多数の重複するツールより優れている
• 「エージェントにとって最も使いやすいツールは、人間にとっても驚くほど直感的に理解しやすいものになる」

名前空間

関連するツールを共通のプレフィックスでグループ化します：

サービスレベルの編成：

asana_search
jira_search

リソースレベルの編成：

asana_projects_search
asana_users_search

プレフィックスとサフィックスの命名はどちらもパフォーマンスに影響します。評価でテストしてください。

意味のあるコンテキストを返す

完全性よりも高シグナルな情報を優先します。

避けるべきフィールド：

• uuid
• 256px_image_url
• mime_type

推奨フィールド：

• name
• image_url
• file_type

暗号的な UUID を意味的な識別子に置き換えてください。

トークン効率の最適化

• ページネーション、フィルタリング、トランケーションを妥当なデフォルトで実装
• Claude Code はデフォルトでレスポンスを 25,000 トークンに制限
• 不透明なコードではなく、アクション可能なガイダンスを含む有用なエラーメッセージを提供

ResponseFormat 列挙型を使用した柔軟なレスポンス：

enum ResponseFormat {
   DETAILED = "detailed",
   CONCISE = "concise"
}

トークン効率の具体例：

• 詳細なレスポンス例：206 トークン
• 簡潔なフォーマット：72 トークン
• 約3分の1のコンテキスト消費に削減

ツール説明のプロンプトエンジニアリング

• 新しいチームメンバーに説明するように記述を書く
• 暗黙のコンテキストを明示的にする
• 曖昧でないパラメータ名を使用：user ではなく user_id
• 評価を通じて説明の改良をテスト ― 小さな変更が大きな改善をもたらす

推奨される評価メトリクス

効果的なツール評価には以下のメトリクスを追跡します：

主要な結果

内部テストでは、Claude に最適化されたツールは、Slack と Asana の両方の MCP 実装において、ホールドアウトテストセットで人間が書いたバージョンを大幅に上回る性能を示しました。

結論

効果的なエージェントツールにはソフトウェア設計の再考が必要です。決定論的なパターンから、体系的な評価と反復的な改良を通じて非決定論的なエージェントの振る舞いに対応する設計へとシフトする必要があります。

参考リンク

• Model Context Protocol (MCP) 公式ドキュメント
• Claude Code ドキュメント
• 元記事（英語）