Tool Schema

A tool is only usable by a model if the model can be told what it does, what it needs, and what it returns. The schema is that description, and it is the entire interface — the model never sees the implementation. Most tool-calling failures are schema failures: an ambiguous name, an unstated unit, a required field the description did not mention.

The description field does more work than the type signature does, because types constrain shape and prose constrains intent. Enumerations beat free strings wherever the set is known, and returning a structured error the model can read beats raising one it cannot. The schema is also the security boundary: anything the schema permits, a model that has been talked into it will eventually call.

The schema defines the space of syntactically valid calls; the model's job is choosing within it, and every unconstrained field multiplies that space. Constraining a parameter to an enumeration of k values replaces an unbounded string with a k-way choice, which is the difference between a decision the model can be evaluated on and one it can fail in unlimited ways.