Strict schemas

A schema tells Claude what shape you want. By default it's guidance, not a guarantee. Claude follows it very well, but now and then a flight-booking tool that needs passengers: 2 gets "2" or "two", or a required field goes missing. One bad call in a thousand is still a crash in production.

Add strict: true to a tool and the guidance becomes a rule. Claude's output is limited, token by token, to text that fits your schema, so the input you get always matches it. The technique is called grammar- constrained sampling.

Two things change in the schema. strict sits at the top level, next to name. And every object says additionalProperties: false, meaning “no fields except the ones listed”. Strict mode needs that.

It isn't free. The first request with a new schema waits a little while the API compiles it (the result is cached for 24 hours). There are limits per request: at most 20 strict tools, and 24 optional parameters across all of them. So save strict mode for the tools where a malformed call would really hurt.

Sometimes you don't want a tool call at all. You want Claude's answer as JSON: a list of extracted fields, a label, a summary in a fixed shape. That's structured outputs, and it uses the same machinery. Pass a schema in output_config.format and the reply's text is guaranteed to parse and match it.

The rule of thumb: strict tools control how Claude calls your code; structured outputs control what Claude says back. You can use both in one request. And the guarantee has edges: if a reply is cut off by max_tokens, or Claude declines, the JSON can still be incomplete. Check stop_reason before you parse.

Your turn. Without any of this, you're relying on the prompt. Ask Claude to turn “two adults, Friday, Lisbon” into JSON with passengers as a number, plus day and city. Run it a few times and check the type of passengers each time.