NOTES / PROMPTING AND CONTEXT ENGINEERING
Structured outputs
Getting machine-readable answers: constrain the response to a JSON schema, validate in code, and retry with the error when it fails.
Why bother
Downstream code needs data it can parse, not prose. Asking nicely for JSON usually works and sometimes does not; one stray sentence or missing field breaks the pipeline. Structured outputs move the guarantee from the prompt into the API.
Diagram: my own.
What the API offers
Anthropic’s documentation describes two complementary features. JSON outputs constrain Claude’s text response to a JSON schema you supply, set through output_config.format, for jobs such as extracting data from text or images, generating structured reports, or formatting API responses. Strict tool use guarantees valid tool parameters1. They can be used independently or together in one request, so an agent can call tools with valid parameters and also return a structured final answer1.
You describe the structure as a JSON schema, or as a type in your language that the SDK converts. The schema follows JSON Schema with some documented limitations, so check the current limits before designing something elaborate1. Other cloud platforms that host Claude also document the feature, so check your platform’s support.
Guaranteed shape is not guaranteed truth
A schema ensures the response parses and has the right fields and types. It cannot ensure the values are correct. A model can return a perfectly valid object containing a wrong date or an invented ID. So:
- Validate semantics in code. Check ranges, enums, cross-field rules and, where possible, that IDs exist.
- Retry with the error. On failure, return the validation message to the model and try again a bounded number of times, then escalate. See Error handling and recovery.
- Log failures. Failure rates are a useful monitoring signal.
Diagram: my own.
Design tips
- Keep schemas small and flat. Fewer optional branches means fewer chances for odd outputs. Reasoning from experience, not from the docs.
- Name fields clearly and describe them. Field names and descriptions are part of the prompt.
- Allow an explicit “unknown”. Offer a null or a status field so the model is not forced to invent a value. This ties to hallucination.
- Put reasoning before the answer when you need it. Let the model think first, or include a short reasoning field ahead of the verdict; see Reasoning models.
- If you cannot use the feature, Anthropic’s guide also describes steering format with tagged sections in the prompt, though that carries no guarantee2.
Sources
- [1]Structured outputs — Anthropic, Claude Platform docsPARAPHRASED
- [2]Prompting best practices — Anthropic, Claude Platform docsPARAPHRASED