Learn · Prompt engineering & structured output · CCAR-F task 4.3

Structured output with schemas and tools

Get guaranteed JSON with structured outputs or a tool schema, design it with nullable fields and 'other' enums, and remember: shape is not truth.

Key ideas

• Two routes to guaranteed structure: structured outputs (output_config.format with json_schema) or a tool whose input_schema is your shape, with strict: true.
• Make fields nullable when data may be missing, or the model is pushed to invent a value.
• Give enums an "other" / "unclear" value plus a free-text detail field.
• Put normalisation rules (date format, units) in the prompt next to the schema.
• tool_choice: auto may return text; any guarantees some tool; a named tool forces that tool.
• Schemas remove syntax errors, not semantic ones. Validate the values in code.

Worked example: One tool per document type

When you don't know whether a document is an invoice, receipt or contract, define one extraction tool for each and set tool_choice to any: Claude must call one of them, and which one it picks tells you the type.

Exam traps

• Thinking a valid schema means correct data. Totals can still be wrong and values can land in the wrong field.
• Making every field a required string, which forces invented values for missing data.
• Using numeric or length bounds (minimum, maxLength) or recursive schemas; structured outputs don't support them, and can't be combined with citations.
• Newer-model note: on Opus 5.5, Sonnet 5.5 and Fable 5.x, forced any/tool returns a 400 error, so the docs suggest auto + strict or structured outputs. Answer the exam in the guide's terms.

Official docs

• Structured outputs
• Define tools

Practise CCAR-F questions · Next lesson: Validation, retry and feedback loops