Claude Structured Outputs: JSON Schemas and Strict Tool Use

1.Why prompting alone is not enough

Any code that consumes Claude's output has to parse it. If you only ask for JSON in the prompt, you are relying on the model to follow that instruction every time. The structured outputs documentation lists what goes wrong "even with careful prompting": parsing errors from invalid JSON syntax, missing required fields, inconsistent data types, and schema violations that you then have to catch and retry.

Structured outputs deal with this at generation time. The feature has two parts, and you can use them separately or in the same request. JSON outputs (output_config.format) control the format of Claude's own response. Strict tool use (strict: true) makes tool names and tool inputs match your schema. The documentation sums up the result as "always valid", "type safe" and "no retries needed for schema violations."

Sources1

2.JSON outputs with output_config.format

Setting it up takes three steps. Define a JSON Schema, add output_config.format with type: "json_schema" and that schema, then parse the response. The JSON comes back in the response's text content block, not in a separate field. The schema uses standard JSON Schema, but only a subset of it is supported.

You usually don't write the raw schema yourself. The SDKs build it from native types: Pydantic in Python, Zod or typed JSON Schema literals in TypeScript, plain classes in Java and C#, and so on. In Python, the recommended entry point is client.messages.parse(), which returns a typed parsed_output.

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, john@example.com, interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# Access the parsed output directly
contact = response.parsed_output
print(contact.name, contact.email)

The helpers also rewrite your schema before sending it. They remove constraints that constrained decoding does not support, such as minimum, maximum, minLength and maxLength. They move each removed constraint into the field description (for example, "Must be at least 100"), add additionalProperties: false to every object, and keep only supported string formats. Then they validate the response against your original schema, constraints included. Claude sees a simplified schema, and your code still enforces the rest. If you need to edit the transformed schema by hand, transform_schema() gives it to you so you can pass it through output_config yourself.

The Agent SDK has the same pattern. You pass outputFormat / output_format with a JSON schema, and the final result message carries a structured_output field. The error handling shown in its examples is worth copying: a single-shot query() raises after it yields an error result such as error_max_structured_output_retries, so wrap it in try and don't assume a validated object always comes back.

Sources12

3.Strict tool use for agent tool calls

In an agent, tool inputs are output too, and your functions run on them directly. Without strict mode, the model can pass the wrong type or leave out a required field. The documentation's booking example: a function that expects passengers: int might get "two" or "2". With strict: true it always gets passengers: 2.

You enable it with a top-level "strict": true next to name, description and input_schema. That gives two guarantees: the tool input follows input_schema, and the tool name is always valid (one of the tools you provided or a server tool). The input arrives in response.content[x].input of a tool_use block:

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

Three constraints to know. First, the computer use and browser use toolset entries do not accept strict: true, and a request that sets it on them is rejected. Second, strict schemas are compiled into grammars and cached for up to 24 hours after last use, apart from message content. Strict tool use is HIPAA eligible, but because of that separate cache, PHI must stay out of property names, enum values, const values and patterns, and appear only in messages. Third, strict mode uses the same schema subset as JSON outputs.

Sources3

4.Choosing between the two

Sources1

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Constrained decoding enforces every constraint in your Pydantic model, including minimum, maximum and length limits.Why is that wrong?

   The SDK removes unsupported constraints before sending the schema and enforces them afterwards by validating the response against the original schema. That check happens in your code, not during decoding.

   Covered in JSON outputs with output_config.format

2. 2.strict: true can be added to any tool in the tools array, including the computer use and browser use toolsets.Why is that wrong?

   Those toolset entries do not accept strict mode, and a request that sets it on them is rejected.

   Covered in Strict tool use for agent tool calls