Skip to Content
Docs03. 実装ツール定義の設計
中級tool-usefunction-calling更新: 2026-07-05この記事の誤りを報告

この記事の音声は準備中です。

音声の一覧・再生リストへ

ツール定義の設計

この記事の目的

ツール定義(名前・説明文・入力スキーマ・結果)を、モデルが正しく選択・呼び出し・回復できる形に設計できるようになります。ツール使用 が「仕組み」を扱ったのに対し、本記事は「良い定義の書き方」という実践に踏み込みます。

対象読者

  • Agent のツールセットを設計・保守するアプリケーションエンジニア
  • 「モデルがツールを正しく使ってくれない」問題を定義の改善で解決したいエンジニア

前提知識

本文

概要: ツール定義はプロンプトである

ツール定義はスキーマ宣言に見えますが、実体はモデルへのプロンプトの一部です。名前・説明文・引数の説明のすべてが「いつ・どう使うか」の判断材料としてモデルに読まれます。したがって、良いツール定義の条件は良いプロンプトの条件と同じです — 具体的で、曖昧さがなく、判断基準を含むこと。

詳細: 命名 — 動詞 + 対象で、語彙を統一する

  • 動詞 + 対象の形にします(search_expenses、send_notification)。名詞だけ(expenses)や汎用動詞だけ(do_action)は選択の手がかりになりません
  • 語彙を揃えます。同じ操作に search_ と find_ と query_ を混在させると、モデルにとっては意味の違いがあるように見えます。動詞の使い分け(get_ = 単一取得 / search_ = 検索 / list_ = 一覧)をチーム内で決めて統一します
  • 関連ツールが多い場合はプレフィックスでグループ化します(expense_search、expense_submit)

詳細: 説明文 — 「いつ使うか」「何ができないか」まで書く

説明文はモデルがツールを選ぶ唯一の材料です。次の 4 点を含めます。

  1. 何をするか — 1 文で
  2. いつ使うか — 呼び出すべき状況を明示的に書きます。2026 年時点の主要モデルはツール選択が保守的な傾向があり、「〜の質問を受けたらこのツールを呼ぶ」のような発火条件の明示が選択率を大きく改善します
  3. 何ができないか — 隣接するできそうなこと(照会専用で申請はできない、など)を否定しておくと誤用が減ります
  4. 形式の注意 — 引数の形式例やよくある間違い

悪い例と良い例:

{ "name": "search_expenses", "description": "経費を検索する" }
{
  "name": "search_expenses",
  "description": "社員の経費精算履歴を検索します。精算の状況・金額・日付についての質問を受けたときに使ってください。経費の新規申請・修正・削除はできません(照会専用)。月をまたぐ集計は月ごとに複数回呼び出してください。"
}

詳細: 入力スキーマ — 自由文字列を減らす

  • 各引数に 説明と形式例 を付けます("対象月。YYYY-MM 形式(例: 2026-06)")
  • 選択肢が有限なら enum で固定 します。自由文字列にすると表記揺れ(「精算済み」「精算済」「completed」)がツール側の突き合わせ失敗になります
  • 必須と任意を正しく分けます。本当は任意の引数を必須にすると、モデルが値をでっち上げます
  • 迷ったら引数は少なく。「モデルに判断させたい境界」以外の複雑さはツール内部のコードに寄せます(ツール使用 の粒度の議論)

詳細: 結果とエラーの設計

  • 成功結果は判断に必要なフィールドに絞ります。内部 API のレスポンスをそのまま返すと、無関係なメタデータがコンテキストを圧迫します
  • エラーメッセージは actionable に。「エラーが発生しました」ではなく「month は YYYY-MM 形式で指定してください(例: 2026-06)」。モデルはこの文字列だけを頼りに引数を直します
  • 大きい結果には上限と続きの手段(件数制限 + 「さらに絞り込むには〜」の案内)を組み込みます

詳細: ツールセットの保守

  • タスク種別ごとにセットを絞ります。全ツール常時投入は選択ミスとトークンコストの温床です(コンテキストエンジニアリング の最小十分の原則)
  • 説明文をテストします。ツール一覧だけをモデルに見せて「それぞれいつ使うか」を説明させると、説明文の曖昧さ・重複が浮き彫りになります
  • 同義ツールを作らないよう、追加前に既存ツールとの役割重複を確認します

実装例

動くコードは examples/python/tool-use/ を参照してください。本記事の search_expenses の定義と、Agent ループ の最小ループを組み合わせた自己完結のサンプルです。

実務での注意点

アンチパターン

  • 内部 API の直写し → 低レベルエンドポイントを 1:1 でツール化すると、モデルが毎回呼び出し順序を推論してエラーを量産する → 「モデルに判断させたい境界」で切り直し、決定論的な組み合わせはツール内部で行う
  • エラーがスタックトレースの生ダンプ → モデルは直し方を読み取れず、同じ失敗を繰り返す → 何が悪く・どうすればよいかを 1〜2 文で返す
  • 同義ツールの併存(search_docs と find_documents)→ モデルには意味差があるように見え、選択が不安定になる → 統合するか、役割の違いを両方の説明文に明記する

チェックリスト

  • ツール名が「動詞 + 対象」で、語彙(get / search / list 等)が全ツールで統一されている
  • 説明文に「いつ使うか」の発火条件と「何ができないか」が書いてある
  • すべての引数に説明と形式例があり、有限の選択肢は enum になっている
  • エラーメッセージから直し方が分かる
  • 大きい結果に件数制限がある
  • ツール一覧をモデルに説明させるテストで曖昧さを確認した

関連トピック

参考資料

TODO・未確認事項

セクション概要Agent 向けプロンプト設計