Why does tool schema design matter?
When an agent uses tools, the schema is the only thing the model sees about what each tool does. It reasons entirely from the names, descriptions, and parameter definitions you provide — not from your implementation. If the schema is ambiguous, the model picks the wrong tool or passes malformed arguments, and no amount of prompt tuning fully compensates.
In practice, most "the agent is unreliable" problems trace back to the schema, not the model. Two tools with overlapping descriptions cause the model to guess between them. A parameter named data with no description forces the model to infer its meaning. An over-broad tool that does five things invites misuse. Treating the schema as a designed interface — not an afterthought — is one of the highest-leverage things you can do for agent reliability.
What makes a good tool schema?
- One clear job per tool. Narrow tools with unambiguous purposes are chosen correctly far more often than broad, multi-purpose ones.
- Descriptions written for the model. Each tool and parameter description should state when to use it and what it returns, in plain language.
- Typed, constrained parameters. Use enums, formats, and required/optional flags so invalid arguments are impossible to express, not just discouraged.
- Disjoint tools. If two tools could plausibly handle the same request, the model will sometimes pick the wrong one — merge or sharpen them.
- Predictable outputs. Return structured, consistent results so the agent can reason about them on the next turn.
How does schema design affect cost and latency?
Every tool definition is tokens in the context window on every call. A bloated tool set — dozens of verbose schemas — inflates cost and can degrade decision quality as the model weighs too many options. This is a practical argument for the orchestrator-specialist pattern: give each specialist only the few tools it needs, rather than exposing the entire catalogue to one agent.