AI Agent Tool Schemas: How to Design Functions Models Can Use Reliably
A tool schema is an API contract between an agent and your application. Good schemas reduce ambiguity, invalid calls, and unsafe assumptions.
A tool schema is an API contract between an agent and your application. Good schemas reduce ambiguity, invalid calls, and unsafe assumptions.
Design tool inputs like production APIs: explicit, narrow, validated, and difficult to misuse.
A tool schema is more than documentation. It is the contract between an AI agent and the software that will execute the agent's decisions.
If the contract is vague, the model has more room to guess. That creates invalid arguments, unnecessary retries, ambiguous intent, and dangerous edge cases.
Prefer a tool such as get_invoice_status over a generic database_query tool.
A narrow tool tells the model exactly what capability exists. It also gives the application a natural place to enforce authorization and validation.
Required fields should be required. Enumerated values should use enums. Numeric values should have sensible limits. Dates should have a defined format.
Avoid descriptions such as "provide the appropriate identifier." Tell the model exactly which identifier is expected and where it comes from.
A business tool should represent an operation the product understands.
For example:
create_support_ticket
is easier to reason about than:
send_http_request
The first exposes intent. The second exposes infrastructure.
Tool schemas should also define what the model receives after execution.
Return the minimum useful data. A customer lookup may only need status, plan, and renewal date. Returning the complete database record creates unnecessary context and privacy exposure.
A schema should make impossible or unsafe combinations difficult to express.
If a tool supports three modes, use an enum. If one field is required only for one mode, validate that relationship server-side.
The model should not have to infer hidden business rules from prose.
Changing a tool argument can break existing agent prompts, cached plans, tests, and workflows.
Prefer explicit versions for important tools and monitor which agent versions are using each schema.
A good tool schema reduces the number of decisions the model has to guess.
Keep tools narrow, inputs explicit, outputs minimal, and business rules enforceable outside the model.
Source: AI Agent tool-use and API design principles.
The tool execution layer should remain responsible for authentication, authorization, validation, rate limits, retries, timeouts, and logging. The model should receive a narrow interface and a sanitized result rather than direct access to infrastructure. This separation lets engineers change providers without changing the agent's conceptual capability.
Before shipping a tool, test normal inputs, malformed arguments, unauthorized resources, provider failures, duplicate requests, slow responses, and cancellation. For side-effecting tools, verify that retries cannot create unintended duplicates. For read tools, verify that returned data contains only what the agent needs.
Keep the tool contract versioned when it becomes important to production workflows. Changes to argument names, required fields, enum values, or output shape can affect prompts and orchestration logic. Treat those changes like API changes rather than casual prompt edits.
Reliable tool calling is mostly good software engineering around an unreliable model. Give the model clear capabilities, then put deterministic controls around execution. The result is an agent that can recover from ordinary failures without turning every failure into another guess.
A production tool layer should be deliberately boring. The model chooses from a documented capability set, while deterministic application code handles the parts that must not depend on model behavior. Validate the request, authenticate the caller, check authorization, validate resource ownership, apply rate and cost limits, execute with a deadline, and return a sanitized result.
Keep tool execution separate from the prompt layer. This makes it possible to change the model without changing the security boundary. It also gives engineers one place to add logging, metrics, retries, circuit breakers, and provider-specific behavior.
Test more than a successful request. Simulate malformed arguments, missing fields, unauthorized resources, expired sessions, rate limits, provider outages, slow responses, duplicate requests, partial responses, and cancellation. For side effects, deliberately create the condition where the provider succeeds but the response is lost. The application should recover without creating a second side effect.
For parallel workflows, test dependency races and partial completion. If three tools run concurrently and one fails, define whether the workflow can continue, whether completed operations should be compensated, and what the model should be told.
Record a workflow ID and tool-call ID for every execution. Useful fields include agent identity, tool version, operation, resource, authorization result, latency, retry count, error category, and final outcome. Do not place secrets or unnecessary customer data into the model-facing result or logs.
Metrics should distinguish model errors from tool errors. A spike in invalid arguments suggests a schema or prompt problem. A spike in timeouts suggests an infrastructure problem. A spike in permission denials may indicate a product workflow problem or an attempted abuse pattern.
Treat important tool schemas like APIs. When a required argument changes, version the contract or provide a compatibility layer. Roll out significant changes gradually and monitor error rates before removing the previous version.
Keep production and development tools separate. A test agent should not accidentally discover a production endpoint merely because the tool registry is shared.
The model is an untrusted decision-maker. The tool executor is the trusted enforcement layer. This distinction should remain true even if the model is highly capable. Prompts can explain policy, but only application code should enforce permissions, resource scope, validation, and side-effect controls.
Reliable tool calling comes from combining a clear interface with deterministic execution controls. Give the model enough capability to complete the task, but keep the actual authority in code that can validate, limit, observe, and stop every operation.
Before production, create automated cases for valid and invalid schemas, missing required fields, unknown enum values, oversized inputs, unauthorized resources, provider failures, repeated requests, and slow dependencies. Verify that the tool returns a stable error category and that the workflow does not accidentally retry a non-retryable failure.
For side-effecting operations, run the same request twice and verify the business result remains correct. For concurrent operations, verify that independent calls can run together while dependent calls preserve their required order. For cancellation, confirm that an aborted workflow does not leave an uncontrolled background operation running.
These tests should run in CI because tool contracts change as the product evolves. A tool is part of the agent's public behavior even when it is technically an internal function.
Community
0 comments
React to this article
Trending now
Written by
Kirtesh Admute
Founder
Kirtesh Admute is the founder of IndieFounder, a platform for founders, builders, and people curious about technology. He writes about AI, startups, software, product building, and the lessons that come from building in public.
See an issue with this story?
