tool-function-schema-designer

ツール／関数スキーマの設計

LLM が確実に呼び出せる、堅牢なツールスキーマを設計します。

関数スキーマの形式

// OpenAI function calling format
const searchDocsTool = {
  type: "function",
  function: {
    name: "search_documentation",
    description:
      "Search through product documentation using semantic search. Use this when the user asks about features, how-tos, or troubleshooting.",
    parameters: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "The search query, phrased as a question or keywords",
        },
        filters: {
          type: "object",
          properties: {
            category: {
              type: "string",
              enum: ["api", "guides", "tutorials", "troubleshooting"],
              description: "Filter by documentation category",
            },
            version: {
              type: "string",
              description: "Filter by product version (e.g., 'v2.0')",
            },
          },
        },
        max_results: {
          type: "integer",
          minimum: 1,
          maximum: 10,
          default: 5,
          description: "Maximum number of results to return",
        },
      },
      required: ["query"],
    },
  },
};

型付きインターフェース

// TypeScript types matching schema
interface SearchDocsParams {
  query: string;
  filters?: {
    category?: "api" | "guides" | "tutorials" | "troubleshooting";
    version?: string;
  };
  max_results?: number;
}

// Implementation
async function search_documentation(
  params: SearchDocsParams
): Promise<SearchResult[]> {
  const { query, filters = {}, max_results = 5 } = params;

  // Implementation
  return await vectorStore.search(query, {
    filter: filters,
    limit: max_results,
  });
}

検証戦略

import { z } from "zod";

// Zod schema for runtime validation
const searchDocsSchema = z.object({
  query: z.string().min(1, "Query cannot be empty"),
  filters: z
    .object({
      category: z
        .enum(["api", "guides", "tutorials", "troubleshooting"])
        .optional(),
      version: z.string().optional(),
    })
    .optional(),
  max_results: z.number().int().min(1).max(10).default(5),
});

// Validate before execution
function validateAndExecute(toolName: string, params: unknown) {
  const validated = searchDocsSchema.parse(params);
  return search_documentation(validated);
}

ツールレジストリ

export const TOOLS = {
  search_documentation: {
    schema: searchDocsTool,
    implementation: search_documentation,
    validator: searchDocsSchema,
  },
  create_ticket: {
    schema: createTicketTool,
    implementation: create_ticket,
    validator: createTicketSchema,
  },
  // ... more tools
};

// Execute tool safely
async function executeTool(name: string, params: unknown) {
  const tool = TOOLS[name];
  if (!tool) throw new Error(`Unknown tool: ${name}`);

  const validated = tool.validator.parse(params);
  return tool.implementation(validated);
}

呼び出し例

// Example 1: Simple search
{
  "name": "search_documentation",
  "parameters": {
    "query": "How do I authenticate API requests?"
  }
}

// Example 2: With filters
{
  "name": "search_documentation",
  "parameters": {
    "query": "rate limiting",
    "filters": {
      "category": "api",
      "version": "v2.0"
    },
    "max_results": 3
  }
}

エラー処理

interface ToolResult {
  success: boolean;
  data?: any;
  error?: {
    code: string;
    message: string;
  };
}

async function safeExecuteTool(
  name: string,
  params: unknown
): Promise<ToolResult> {
  try {
    const data = await executeTool(name, params);
    return { success: true, data };
  } catch (error) {
    if (error instanceof z.ZodError) {
      return {
        success: false,
        error: {
          code: "VALIDATION_ERROR",
          message: `Invalid parameters: ${error.message}`,
        },
      };
    }
    return {
      success: false,
      error: {
        code: "EXECUTION_ERROR",
        message: error.message,
      },
    };
  }
}

ベストプラクティス

1. 明確な説明：ツールをいつ使用するかを説明します
2. 具体的な型：列挙型、範囲、パターンを使用します
3. 適切なデフォルト値：必須パラメーターを減らします
4. 厳密に検証：LLM の出力をそのまま信用しないでください
5. エラーメッセージ：LLM が誤りを修正できるようにします
6. 呼び出し例：成功例を示します
7. 型安全性：TypeScript のインターフェース

出力チェックリスト

• JSON スキーマを定義
• TypeScript インターフェース
• Zod による検証
• 実装関数
• エラー処理
• 呼び出し例（3 件以上）
• ツールレジストリのエントリー
• ドキュメント