Structured Output

When a downstream system needs machine-readable output, prompting Claude to *return JSON* is fragile — the model can still emit malformed or drifting structures. The reliable approach is tool use: you define a tool whose input_schema is the shape you want, and Claude returns a tool_use block whose input conforms to that schema. This eliminates JSON syntax errors entirely.

messages=[{"role": "user",
  "content": "Extract the invoice as JSON."}]
# reply may include prose -> json.loads() throws

tools=[invoice_tool],
tool_choice={"type": "tool",
             "name": "extract_invoice"}
# msg.content -> tool_use.input conforms to schema

The three tool_choice modes

For guaranteed extraction into a single known schema, force the specific tool. Use "any" when the input could match one of several schemas and you want the model to select. Reserve "auto" for cases where a plain text answer is a valid outcome.

import anthropic

client = anthropic.Anthropic()

invoice_tool = {
    "name": "extract_invoice",
    "description": "Extract structured fields from an invoice.",
    "input_schema": {
        "type": "object",
        "properties": {
            "invoice_number": {"type": "string"},
            "issue_date": {"type": "string", "description": "ISO 8601 (YYYY-MM-DD)"},
            "total": {"type": "number", "description": "Decimal amount, no currency symbol"},
            "currency": {"type": "string", "enum": ["USD", "EUR", "GBP", "unclear"]},
            "department": {"type": ["string", "null"], "description": "null if absent"}
        },
        "required": ["invoice_number", "total"]
    }
}

msg = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[invoice_tool],
    tool_choice={"type": "tool", "name": "extract_invoice"},
    messages=[{"role": "user", "content": document_text}],
)
data = next(b.input for b in msg.content if b.type == "tool_use")

Syntax versus semantic errors

A schema constrains structure — field names, types, required keys — so the output is always parseable. It does not guarantee the values are correct. Semantic errors slip through: line items that do not sum to the stated total, a value placed in the wrong field, or a fabricated number for information that was never in the source. Catching those requires external validation logic, covered in the next lesson.

Schema design that prevents fabrication

• Optional/nullable fields — make a field nullable when the source may omit it, so the model reports absence instead of inventing a plausible value.
• An 'unclear' enum value — give genuinely ambiguous categoricals an explicit escape hatch instead of forcing a guess.
• 'other' plus a detail string — pair an 'other' enum with a freeform field to capture edge cases without distorting the taxonomy.
• Format normalization in the prompt — state format expectations (ISO 8601 dates, decimal currency) alongside the schema, since the schema alone cannot enforce them.