Machine-Checkable Tool Contract

Problem

A constraint stated only in prose is enforced by nobody. The schema validator does not see it, the server often does not check it, and the model reads it as a suggestion among many. A call that violates such a constraint is not rejected: it runs, matches nothing, and returns a well-formed empty result with a success status. The caller has no field to branch on, cannot distinguish a query that legitimately matched nothing from one the server never understood, and so reports the empty result as a finding.

Solution

Treat the tool description as a contract with two obligations. On the way in, every constraint that determines whether a call can succeed is declared in the machine-readable schema — enumerations for closed value sets, patterns for formats, ranges for servable bounds — so an unsatisfiable call is rejected at validation time instead of running and returning nothing. On the way out, a failure is not a boolean flag but a structured result: a specific cause, the parameter or resource at fault, an executable repair where one exists, and whether replaying the call is safe. The caller then branches mechanically on the failure kind, fixing an argument, authenticating, backing off, or choosing another tool, rather than inferring intent from a prose message. Prose keeps the nuance a schema cannot hold, but it stops being the only record of anything load-bearing.

When to use

• A tool is exposed to agent callers rather than to human developers who can read a description page.
• Some calls are unsatisfiable in ways the transport layer reports as success, such as an empty result set.
• Callers need to choose between repairing an argument, authenticating, waiting, and switching tools without parsing prose.