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.

structured-output

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.