"A tool is only as good as its schema. Vague tool descriptions produce unpredictable behavior. Precise schemas with clear boundaries produce reliable systems. The engineering discipline is in the schema design, not the tool implementation."
AI Platform Architect, HealthMetrics
Introduction
Tool schemas define the contract between AI models and the tools they can invoke. A well-designed schema tells the model exactly what a tool does, what parameters it accepts, and what outputs it returns. Service boundaries define where tool responsibility ends and model responsibility begins. Getting both right is essential for building reliable AI products that use tools.
Anatomy of a Tool Schema
A complete tool schema includes several essential components that work together to enable reliable tool invocation.
Tool Name
The tool name should be a verb or verb phrase that clearly describes the action. Names like get_customer, search_products, or send_message are clear. Names like customer_action or do_stuff are not.
Description
The description explains what the tool does in plain language. This description is the primary way models understand when to use the tool. Be specific about what the tool returns and any important limitations.
Parameter Schema
Parameters define what inputs the tool accepts. Each parameter needs a name, type, description, and whether it is required or optional. JSON Schema format is the standard for parameter definitions.
Response Schema
While not always formalized, documenting the expected response structure helps models interpret results correctly. Specify the shape of returned data and any important field semantics.
Service Boundaries: Where Does the Tool End?
A critical question in tool design is determining what the tool is responsible for versus what the model should handle. Service boundaries define this division of responsibility.
Interpretation, reasoning, response synthesis, error handling for ambiguous cases
Data retrieval, external actions, API calls, side effects, structured operations
The Single Responsibility Principle for Tools
Each tool should do one thing well. A tool that tries to do too much has fuzzy boundaries. A tool that does one precise thing is easier to test, debug, and reason about. If you find yourself writing "and also..." in a tool description, split the tool into multiple tools.
What Belongs in Tools
Data retrieval: Tools excel at fetching specific, structured data from databases, APIs, or search indices. If the model needs to know something specific that exists in your systems, a tool should retrieve it.
External actions: Sending messages, creating records, triggering workflows, making payments. These are actions with side effects that tools should handle.
Complex computation: Calculations that require precision or specific algorithms should live in tools, not in model reasoning.
Validation and transformation: Converting data formats, validating inputs against business rules, transforming API responses into consistent shapes.
What Belongs in Models
Interpretation: Understanding user intent, resolving ambiguity, determining appropriate responses.
Reasoning: Drawing conclusions from retrieved information, connecting concepts, making judgments.
Natural language generation: Producing coherent, well-formatted responses that synthesize tool results.
Error handling for edge cases: When tool results are incomplete or unexpected, models can often work around issues that would break rigid code.
Schema Design Best Practices
Be Specific About Limitations
Do not just describe what a tool does. Describe what it does not do, or what constraints apply. If a search tool only returns active products, say so. If an API has rate limits, mention them.
The Ambiguity Trap
Vague schemas produce unpredictable tool invocations. "Search for products" might mean anything. "Search for active products in the catalog by name, returning price and availability" tells the model exactly what to expect and prevents surprising invocations.
Use Consistent Naming Conventions
Establish naming conventions for tools and parameters and stick to them. If you use camelCase for parameters, do it consistently. If tools follow a verb_noun pattern, apply it everywhere.
verb_noun naming follows patterns like get_customer and create_order, and works well for tools that perform specific actions. noun_by_noun naming follows patterns like customer_by_id and products_by_category, and suits data retrieval with specific keys. search_by_noun naming follows patterns like search_products and search_orders, and is appropriate for free-text search operations.
Parameter Type Precision
Use the most specific type possible for parameters. If a parameter is a date, use string with date format. If it is an enum, define the allowed values. Avoid type ambiguity that forces the model to guess.
Practical Example: HealthMetrics Tool Schema Design
Situation: HealthMetrics needed tools for hospital staff to query patient data, appointment schedules, and resource utilization.
Problem: Initial schemas were vague. A tool called get_patient_info returned different data shapes for different query types.
Solution: The team split into focused tools with precise schemas including get_patient_demographics that returns name, DOB, contact info, and insurance, get_patient_appointments that returns scheduled appointments with times and departments, get_patient_admissions that returns current and historical admissions, and search_patients that provides free-text search returning patient IDs and basic info.
Result: Tool invocation accuracy improved from 72% to 96%. Models could reliably select the right tool because the boundaries were clear.
Tool Catalog Design
When your AI product has many tools, organizing them into a catalog helps models discover and select appropriate tools.
Tool Grouping
Group related tools into categories. A customer service AI might have tool groups for orders, products, account, and support. Within each group, tools follow consistent naming and response patterns.
Capability Advertising
Tools should advertise their capabilities in ways that help models decide when to use them. This includes not just what the tool does, but what types of queries it handles best.
Versioning and Evolution
Tools evolve over time. Schema changes can break AI product behavior if not handled carefully. Version your tool schemas and provide migration paths.
Backward Compatibility
Prefer additive changes that maintain backward compatibility. Adding new optional parameters does not break existing callers. Removing parameters or changing parameter types does.
Deprecation Handling
When removing tools or changing schemas, support both old and new during a transition period. Log warnings when deprecated tools are used to identify callers that need updating.
Cross-References
For MCP integration of tool schemas, see Section 19.1 MCP as a Standard. For UI integration patterns for tool results, see Section 19.4 UI-Agent Integration Patterns.
Section Summary
Tool schemas define the contract between AI models and tools. A complete schema includes the tool name, description, parameter definitions, and response structure. Service boundaries determine where tool responsibility ends and model responsibility begins. Tools should handle data retrieval, external actions, complex computation, and validation. Models should handle interpretation, reasoning, and natural language generation. Schema design should follow the single responsibility principle, use specific types, and document limitations. Organize tools into catalogs with consistent naming and capability advertising to help models select appropriate tools.