ツールレジストリとは｜説明文を書き直したら、候補が9個から5個に絞れた

説明文を書き直したら候補が9個から5個に絞れた

曖昧な説明と具体的な説明で、質問に対する候補の数を測りました。書き方だけで絞り込みの精度が変わります。

ツールレジストリの説明文の効果を確かめるため、実際に測りました。3つのツールと3つの質問を用意しています。

曖昧な説明は「データを取得する」「情報を取ってくる」「検索する」。具体的な説明は、受け取る引数と返す内容、対象の範囲まで書いたものです。

// 曖昧な説明
const VAGUE = [
  { name: 'get_data',    desc: 'データを取得する' },
  { name: 'fetch_info',  desc: '情報を取ってくる' },
  { name: 'search_docs', desc: '検索する' },
];

// 具体的な説明
const CLEAR = [
  { name: 'get_order',     desc: '注文番号を指定して、1件の注文の明細と配送状況を返す。過去2年分が対象' },
  { name: 'search_faq',    desc: 'キーワードでよくある質問を全文検索し、上位5件の質問と回答を返す' },
  { name: 'get_user_plan', desc: 'ユーザーIDを指定して、契約プラン名と次回請求日を返す' },
];

質問に対して、説明文だけで候補をいくつまで絞れるか

--- 曖昧な説明 ---
  「注文12345はいつ届く？」 候補3個 → 絞れない
  「返品のやり方を教えて」 候補3個 → 絞れない
  「今のプランと次の請求日は？」 候補3個 → 絞れない
  候補の合計: 9個 / 一意に決まった質問: 0 / 3

--- 具体的な説明 ---
  「注文12345はいつ届く？」 候補1個 → 一意に決まる
  「返品のやり方を教えて」 候補3個 → 絞れない
  「今のプランと次の請求日は？」 候補1個 → 一意に決まる
  候補の合計: 5個 / 一意に決まった質問: 2 / 3

絞れました。候補は9個から5個、一意に決まった質問は0件から2件です。ツールの数も機能も変えていません。説明文だけを書き直しました。

何が効いたのか

効いたのは、説明文に質問と結びつく語が入っていることです。「注文番号を指定して」と書いてあれば、注文についての質問と結びつきます。

曖昧な説明にはその手がかりがありません。「データを取得する」では、どの質問とも等しく結びついてしまい、選べません。

1件は絞れなかった

正直に書くと、具体的な説明でも1件は絞れていません。「返品のやり方を教えて」という質問です。返品という語が、どの説明文にも入っていないためです。

これは説明文の限界というより、想定する質問と説明文がずれている状態です。よく聞かれる語を説明文に含めることで改善できます。

登録するときに何を決めておくのか

説明文に加えて、取り消せる操作かどうかを属性として持たせます。これがないと、渡すツールを場面ごとに絞れません。

ツールレジストリに登録するとき、名前と説明だけでは足りません。その操作の性質も一緒に持たせます。

説明文に書く3要素

1. 何を受け取るか。注文番号なのか、キーワードなのか
2. 何を返すか。1件なのか一覧なのか、どんな項目が含まれるか
3. 対象の範囲。過去2年分、上位5件、といった制限

3番目が抜けやすい項目です。範囲を書いておかないと、対象外のデータを探して「見つかりません」と答えることになります。

説明文以外に持たせる属性

選択のためではなく、安全のために持たせる情報もあります。取り消せる操作か、承認が必要か、外部に影響するか。

これらがあると、場面ごとに渡すツールを絞れます。外部の文章を読み込む場面では読み取り専用のものだけ渡す、といった制御が可能になります。

全部を常に渡さない

登録してあるツールを、毎回すべて渡す必要はありません。その場面で使うものだけ渡す方が、選択の誤りも減り、送る量も減ります。

OWASPが指摘する権限の過大さは、想定外の出力に応じて有害な操作が実行されてしまう問題でした。渡すツールを絞ることは、この対策にもなります。

権限の設計はエージェントのセキュリティの記事、渡す量を絞る考え方はコンテキスト設計の記事で扱っています。

ツールレジストリとは何を管理する仕組みなのか

エージェントが使える機能を一覧で持つ仕組みです。名前と説明、そして権限の情報をまとめて管理します。

ツールレジストリは、エージェントが呼び出せる機能を登録しておく場所です。名前・説明・引数の形式・返す内容をまとめて持ちます。

OWASPが説明するとおり、エージェントは開発者から関数を呼ぶ能力を与えられます。その能力の一覧を、どこでどう管理するかという話になります。

散らばると把握できなくなる

小さいうちは、ツールの定義をコードの中に直接書いても困りません。問題は数が増えたときです。どこにどれがあるか分からなくなり、似た機能が重複します。

重複は選択の誤りを招きます。似た名前と似た説明のツールが並ぶと、どちらを使うべきかが判断できなくなります。

説明文が選択の唯一の手がかり

重要なのは、エージェントが説明文だけを見てツールを選ぶことです。中の実装は見えません。

つまり説明文の質が、そのまま選択の精度になります。次の節で、書き方によってどれだけ変わるかを測ります。