What you will be able to do
- Choose between required, optional and nullable fields so the model is not pushed into inventing values
- Design enum categories with an 'other' escape route and a way to express ambiguity
- Explain why a schema-valid extraction can still be semantically wrong, and where that gets checked
- Combine format rules in the prompt, in field descriptions and in input_examples with a strict schema
1.Required, optional and nullable fields
Every property in an extraction schema raises a design question: must this value always be present? In the standard get_weather definition, location is listed in required and unit is not, which makes unit optional.
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
}
},
"required": ["location"]
}
}For extraction, this choice carries more weight than it seems to. Strict tool use compiles the schema into a grammar, so a required field always shows up in the output. If the source document doesn't contain that information, Claude still has to fill the slot with something. Whatever goes there looks like a real value but has no basis in the document.
The Anthropic content-moderation cookbook builds its schema with nulls deliberately allowed. It types apr_disclosed as boolean | null because "couldn't tell" is a legitimate answer, and its rule engine treats null differently from false. Anthropic's prompting guide does the same in prompt form, telling the model to use null when a metric isn't clearly stated rather than guess. In practice: make a field optional or nullable whenever the source might not contain it, so leaving it empty is a valid answer that fits the schema.
Checkpoint 1 of 5· Check yourself
Invoices sometimes omit a purchase-order number. The schema lists po_number as a required string with strict: true. What is the main risk?
Strict mode guarantees that required fields appear, so the slot always gets filled. Making the field nullable lets the model honestly report that the value is absent.
“Fields can be null on purpose.”Source: platform.claude.com
2.Enums with 'other', a detail field, and room for ambiguity
An enum limits a field to a fixed list, like unit in the schema above. Under strict mode that limit is absolute: the tool input follows the schema exactly, so nothing outside the list can appear. That's useful for a downstream switch statement. The cost is that a document which fits none of the listed categories gets pushed into the closest wrong one.
The fix is to add an exit. The moderation cookbook's ad_category enum lists alcohol, gambling, financial_services and the other expected categories, and its last value is other. The exam guide's pattern goes one step further: pair other with a free-text detail string, such as an optional category_detail field, so the real category is kept rather than lost. The sources show the other value but don't spell out the detail-field pairing, so treat the field name here as illustrative.
Ambiguity is a different case from 'none of the above'. The exam guide recommends an explicit value such as unclear for documents that could fit more than one category. The sources here don't name that value. They do describe the underlying problem: in the moderation cookbook, a borderline post was sometimes tagged one way and sometimes the other, and the authors concluded the extraction wasn't wrong either way, because the schema had left the boundary fuzzy. Their fix was to sharpen the field description and re-run the evaluation. They also suggest watching null rates, since a rising rate of nulls on a field usually means its description needs work.
Checkpoint 2 of 5· Check yourself
A strict extraction tool has category: enum ["billing", "shipping", "returns"]. A ticket about a data-privacy request comes in. What does the schema force?
Strict mode limits output to the values the schema allows, so a closed enum has no honest answer for an unexpected category. An 'other' value plus a detail field gives it one.
“Tool input strictly follows the input_schema”Source: platform.claude.com
3.What a strict schema cannot catch
Constrained decoding removes a whole class of failures: invalid JSON syntax, missing required fields, and wrong types. Anthropic's 'no need to validate and retry' claim is about schema violations. It doesn't cover meaning. The documentation's guarantees are stated in terms of conformance to the schema. The sources don't discuss semantic errors such as line items that don't sum to the total, or a value placed in the wrong field. Those errors still fit the schema, so no grammar can stop them, and they have to be caught by checks you write.
The structured outputs SDK shows a related point. Before sending a schema, the helpers remove constraints the grammar can't enforce, such as minimum and maximum. Helpers that validate then check the response against the full original schema in your code. Value-level rules are your application's job.
| Error | Example | Prevented by strict schema? |
|---|---|---|
| JSON syntax | Missing brace, trailing text | Yes. Sampling is restricted to schema-valid output |
| Type mismatch | passengers: "2" instead of 2 | Yes |
| Missing required field | No location key | Yes |
| Semantic inconsistency | Line items do not sum to the total; a value in the wrong field | No. Needs validation in your code |
Checkpoint 3 of 5· Match them up
Match each failure to the layer that handles it
Tap a term, then the definition that fits it.
Constrained decoding removes syntax errors. SDK helpers strip constraints like minimum before sending and then enforce them in code. Business rules such as sums are entirely up to your application.
“Validate responses against your original schema and all its constraints, if the helper validates responses”Source: platform.claude.com
4.Format rules in the prompt, alongside the schema
Source documents are messy. The same date can show up in three formats from three senders. A strict schema says what the output must look like. It doesn't tell Claude how to turn a messy input into that shape. The tool-choice cookbook says that even when you force an extraction tool, you should still write a proper prompt. There are three places to put normalization rules.
Field descriptions. The get_weather example's description for location gives the expected form: "The city and state, e.g. San Francisco, CA".
Prompt instructions. Anthropic's prompt-engineering guide pairs a JSON structure with format notes for each field, such as "value with units" and "percentage", plus a rule for missing values.
input_examples. Concrete example inputs, each of which must be valid against the schema, show Claude which formats to use.
"input_examples": [
{"location": "San Francisco, CA", "unit": "fahrenheit"},
{"location": "Tokyo, Japan", "unit": "celsius"},
{
"location": "New York, NY" # 'unit' is optional
},
],So when extractions keep failing because source formats don't match the schema, the fix is to tell Claude how to normalize: state the target format and how to convert each variant you've seen, in the prompt or the field description, and back it up with examples. Loosening the schema or dropping it would throw away the guarantee you added it for. Each example adds prompt tokens: roughly 20–50 for a simple one and 100–200 for a complex nested one.
Checkpoint 4 of 5· Exam question
A pipeline first needs Claude to run extract_metadata on an uploaded document before any enrichment or summarization steps proceed. Other tools such as translate_text and summarize_document are also registered on the same request, and the team is worried Claude might call one of those first. Which tool_choice setting guarantees extract_metadata runs on this turn?
Correct answer: A — tool_choice: {"type": "tool", "name": "extract_metadata"}
- A. Correct. Forcing a specific named tool guarantees that exact tool is called on this turn, ensuring extract_metadata runs before any other registered tool such as translate_text or summarize_document.
- B. "any" only guarantees that some tool is called; Claude could still pick translate_text or summarize_document instead of extract_metadata.
- C. "auto" lets Claude decide freely whether to call a tool at all and which one, so it does not guarantee extract_metadata runs first.
- D. "none" prevents Claude from calling any tool at all, which would block extract_metadata from running rather than force it.
Checkpoint 5 of 5· Check yourself
Which tool-definition feature does the documentation say helps Claude learn what formats to use and when to include optional parameters?
input_examples are added to the prompt next to the schema and show concrete, well-formed calls, including formats and when optional fields are present.
“This helps Claude understand when to include optional parameters, what formats to use, and how to structure complex inputs.”Source: platform.claude.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Marking every field required makes extraction more complete and therefore more accurate.Why is that wrong?
Under strict mode, a required field always gets filled, even when the source lacks the information. Nullable or optional fields let the model say 'not present' instead of inventing a value.
Covered in Required, optional and nullable fields
2.Since strict mode means 'no need to validate and retry', schema-valid extractions can go straight to downstream systems.Why is that wrong?
The guarantee covers conformance to the schema: syntax, types and required fields. Semantic problems such as totals that don't reconcile still fit the schema and need your own validation.
Covered in What a strict schema cannot catch
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“expects an input object with a required location string and an optional unit string that must be either "celsius" or "fahrenheit".”
↩︎ Required, optional and nullable fields“Each example must be valid according to the tool's input_schema”
↩︎ Format rules in the prompt, alongside the schema“This helps Claude understand when to include optional parameters, what formats to use, and how to structure complex inputs.”
↩︎ Checkpoint - 2.
“Strict tool use compiles tool input_schema definitions into grammars using the same pipeline as structured outputs.”
↩︎ Required, optional and nullable fields“Tool input strictly follows the input_schema”
↩︎ Enums with 'other', a detail field, and room for ambiguity“No need to validate and retry tool calls”
↩︎ What a strict schema cannot catch“Tool input strictly follows the input_schema”
↩︎ Prediction - 3.
“"couldn't tell" is a legitimate answer”
↩︎ Required, optional and nullable fields“electronics, food_beverage, other]”
↩︎ Enums with 'other', a detail field, and room for ambiguity“The extraction isn't wrong either way; the schema left the boundary fuzzy.”
↩︎ Enums with 'other', a detail field, and room for ambiguity“rising nulls on a field usually mean the description needs work”
↩︎ Enums with 'other', a detail field, and room for ambiguity“Fields can be null on purpose.”
↩︎ Checkpoint - 4.
“Always valid: No more JSON.parse() errors”
↩︎ What a strict schema cannot catch“Remove unsupported constraints (for example, minimum, maximum, minLength, maxLength)”
↩︎ Exam trap 2“Validate responses against your original schema and all its constraints, if the helper validates responses”
↩︎ Checkpoint - 5.https://platform.claude.com/cookbook/tool-use-tool-choiceSecondary source
“Even though we're forcing Claude to call our print_sentiment_scores tool, we should still employ some basic prompt engineering”
↩︎ Format rules in the prompt, alongside the schema - 6.https://claude.com/blog/best-practices-for-prompt-engineeringSecondary source
“Permission to express uncertainty (use null if unsure)”
↩︎ Format rules in the prompt, alongside the schema“If any metric is not clearly stated in the report, use null rather than guessing.”
↩︎ Exam trap 1