Tool Schema Design — Naming, Descriptions, Parameter Constraints
A correct tool fails silently when the model cannot tell when to use it. Naming, descriptions, and parameter shapes drive 10 to 20 percentage-point swings in tool-selection accuracy on benchmarks like StableToolBench and MCPToolBench++. This lesson names the design rules that separate a tool a model picks reliably from a tool a model mis-fires. Write a tool description using the "Use when X. Do not use for Y." pattern, under 1024 characters. Name tools in a way that is stable, snakecase, and unambiguous across a large registry. Choose between atomic tools and a single monolithic tool for a given task surface. Run a tool-schema linter against a registry and fix the findings. Imagine an agent with 30 tools. Every user query triggers tool selection: the model reads every description and picks one. Two shapes of failure show up. Wrong tool picked. The model chooses searchcontacts when it should have chosen getcustomerdetails. Cause: both descriptions say "look up people". The model has no way to disambiguate. No tool picked when one fits. The user asks for a stock price; the model replies with a plausible but hallucinated number. Cause: the description says "retrieve financial data" but the model did not map "stock price" to that. Composio's 2025 field guide measured 10 to 20 percentage-point accuracy swings on internal benchmarks purely from…
Tool Schema Design — Naming, Descriptions, Parameter Constraints: A correct tool fails silently when the model cannot tell when to use it. Naming,…
This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.
Browse the complete course catalog or open this lesson on GitHub.