Tool/Function Schema Designer

Design robust tool schemas that LLMs can reliably invoke.

Function Schema Format

// 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"], }, }, };

Typed Interfaces

// 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, }); }

Validation Strategy

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); }

Tool Registry

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 Calls

// 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 } }

Error Handling

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, }, }; } }

Best Practices

• Clear descriptions: Explain when to use the tool

• Specific types: Use enums, ranges, patterns

• Sensible defaults: Reduce required parameters

• Validate rigorously: Don't trust LLM output

• Error messages: Help LLM correct mistakes

• Example calls: Show success cases

• Type safety: TypeScript interfaces

Output Checklist

• JSON schema defined

• TypeScript interface

• Validation with Zod

• Implementation function

• Error handling

• Example calls (3+)

• Tool registry entry

• Documentation