What Is a Tool Schema? Defining Agent Capabilities Explained

Tool schemas are treated as plumbing and behave like documentation, which is why so many agent failures attributed to model capability are in fact description problems. The model is choosing reasonably from what it was told; it was told the wrong thing. This explainer covers what a schema must contain and how to write one that works. It complements what is an agent loop and how to build an mcp gateway, and reflects FISTA Solutions' approach in AI agents delivery.

What is in a tool schema?

A name, a description, a parameter specification with types and constraints, and a description of what is returned. In function-calling interfaces this is typically JSON Schema; in the Model Context Protocol it follows the same shape.

The model reads this and nothing else. It does not see the implementation, the documentation, or the intent behind the tool. Everything it knows comes from the schema.

Element	Drives	Common failure
Name	Recognition	Cryptic abbreviations
Description	Selection	Vague, no negative case
Parameter types	Call validity	Free strings where enums fit
Required vs optional	Completeness	Everything marked required
Return description	Downstream use	Undocumented shape
Error contract	Recovery behaviour	Unstructured strings

Why is the description decisive?

Because selection happens on it. When an agent must choose among several tools, the description is the entire basis for the decision, and two tools with similar vague descriptions will be confused consistently.

Most tool selection problems dissolve when the descriptions are rewritten to distinguish the tools clearly. That is a cheaper intervention than changing models and is almost always tried too late.

What makes a description good?

Four things in order: what it does, when to use it, when not to use it, and what it returns. Concretely, with examples of the situations it suits.

The negative case matters most and appears least. "Use this to look up a customer by their account identifier. Do not use it to search by name — use customer_search for that" resolves an ambiguity that no amount of positive description would.

How should parameters be designed?

Constrained. An enumeration prevents an invalid value being passed at all. An explicit date format prevents ambiguity between conventions. Marking genuinely optional parameters as optional prevents the model inventing values to satisfy a requirement.

Every constraint expressed in the schema is a class of malformed call eliminated before it happens, which is cheaper than validating and retrying.

Why do errors belong in the contract?

Because the agent's next action depends on what the failure means. Record not found means try different parameters or report absence. Permission denied means stop and escalate. Rate limited means wait and retry. Invalid parameter means correct and retry.

An unstructured error string forces the model to guess between these, and it guesses wrong in ways that produce retry loops or silent abandonment. Structured, documented errors are among the highest-value additions to any tool interface.

How many tools should an agent have?

Fewer than teams expect. Selection accuracy degrades as the set grows, especially where purposes overlap, and every schema consumes context on every call.

Beyond roughly a dozen, grouping tools by task and exposing only the relevant subset performs better than presenting everything. This also reduces context cost proportionally, which matters on high-volume workloads.

What about return shapes?

Document them, and keep them small. A tool returning a deeply nested object with forty fields consumes context and buries the two fields that matter. Filtering the response to what the agent actually needs is application work and one of the most effective context optimisations available.

What should you do first?

Take a sample of wrong tool calls from your logs and read the schemas the model was working from. In most cases the mistake is explicable — two descriptions that do not distinguish the tools, a free-text parameter that invited an invalid value, an error string that gave no basis for recovery. Fixing the schema is faster than anything else you could do.

How do schemas relate to security?

Closely, and not sufficiently. A schema describes what a tool accepts; it does not decide whether this caller may invoke it on this record. Authorisation belongs in the tool's implementation, checked against the acting identity, because a model can be persuaded to call anything its schema permits.

Schemas do contribute to safety by narrowing what is expressible. A tool whose parameters cannot express an unbounded query is harder to misuse than one taking arbitrary SQL, and that constraint is worth designing for even when authorisation is also enforced.

What changes with shared tool servers?

When tools come from a shared server rather than from application code, their descriptions arrive from elsewhere and may change without notice. That makes schema review part of onboarding a server, and schema change detection part of operating one, because a redefined tool description alters agent behaviour with no change on your side.

How FISTA Solutions helps

FISTA Solutions writes tool descriptions that state the negative case, constrains parameters with enumerations and formats, documents structured actionable errors, filters return shapes to what agents need, and keeps exposed tool sets small and task-scoped, through AI agents, AI enablement, and forward deployed engineers. The record behind the approach is 150+ projects for 50+ companies with 99.9% uptime.

To fix tool selection problems at their actual cause, message FISTA on WhatsApp, or read what is an agent loop.