| name | structured-output |
| description | When an answer will be consumed by code or another step (not a human), define a schema first and make the output conform to it, instead of free text you then regex. Use for tool arguments, API payloads, extraction/classification results, agent-to-agent handoffs. Trigger with /structured-output or "make this JSON", "constrain to a schema", "structured result". |
| version | 0.1.0 |
| user-invocable | true |
| metadata | {"emoji":"🧱"} |
structured-output
If a downstream step (code, a tool, another agent) will parse the answer, decide the shape FIRST and conform to it. Free-form text that you later regex is where parse errors and bad tool-args come from.
Why this exists (evidence)
- Malformed tool calls / wrong arguments are a leading cause of agent failure (~31% of production failures). A declared schema removes a whole class of these: missing fields, wrong types, prose where JSON was expected.
- Constrained / schema-guided decoding is the reliable fix: output that is validated against a schema is machine-consumable by construction, instead of "usually parseable".
When to use
- Tool / function arguments and API request bodies.
- Extraction & classification (pull fields from text -> typed object).
- Agent-to-agent handoffs in a Workflow (one stage's output is the next stage's input).
- NOT for human-facing prose; this is for machine-consumed output.
The method
- Define the schema first: the exact fields, types, required vs optional, allowed enums. Keep it minimal, only what the consumer needs.
- Emit only the structure: no prose around it, no markdown fences if the consumer wants raw JSON.
- Validate before use: parse + check against the schema. On mismatch, do not "best-effort" it, regenerate to conform or surface the error.
- Constrain when you can: in the API, pass a JSON schema / tool definition so the model is forced to the shape; in a Workflow, use the agent
schema option so output is validated and retried automatically.
How to run it
- API / SDK: define a tool or response JSON schema and let the platform enforce it.
- Workflow: pass a JSON Schema to
agent(prompt, { schema }), the runtime forces a structured tool call and validates, so the returned object is typed, no parsing.
- Extraction: give the target object shape up front; assert every required field is present and typed before acting.
Composes with
tool-guard: structured-output prevents bad args at generation time; tool-guard validates at call time. Belt and suspenders.orchestrate / multi-stage Workflows: typed handoffs between stages so stage N+1 never parses stage N's prose.
Honest limits
- A schema guarantees SHAPE, not correctness: a well-formed object can still hold wrong values. Pair with verification for the values that matter.
- Over-schematizing human-facing answers makes them robotic; scope to machine-consumed output.
