Tool Callingの道具をどう設計する？名前・入力・結果・失敗を曖昧にしない
AIエージェントが間違った道具を選ぶとき、原因がモデルだけにあるとは限らない。道具の名前が似ている、説明が短い、必須入力が分からない、結果が長すぎる。Tool Callingは、モデルへ自由な操作権を渡す仕組みではなく、アプリケーションが用意した操作の契約から一つを選ばせる仕組みだ。契約を曖昧にすれば、呼び出しも確認しにくくなる。
例えば、記事を調べる道具と記事を公開する道具が、どちらも article という名前だったとする。「最新記事を確認して」という依頼で、モデルが書き込み側を選んでも、名前から誤りを見つけにくい。これは道具設計を説明するための架空例であり、特定のAPIの挙動ではない。
名前と説明で使う場面を限定する
道具名には対象と動作を含める。blog_search_articles と blog_publish_article のように、読む操作と状態を変える操作を区別する。説明には「何をするか」だけでなく、どの場面で使うか、返さない情報、実行による影響を書く。Anthropicの道具定義資料も、明確な説明を重要な要素として挙げ、各入力の意味や制約を書くことを勧めている。
似た道具を増やすほど選択は難しくなる。一方で、読み取りと削除のように影響が大きく違う操作を一つの道具へ詰め込むと、許可の境界が見えにくい。対象、権限、失敗時の扱いが同じ操作はまとめ、確認方法が異なる操作は分ける。名前の整理だけでなく、実行側が許可する操作を狭く保つ。
入力Schemaは「期待」ではなく検証条件
入力をJSON Schemaで定義すれば、日付、ID、列挙値、必須項目を機械的に確認できる。MCPのTools仕様も、道具の inputSchema をJSON Schemaとして定義している。自由文一つで対象、期間、操作をすべて解釈するより、article_id、start_date、end_date のように項目を分けた方が、実行前に値を確認しやすい。
Schemaに合うことは、操作してよいことの保証ではない。存在する記事IDか、日付の前後関係が正しいか、利用者に権限があるかは実行時にも確かめる。形式が正しい削除要求でも、対象範囲が想定より広ければ止める必要がある。モデルが省略した値を危険な既定値で埋めない。
結果は次の判断に必要な情報へ絞る
道具の結果には、成否、対象の安定したID、取得または変更した値、必要なら更新日時を含める。検索道具がページ全体のHTMLを返すと、次の判断に不要な文や指示まで文脈へ入る。必要な項目へ整形し、結果が外部から取得した未信頼の内容である場合は、その境界も保つ。
MCPは構造化した結果と outputSchema を定義できる。結果の形式が一定なら、モデルだけに解析を任せず、クライアント側でも必須項目や型を検証できる。結果が0件である状態と、道具が失敗した状態を同じ空文字で返さない。次の処理が続けるべきか止まるべきか判断できる形にする。
失敗を正常な結果に見せない
タイムアウト、認証切れ、対象なし、入力不正、権限不足は原因が異なる。利用者向けの秘密情報を漏らさない範囲で、再試行できる失敗か、入力を直すべき失敗かを区別する。道具が失敗したのに空の一覧を返すと、エージェントは「該当データなし」と誤解して回答を作るかもしれない。
書き込み操作には、同じ要求を再試行しても二重登録にならない仕組みを用意する。実行IDや一意制約を使い、結果には新規作成か既存処理の再取得かを示す。モデルへ再試行の判断を任せる前に、サーバー側で重複実行を防ぐ。
道具単体と選択の両方を評価する
最初に、正しい入力で成功するか、不正な入力と権限不足を拒否するかを道具単体で確かめる。次に、複数の道具をモデルへ提示し、代表的な依頼で正しい道具と引数を選ぶかを見る。「記事を探す」「下書きを作る」「公開状況だけ確認する」のように、似ている依頼を並べると説明の曖昧さが見つかりやすい。
成功率だけでなく、誤った書き込みを試みた回数、不要な呼び出し回数、失敗後の停止、結果を最終回答へ正しく反映したかを記録する。Tool Callingの品質は、正しいJSONを出せたかだけではなく、道具を選ぶ前から結果を使うところまでの一連で測る。