ストーリー

ツール設計の基本原則

1. 単一責任の原則

1つのツールは1つの明確な責務を持つべきです。

悪い設計:
manage_orders(action, order_id, ...)
→ actionに "search" / "cancel" / "update" を渡す
→ LLMがactionの値を間違える可能性が高い

良い設計:
search_orders(query, status, date_from, date_to)
cancel_order(order_id, reason)
update_order(order_id, fields)
→ ツール名だけで何をするか明確

2. 明確な命名

ツール名はLLMが目的を即座に理解できる命名にします。

3. 自己説明的な説明文

ツールの説明文は、LLMがツール選択の判断材料にする最も重要な情報です。

悪い説明:
"注文を検索します"

良い説明:
"注文番号、顧客ID、注文日の範囲、ステータスで注文情報を検索します。
部分一致検索が可能です。最大100件を返します。
注文の詳細（商品、金額、配送先）を確認したい場合に使用してください。"

4. 厳密な入出力定義

パラメータの型、必須/任意、バリデーションルールを明確に定義します。

// ツール定義の例
const searchOrdersTool = {
  name: "search_orders",
  description: "注文番号、顧客ID、日付範囲、ステータスで注文を検索します。部分一致対応。最大100件返却。",
  parameters: {
    type: "object",
    properties: {
      order_id: {
        type: "string",
        description: "注文番号（例: ORD-12345）。部分一致検索可能。"
      },
      customer_id: {
        type: "string",
        description: "顧客ID（例: CUST-001）"
      },
      status: {
        type: "string",
        enum: ["pending", "confirmed", "shipped", "delivered", "cancelled"],
        description: "注文ステータスでフィルタリング"
      },
      date_from: {
        type: "string",
        format: "date",
        description: "検索開始日（ISO 8601形式: YYYY-MM-DD）"
      },
      date_to: {
        type: "string",
        format: "date",
        description: "検索終了日（ISO 8601形式: YYYY-MM-DD）"
      }
    },
    required: [] // 全て任意（少なくとも1つは指定推奨）
  }
};

エラーハンドリングの原則

ツール側のエラー処理

ツールは成功時も失敗時も、LLMが次のアクションを判断できる情報を返すべきです。

// ツールのレスポンス設計
interface ToolResponse {
  success: boolean;
  data?: unknown;
  error?: {
    code: string;
    message: string;
    suggestion: string; // LLMへの次のアクション提案
  };
}

// 例: 注文検索ツールのエラーレスポンス
{
  success: false,
  error: {
    code: "ORDER_NOT_FOUND",
    message: "注文番号 ORD-99999 は見つかりませんでした",
    suggestion: "顧客IDまたは日付範囲で再検索してください"
  }
}

エラーレスポンスの設計ガイドライン

ツール設計のベストプラクティス

出力のフォーマット

ツール数の適正化

「ツール設計はUXデザインと同じ考え方だ。ユーザー（ここではLLM）にとって直感的で使いやすいインターフェースを設計することが成功の鍵になる」 — 田中VPoE

まとめ

チェックリスト

• ツール設計の4つの基本原則（単一責任、命名、説明文、入出力定義）を理解した
• ツールのパラメータ定義を型安全に設計できる
• LLMが理解しやすいエラーレスポンスの設計方法を理解した
• ツール数の適正化の考え方を把握した

次のステップへ

次は「ファンクションコーリング」を学びます。OpenAI/Claude APIでツールをLLMに接続する具体的な実装方法を理解しましょう。

推定読了時間: 30分