以前の記事「AIエージェントのTool Engineering入門」では概念を扱いました。実装編ではここまで、Harness Engineeringを実装する（何をさせて良いか）、Loop Engineeringを実装する（結果の検証と再実行）、Context Engineeringを実装する（何を見せるか）と進めてきました。
この章のTool Engineeringは、その一段階手前——エージェントが世界に働きかけるための道具そのものをどう設計するかです。
ツールの設計品質は、モデルの性能そのものより結果を左右することがあります。同じモデルでも、ツールの粒度・命名・エラーメッセージの作り方次第で、成功率が大きく変わります。
1. ツールは「関数」ではなく「インターフェース」として設計する
初心者が陥りやすい失敗は、既存の関数をそのままツールとして公開することです。関数のシグネチャは人間のプログラマ向けに最適化されていて、エージェント向けには冗長だったり、逆に説明不足だったりします。
# 悪い例：内部実装をそのまま公開
def query_db(sql: str) -> list:
...
# 良い例：意図が伝わる粒度で公開
def find_users_by_status(status: str, limit: int = 50) -> list[dict]:
"""指定したステータスのユーザーを検索する。
statusは 'active' | 'suspended' | 'pending' のいずれか。"""
...
生のSQLを実行できるツールは柔軟に見えますが、エージェントが誤ったクエリを組み立てるリスクを常に抱えます。「検索」「更新」のように意図が明確な単位でツールを切ると、エージェントが誤用しにくくなります。
2. ツールの数は絞る
ツールが増えるほど、エージェントはどれを使うべきか判断に迷います。似た機能のツールが複数あると、誤った方を選ぶ確率が上がります。
❌ get_user / fetch_user / retrieve_user_data （同じことをする3つのツール）
✅ get_user （1つに統一し、オプション引数で挙動を変える）
Harness Engineeringで許可ツールを絞ったのと同じ発想です——選択肢が多いことは、必ずしも良い設計ではありません。
3. エラーメッセージはエージェント向けに書く
ツールが失敗したとき、返すエラーメッセージは人間のログ向けではなく、エージェントが次の行動を判断できる形にします。
# 悪い例
raise ValueError("Invalid input")
# 良い例
raise ValueError(
"ユーザーID '12345' が見つかりません。"
"list_users() で有効なIDの一覧を確認してから再試行してください。"
)
「何が悪いか」だけでなく「次に何をすべきか」まで含めるのは、Loop Engineeringのフィードバック設計と同じ原則です。エージェントはこのメッセージを読んで、次のツール呼び出しを自分で組み立てます。
4. 副作用のあるツールとないツールを区別する
読み取り専用のツールと、状態を変更するツールは、名前の時点で区別できるようにします。
# 読み取り専用（安全に何度でも呼べる）
def get_order_status(order_id: str) -> str: ...
# 副作用あり（呼ぶたびに状態が変わる）
def cancel_order(order_id: str) -> bool: ...
命名規則をget_* / list_*（読み取り）と create_* / update_* / delete_*（書き込み）で統一しておくと、Harness Engineeringの権限設計とツール設計を一致させやすくなります。実際、Claude CodeのReadとWriteの分離も同じ考え方です。
5. ツールの結果は「次の一手」を想定して設計する
ツールが返す値は、単なるデータではなく、エージェントが次に取るべき行動のヒントを含められます。
def run_tests() -> dict:
return {
"passed": 42,
"failed": 3,
"failed_tests": ["test_login", "test_logout", "test_signup"],
"suggestion": "失敗したテストのファイルを確認してください: tests/test_auth.py"
}
suggestionのようなフィールドを添えることで、エージェントが次に何を読みに行けばいいかを自分で調べ直す手間を省けます。これはContext Engineeringの「見せ方の設計」の延長でもあります。
まとめ
Tool Engineeringの実装は、次の5点に集約されます。
- 既存の関数をそのまま公開せず、意図が伝わる粒度でツールを切る
- 似た機能のツールを重複させず、選択肢を絞る
- エラーメッセージは「次に何をすべきか」まで含めて書く
- 読み取り専用と副作用ありを命名規則で区別する
- ツールの結果に、次の一手のヒントを含める
拙著『AIエージェント設計論 — Harness/Loop EngineeringからRAGまで』では、この考え方の全体像を扱っています。