# Structured Output

> 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".

- Skill: `zavelinski/structured-output` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zavelinski/structured-output`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zavelinski/structured-output/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zavelinski (https://skillmd.com/u/zavelinski)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zavelinski/structured-output

---


# 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

1. **Define the schema first:** the exact fields, types, required vs optional, allowed enums. Keep it minimal, only what the consumer needs.
2. **Emit only the structure:** no prose around it, no markdown fences if the consumer wants raw JSON.
3. **Validate before use:** parse + check against the schema. On mismatch, do not "best-effort" it, regenerate to conform or surface the error.
4. **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.