Write a Tool Schema

You have now studied every major dimension of tool schemas: what they contain, why descriptions are the most important field, how parameter types and enums constrain valid arguments, what makes a schema fail in practice, and how security concerns shape design. In this lesson you will apply all of it. The centerpiece is an extended design activity — you will write a complete, production-quality function schema from a specification, then critique it, then improve it. Writing schemas is the primary skill of anyone building AI agents professionally.

Before You Build: The Schema Design Checklist

Before writing any schema, a professional agent developer works through a mental checklist. Run through these questions for every tool you design: Name: Is it a snake_case verb-noun pair? Is it unique among all tools in this agent? Will someone reading it know instantly what the tool does? Description: Does it explain what the tool returns? Does it say when to use it? Does it say when NOT to use it (especially if another tool handles adjacent cases)? Is it specific enough that a model could distinguish this tool from every other tool in the set? Parameters: Does every parameter have a type and a description? Have I used enums for parameters with a fixed set of valid values? Have I set minimum/maximum for numeric parameters where a valid range exists? Is the required list accurate — truly required parameters only, optional ones genuinely optional with sensible defaults described? Security: Is this tool read-only or does it write/delete/send/charge? If it writes, does it need a confirmation step or idempotency key? Does it process untrusted content? Does it need to be scoped to a specific resource subset? Error behavior: Have I documented what the tool returns on failure? Does the implementation return structured errors, not null or exceptions?

Here is a worked example of schema evolution — the same tool written at three quality levels: Level 1 (inadequate): name: 'search' description: 'Searches for things.' parameters: { q: { type: 'string' } } Level 2 (functional but incomplete): name: 'search_articles' description: 'Searches for news articles.' parameters: query: { type: 'string', description: 'Search terms' } limit: { type: 'integer' } required: ['query'] Level 3 (production-quality): name: 'search_news_articles' description: 'Searches a curated database of news articles published within the last 2 years. Returns up to 20 results with title, publication date, source name, URL, and a 2-sentence excerpt. Use when the user needs factual information likely covered by news reporting. Do not use for scientific papers or academic research — use search_academic_papers instead. Do not use for real-time events from the last 24 hours — use get_breaking_news instead.' parameters: query: { type: 'string', description: 'The search query. Use specific terms rather than full questions for best results. Example: supply chain semiconductor shortage, not What happened with semiconductor supply chains?' } limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Number of results to return. Default 5.' } sort: { type: 'string', enum: ['relevance', 'date_desc', 'date_asc'], description: 'Sort order. relevance ranks by relevance score. date_desc returns newest first. Default: relevance.' } date_from: { type: 'string', description: 'ISO 8601 date (YYYY-MM-DD). Only return articles published on or after this date. Optional.' } required: ['query'] The progression from Level 1 to Level 3 is not cosmetic. Each improvement makes model behavior more predictable, more correct, and safer to deploy.