Enforce structured output using tool use and JSON schemas

Tool use is the schema enforcement mechanism

The reliable way to get structured output is not to ask for JSON in the prompt. Instead you define a tool whose input_schema is your output schema, let the model call it, and read the structured data out of the tool_use block.⁴⁷ Because the model emits tool input rather than free text, you get schema-compliant output and JSON syntax errors are eliminated: no markdown fences, no preamble, no trailing comma to repair. That is the guide's claim and the exam's answer. In the live API the guarantee is opt-in: you set strict: true on the tool definition and give the schema additionalProperties: false.⁴⁸ The API also ships a first-class path the guide does not cover: output_config.format returns validated JSON with no extraction tool. Read the reliable way as the way the exam tests. The extraction "tool" usually executes nothing on your side; its schema exists purely to constrain the shape of the answer.

This is the API-layer mechanism. When the surface is Claude Code in CI rather than a direct API call, the equivalent controls are --output-format json plus --json-schema (3.6). Same goal of a schema-enforced machine-readable result, expressed as CLI flags instead of a tool definition.

The three tool_choice modes

The distinction the exam tests:

Mode	Guarantee	Who picks the tool	Use it when
"auto"	May call a tool, may return plain text	Model	Never, when structured output is mandatory
"any"	Must call a tool	Model	Several schemas, document type unknown — the tool name doubles as the classification
{"type": "tool", "name": "..."}	Must call that tool	You	One particular extraction has to run, e.g. metadata before enrichment consumes it

The API has a fourth value, none, which blocks tool calls for that request.¹⁹ The guide does not test this — if it appears as an option, it is not the credited answer.

Strict schemas stop syntax errors, not semantic ones

This is the highest-value nuance in the statement. JSON Schema's strict mode is the feature name to know here. The guide lists it as strict mode for syntax error elimination — syntax errors, and nothing more. Note where it actually lives: strict is a field on the tool definition, not on the schema and not on tool_choice.⁴⁸ Without it, the schema guides the model rather than binding it. A strict schema guarantees the shape: required keys present, values of the right type, enum values legal. It guarantees nothing about meaning. Line items can still fail to sum to the stated total; a vendor tax ID can land in the invoice-number field; a date can be wrong in perfect ISO 8601. Schema compliance is not correctness, and the remedy is semantic validation (4.4), not a stricter schema.

Schema design that does not induce fabrication

Two design decisions carry most of the weight:

• Required vs optional. If a source document may legitimately not contain a field, model it as optional or nullable. A field marked required forces the model to produce something, and what it produces is a fabricated value. Making absence representable is what converts a hallucination into an honest null.⁴⁹
• Extensible enums. Closed enums break on real-world data. Add an "unclear" value for genuinely ambiguous cases, and an "other" value paired with a detail string so an unanticipated category can be captured rather than forced into the nearest wrong bucket.

Finally, a schema constrains structure but says nothing about formatting. Source documents write dates, currencies and units inconsistently. Put format normalization rules in the prompt alongside the strict schema: "dates as YYYY-MM-DD; amounts as decimals with no currency symbol; for a range, record the lower bound and note it".

{
  "name": "extract_invoice",
  "description": "Record the fields present in this invoice. Omit or null any field the document does not contain; never infer a value.",
  "input_schema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string" },
      "issue_date": {
        "type": ["string", "null"],
        "description": "YYYY-MM-DD, or null if the document has no issue date"
      },
      "vendor_tax_id": { "type": ["string", "null"] },
      "currency": {
        "type": "string",
        "enum": ["USD", "EUR", "GBP", "other", "unclear"]
      },
      "currency_detail": {
        "type": ["string", "null"],
        "description": "Required when currency is 'other'; the code as printed"
      },
      "line_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "amount": { "type": "number" }
          },
          "required": ["description", "amount"]
        }
      }
    },
    "required": ["invoice_number", "currency", "line_items"]
  }
}

// Document type unknown: the model must call one of the schemas,
// and its choice of tool name is the classification.
const res = await client.messages.create({
  model: 'claude-opus-5',
  max_tokens: 4096,
  tools: [extractInvoice, extractPurchaseOrder, extractReceipt],
  tool_choice: { type: 'any' },
  messages: [{ role: 'user', content: [documentBlock] }],
});

const call = res.content.find((b) => b.type === 'tool_use');
// call.name  -> which document type matched
// call.input -> the structured extraction, already schema-compliant

// Metadata must exist before the enrichment pass runs: force that one tool.
const meta = await client.messages.create({
  model: 'claude-opus-5',
  max_tokens: 2048,
  tools: [extractMetadata, extractInvoice],
  tool_choice: { type: 'tool', name: 'extract_metadata' },
  messages: [{ role: 'user', content: [documentBlock] }],
});

Normalization rules:
- Dates: emit YYYY-MM-DD. If the source order is ambiguous (11/02/26) and the
  document gives no locale signal, set the date to null and set
  date_ambiguous to true. Do not pick an interpretation.
- Amounts: emit a decimal number with no currency symbol and no thousands
  separator. Treat "1.240,00" as 1240.00 only when the document uses comma
  decimals elsewhere; otherwise set the amount to null.
- Informal quantities ("about a tablespoon", "roughly room temperature"):
  leave the numeric field null and copy the phrase verbatim into the
  matching *_note field.
- Never convert, round, or infer a unit that the document does not state.