## Definition **Tool schema is the prompt** is the principle that a tool's `name`, `description`, and JSON parameter schema are the only information the model has about that tool — they function as prompt engineering, not documentation. A vague or ambiguous schema produces the same class of failure as a vague user prompt: wrong-tool selection, missing arguments, or semantically incorrect values. ## The Authoring Heuristic Write a tool definition by asking: "Would an LLM, reading only this description and schema, know exactly when to call this tool, what to pass, and what to expect back?" If the answer is no, the schema is the bug — not the model. Concretely, for each tool: - **Name**: use a verb-noun pair that uniquely identifies the action (`get_weather`, not `weather`). - **Description**: state the *when* (triggering condition), the *what* (what the tool does), and any *constraints* (rate limits, data freshness, scope). Avoid restating the parameter names — the schema handles that. - **Parameters**: name fields precisely; add `description` fields for every parameter; enumerate valid values in an `enum` where applicable; mark every required field explicitly. ## Failure Modes from a Vague Schema | Schema defect | Resulting failure | |---|---| | Ambiguous tool name or description | Model calls the wrong tool entirely | | Missing parameter description | Model invents plausible but wrong values | | No enum for constrained values | Model fabricates an out-of-range option | | Two tools with overlapping descriptions | Non-deterministic tool selection across runs | The [[Agent Failure Modes]] taxonomy labels these tool-use failures as the dominant failure category in agentic systems. ## Relationship to [[Function Calling]] [[Function Calling]] defines the contract (model proposes → host executes). This note addresses the *design* side: how to write the schema so the proposal is correct. The distinction matters because fixing a wrong-tool call at runtime is expensive — it costs at minimum one extra turn and one extra tool-result in context; a well-designed schema prevents it for free. ## Lean Tool Inventory The schema-as-prompt principle also implies: every tool in the inventory is read by the model on every turn. Unnecessary tools consume context and introduce ambiguity. Remove a tool if its absence causes no measurable performance drop. The discipline is an ablation, not a collection. ## Related - [[Function Calling]] - [[Tool Use]] - [[Tool Taxonomy]] - [[Agent Failure Modes]] - [[Structured Outputs]] ## Sources - [[Modern AI Software Engineering - The Orchestrators Playbook]]