Tool schemas are security boundaries, not developer documentation

Tool schemas are security boundaries, not developer documentation. They define the action language available to a probabilistic caller: which operations exist, which arguments can be expressed, what defaults fill missing intent, and which malformed requests reach execution. If that language is ambiguous or overpowered, the agent has already been granted unsafe authority before any policy engine sees the call.

Traditional API documentation explains a contract to a human developer who can inspect examples, read source, and correct a misunderstanding. An agent usually sees a compact name, description, and JSON schema inside a crowded context window. That representation is both documentation and executable affordance. A vague parameter such as user, an unconstrained string where an enum would do, or an optional destructive flag with a permissive default does not merely create poor developer experience. It expands the set of actions the model can accidentally formulate.

I therefore treat schema design as least-privilege design. Required and optional fields should reflect the minimum complete authorization story, not implementation convenience. Enumerations should close choices that the model has no reason to invent. Identifiers should name their scope precisely. Destructive, networked, or non-idempotent behavior should be visible in the contract rather than hidden behind prose or a generic “execute” tool. A schema-first tool factory with fail-closed defaults makes the permitted action space reviewable before code is reachable.

Validation must also happen at the execution boundary. Constrained generation improves syntax, but it does not prove that a resource exists, belongs to the tenant, falls inside the task’s write scope, or remains authorized now. Strict argument validation, existence checks, temporal permission checks, and a pre-execution tool-call gate turn the schema into an enforced boundary. This is why prompt injection is a permissions problem: an injected instruction becomes consequential only when the tool layer accepts and authorizes its expression.

Return schemas matter too. Tool output re-enters the model’s context and can carry untrusted content, excessive data, or instructions disguised as results. Typed envelopes that separate data, errors, provenance, and control metadata reduce that ambiguity. They also make sanitization and policy checks deterministic. The boundary is bidirectional — arguments constrain what the agent can do, while results constrain what external systems can say back to the agent.

Good schemas improve reliability and security for the same reason: they reduce interpretation. Tool design is API design under uncertainty, and security is the part of that uncertainty with a blast radius. Single-responsibility tools, explicit preconditions and effects, idempotency classes, and bounded response formats give evaluators something concrete to test. They also produce clearer audit records than a broad tool whose meaning changes according to a paragraph of instructions.

There is one precise concession: schemas cannot express every semantic or contextual policy, and forcing rich business rules into JSON Schema can produce a brittle, unreadable contract. Ownership, purpose, current risk, and cross-resource invariants still require authorization and domain validation behind the tool. The boundary claim is not that the schema replaces policy. It is that policy starts from the action language the schema permits, so a permissive schema makes every downstream defense work harder.

I review tool schemas the way I review public endpoints: what authority becomes expressible, which ambiguity becomes a default, what untrusted data crosses the boundary, and how failure closes. Structured outputs are integration contracts; tool schemas are the active half of the same seam. Calling them documentation understates their role. They are the grammar through which a stochastic system acquires effects.