{"post":{"slug":"tool-schema-design-2026","title":"Tool Schema Design: The Interface a Model Has to Read","excerpt":"A tool definition is documentation for a reader that cannot ask questions. Most tool-calling failures are schema problems, not model problems.","category":"ai","date":"February 6, 2026","author":"ByteLedger Team","content":"<span class=\"dropcap\">W</span>hen an agent calls the wrong tool, or calls the right tool with wrong arguments, the instinct is to blame the model. Usually the schema is at fault. The model read a description that did not distinguish this tool from three others, and filled a free-form string field that accepted anything.\n\nA tool definition is documentation written for a reader with no ability to ask a clarifying question, no access to your codebase, and one attempt. That framing changes how you write it.\n\n## What changed in 2026\n\n- **Strict schema enforcement became available.** Constrained decoding against the schema removed malformed-argument errors, which shifted the remaining failures to selection and semantics.\n- **Tool sprawl made descriptions matter more.** With many tools attached, disambiguation became the dominant quality factor — see [tool search and deferred loading](/blog/tool-search-and-deferred-loading-2026).\n- **Description writing became a discipline.** Teams began iterating on tool text the way they iterate on prompts, with evaluation.\n- **Model-facing design displaced API mirroring.** Wrapping internal APIs in purpose-built tool interfaces became standard practice.\n\n## Descriptions do the selection\n\nThe name gets a glance. The description decides.\n\nThe most valuable sentence in a tool description is frequently the one saying when *not* to use it. A description covering only capability leaves the model to infer boundaries, and it infers generously.\n\nWeak: *\"Searches documents.\"*\n\nStrong: *\"Searches internal policy documents. Use for questions about company procedures, benefits, or compliance. Do not use for customer data, product documentation, or anything requiring current external information.\"*\n\nThe second tells the model where the boundary is, which is exactly the information that prevents a wrong selection. It costs thirty tokens and eliminates a class of error.\n\nWhen two tools could plausibly serve the same request, say so in both descriptions. *\"For internal documents use this; for public web content use `web_search`.\"* Cross-referencing removes ambiguity in a way that neither description alone can.\n\n## Constrain the parameters\n\nEvery free-form field is a place the model can produce something your service rejects.\n\n| Instead of | Use | Why |\n| --- | --- | --- |\n| `status: string` | `status: enum[open, closed]` | Invalid values become impossible |\n| `date: string` | `date: string` with format stated | Removes format ambiguity |\n| `limit: number` | `limit: integer, min, max` | Prevents absurd values |\n| Ten optional fields | Three required, two optional | Fewer chances to err |\n| `filters: object` | Named specific parameters | Structure the model can fill |\n\nEnums are the highest-value change. A constrained set means the model cannot invent a value, and with strict schema enforcement it literally cannot emit an invalid one.\n\nWhere free text is genuinely necessary, state the format in the parameter description with an example. `\"date: ISO 8601 date, e.g. 2026-05-06\"` is unambiguous; `\"date: the date\"` is not.\n\nKeep the parameter count low. Every optional field is a decision the model has to make, and models fill optional fields more often than intended. If your tool has twelve parameters, it is probably two tools.\n\n## Design for the model, not your API\n\nThe common shortcut is to expose an internal endpoint directly as a tool. It rarely works well, because your API was designed for a client that reads documentation and has a developer behind it.\n\nPurpose-built tool interfaces do better. That usually means fewer parameters with sensible defaults applied server-side, combining several calls the model would otherwise have to chain, naming things for what they mean rather than for your internal schema, and returning results shaped for reading rather than for parsing.\n\nReturn values deserve as much thought as inputs. A tool returning a large JSON blob puts all of it into context permanently — see [ReAct agents](/blog/react-agents-explained-2026) for why that accumulates. Return what the model needs, not everything the endpoint produces.\n\n## Common mistakes\n\n- **Description of capability only.** No boundary, so wrong selections.\n- **Free-form strings where an enum fits.** Invented values.\n- **Overlapping descriptions across tools.** The model guesses.\n- **Too many parameters.** More chances to err; probably several tools.\n- **Mirroring the internal API.** Designed for a different reader.\n- **Verbose return values.** Fills context with what nobody needed.\n- **Never evaluating tool selection.** Wrong-tool errors are invisible without measurement.\n\n## FAQ\n\n**How long should a description be?**\nLong enough to state purpose, scope, and boundary — usually two or three sentences. Every tool description is in context on every request, so length has a real cost when there are many tools.\n\n**Should I include examples?**\nFor parameters with non-obvious format, yes, inline in the parameter description. A full usage example in the tool description is usually unnecessary and expensive.\n\n**How do I know if my schemas are the problem?**\nMeasure tool selection accuracy on a set of representative requests with known-correct tools. Wrong selections point at descriptions; wrong arguments point at parameter design — the same discipline as [LLM regression testing](/blog/llm-regression-testing-2026).\n\n**Does strict mode remove the need for good schemas?**\nIt guarantees valid *shape*, not correct *choice*. The model can still pick the wrong tool and fill valid-but-wrong values.\n\n## Where to go next\n\nFor errors when a call fails, read [agent tool error handling](/blog/agent-tool-error-handling-2026). For managing a large tool set, [tool search and deferred loading](/blog/tool-search-and-deferred-loading-2026), and for the reliability side, [tool calling reliability](/blog/tool-calling-reliability-2026).","hue":203,"metaTitle":"Tool Schema Design: The Interface a Model Reads","metaDescription":"How to write tool definitions AI models call correctly — descriptions that say when not to use a tool, enums over strings, and disambiguating similar tools.","keywords":["tool schema design","function calling schema","tool description llm","json schema tools","tool selection accuracy","agent tool interface","structured tool definitions","llm tool use 2026"],"tldr":["**The description does more work than the name** — say when to use the tool, and when not to.","**Enums beat free-form strings** — constrain what you can, and the model cannot invent an invalid value.","**Fewer parameters means fewer mistakes** — every optional field is another chance to get it wrong.","**Distinguish similar tools explicitly** — if two descriptions overlap, the model will pick wrongly.","**Skip:** exposing your internal API shape directly. Design the tool for the model, not for your service."],"readTime":"4 min read","wordCount":884},"related":[{"slug":"tool-calling-reliability-2026","title":"Tool Calling Reliability: Making the Model Pick Right","excerpt":"Models call the wrong tool, invent arguments, and loop. Most of that is fixable by changing the tools rather than the prompt. Here is what actually works.","category":"ai","date":"June 26, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":204},{"slug":"tool-use-in-llms-2026","title":"Tool Use in LLMs 2026: How Function Calling Actually Works","excerpt":"Tool use lets a language model call external functions instead of just generating text. Here is how the mechanism works, what breaks in practice, and how to design tools that models actually use correctly.","category":"ai","date":"July 3, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":260},{"slug":"json-mode-vs-tool-calling-2026","title":"JSON Mode vs Tool Calling: Which One You Actually Want","excerpt":"Both produce structured output and they solve different problems. Here is when to use each, why mixing them causes trouble, and how reliability differs.","category":"ai","date":"June 26, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":210}],"sameCategory":[{"slug":"agent-cost-attribution-2026","title":"Agent Cost Attribution: Finding Where the Tokens Went","excerpt":"A single monthly API bill tells you that agents are expensive. It does not tell you which feature, which customer, or which retry loop is responsible. That gap is fixable.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":220},{"slug":"human-in-the-loop-agents-2026","title":"Human-in-the-Loop Agents: Where to Put the Approval Gate","excerpt":"Approve everything and the agent is a slow autocomplete. Approve nothing and you have handed irreversible actions to a system that can be talked into things.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":197},{"slug":"reasoning-effort-controls-2026","title":"Reasoning Effort Controls: Tuning How Hard a Model Thinks","excerpt":"Fixed thinking budgets gave way to effort levels, and the default is rarely the right setting. Here is how the dial behaves and where each level actually belongs.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":210},{"slug":"retrieval-metrics-explained-2026","title":"Retrieval Metrics: Measuring the Half of RAG That Fails","excerpt":"When a RAG system answers badly, the retrieval usually failed before the model ever spoke. Measuring generation quality alone hides that entirely.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":215}],"newer":{"slug":"svelte-5-vs-react-19-2026","title":"Svelte 5 vs React 19 in 2026: runes vs RSC, perf, ecosystem","excerpt":"Svelte 5 runes and React 19 server components changed both frameworks significantly. Here is the honest 2026 comparison — performance, mental model, ecosystem.","category":"code","date":"February 6, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":168},"older":{"slug":"wifi-7-router-buying-guide-2026","title":"WiFi 7 router buying guide for 2026: real-world speeds and when MLO matters","excerpt":"WiFi 7 routers dropped to $200 in 2026. Here's whether you actually need one, the real-world speed gains, and which models are worth the upgrade.","category":"tech","date":"February 6, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":235}}