Skip to content
Published on

ツール表面の設計 — スキーマ1行が成功率を動かします

🇰🇷KO🇺🇸EN🇯🇵JA🇨🇳ZH
Split View필사 모드
シェア
Authors

ツールを増やしたら成功率が下がった

エージェントにツールを5個追加したら、課題成功率がかえって下がったとします。構成した例ですが、ツール表面を広げたことのあるチームなら方向に見覚えがあるはずです。理由は二重です。ツールのスキーマは毎ターン、コンテキスト予算を食い、似たツールが多いほど選択がぶれます。モデルにできることを増やすのと、いまの課題をよりよく終わらせるのは別の問題です。

だからツール表面という言葉が役に立ちます。設計対象はツール1個1個ではなく、モデルが向き合うインターフェース全体だという意味だからです。Anthropicのエージェント構築ガイドはこれをエージェント・コンピュータ・インターフェースと呼び、人間のUIと同じだけ手をかけよと勧めます。自社のSWE-bench作業でプロンプトよりツールの最適化に多くの時間を使ったという回顧が、その勧めの重さを示しています。

ツール数の呪い：全部公開か、キュレーションか

最初に決めるのは個数です。手持ちのツールを全部公開する方式は準備が楽ですが、スキーマだけで予算が減り、類似ツール間の誤選択が増えます。逆に、この課題に使うものだけを選んで公開するキュレーションが、ほとんどの作業で既定値になるべきです。余力があれば、その上にこの課題専用のツールをひとつ作って載せる選択肢もあります。専用ツールは作って維持するコストがかかりますが、複数の呼び出しを一度に減らします。

Anthropicのツール作成ガイドが勧める統合はその延長線上にあります。ユーザー一覧、予定一覧、予定作成をそれぞれツールとして渡す代わりに、内部でその段階を処理する予定調整ツールひとつにまとめる、という具合です。ツール数が減れば、スキーマのコストと誤選択と呼び出しの往復が一緒に減ります。

名前と説明がインターフェースです

モデルはコードを見られず、名前と説明だけを見ます。だから説明の1行が挙動を変えます。同じガイドはサービスとリソースの単位で名前を束ねるネームスペーシングを勧めます。asana_searchとjira_searchのように接頭辞が所属を語れば、似た検索ツールが複数あってもモデルは迷いにくくなります。

# 悪い例 — 何をいつ使うのか、モデルが推測するしかない
- name: proc2
  description: 'プロセスユーティリティ'

# 良い例 — いつ使い、いつ別のツールを使うかが説明にある
- name: code_search_symbol
  description: 'リポジトリ内でシンボルの定義位置を探す。本文の全文検索には code_grep を使うこと。'

良い説明の基準は、新入りに渡すオンボーディング文書と同じです。何をするツールか、いつ使うか、いつ使ってはいけないか、返り値はどんな形か。説明が良くなるほど、プロンプトでツールの使い方を説明していた段落が消えていきます。

パラメータ設計：ミスを構造で防ぐ

パラメータは、モデルが間違えうる箇所を減らす方向に設計します。Anthropicのエージェントガイドはこれを製造業のポカヨケにたとえます。ミスを指摘する代わりに、ミスが不可能な構造を作るのです。たとえば相対パスと絶対パスの両方を受け付けるパラメータは、作業ディレクトリが変わった瞬間にエラーの源になります。絶対パスだけに絞れば、そのミスの類型は構造的に消えます。識別子も同じです。意味のないUUIDをやり取りさせるより、人間が読める名前を使わせたほうがモデルの正確さが上がる、というのがツール作成ガイドの観察です。

失敗をどう返すか

ツールは失敗します。設計対象は失敗そのものではなく、失敗がモデルに戻る形式です。例外文字列とスタックトレースをそのまま返せば、モデルは原因を知らないまま同じ呼び出しを繰り返しがちです。失敗の原因といま試せる代替案を構造化して返せば、次の呼び出しが変わります。

{
  "error": "file_not_found",
  "path": "src/pay/handler.py",
  "hint": "このリポジトリのソースルートは services/ です。",
  "try_next": ["list_dir services/pay", "code_search_symbol handler"]
}

この形式は第4回で扱う再試行ポリシーと直接絡みます。原因が返ってこない再試行は同じ失敗の買い直しであり、代替案が返ってくる再試行は探索になります。再試行上限を決める前に、失敗の返し方を直すのが順序として先です。

応答も表面です：トークン効率

ツールが返す応答は、そのままコンテキスト予算から引き落とされます。だからツール作成ガイドは、ページネーション、範囲指定、フィルタリング、妥当な既定値での切り詰めをツール側の責務に置きます。4千行のファイルを丸ごと返す読み取りツールより、既定200行で範囲パラメータを受け付ける読み取りツールのほうが、表面として優れています。切り詰めたなら、切り詰めた事実とより狭く検索する方法を応答に書き添えるところまでが設計です。

ツールも評価の対象です

ツール表面は作って終わりではなく、評価で磨く対象です。同じガイドが勧めるループは単純です。プロトタイプを作り、現実的な課題で評価を回し、エージェントの残した記録を読んでどこで迷ったかを探し、ツールを直してまた測る。ツール1個の説明文を変えるのもハーネスの変更なので、第7回で扱うハーネス指紋が捕まえるべき変更です。どの表面が良いかを判定するのは結局評価者であり、その評価者の信頼性が第5回のテーマです。

実際に練習する

ハーネスエンジニアリングRPGでは、最小3個、課題別に厳選した8個、厳選＋専用ツール、全部公開の21個という4つのツール表面を、どのシナリオにも差し替えられます。全部公開がスキーマのコストで崩れるシナリオと、最小構成が迂回コストで崩れるシナリオの両方を経験すると、キュレーションが既定値である理由が体に残ります。

参考資料

  • Writing effective tools for agents — Anthropic, 2025-09-11 — ネームスペーシング、ツール統合、意味のある識別子、トークン効率の良い応答、評価ループがこの記事にあります。
  • Building effective agents — Anthropic, 2024-12-19 — エージェント・コンピュータ・インターフェースという観点、ポカヨケなパラメータ設計、SWE-bench作業でツールに多くの時間を使ったという回顧がこの記事にあります。
  • 冒頭の成功率の話と本文のスキーマ・失敗返却の例は、説明のために構成したものです。
Discuss on Twitter • View on GitHub