references/structured-outputs.md

# LLM interfaces and structured output
Prefer schema-controlled outputs for machine consumption. Give the model only fields necessary for the next action; validate the output in deterministic code. Define `status`, payload, optional warnings, and typed recoverable/fatal errors. Unknown schema versions are rejected or explicitly migrated.

Structured output isn't proof of factual correctness. For generated plans, separately verify claims against known sources, authorizations and the external system of record. Avoid parsing open-ended JSON from prose or silently repairing invalid output for consequential tool calls. Implement response-size limits, malformed-output handling, and allowed enum checks. Version and test the schema.

For model selection and schema guarantees, consult current primary vendor docs and installed versions. Never hardcode unsupported model capabilities or prices. Evaluate quality, invalid-output rate, refusal handling, latency and cost using labeled fixtures.