Enforce structured output using tool use and JSON schemas

Prompting the model to "respond with only valid JSON" works most of the time, and "most of the time" is exactly what breaks a production pipeline. Free-text JSON arrives wrapped in prose, fenced in markdown, carrying a trailing comma, or truncated at the token limit. Tool use removes that entire class of failure. You declare a tool whose input_schema is a JSON Schema, the model returns a tool_use content block whose input is an object conforming to that schema, and the API validates the structure for you. The object you read is already parsed and structurally valid.

The extraction "tool" does not need to execute anything. It is a schema carrier: you define it purely to give the model a typed slot to fill. You then scan response.content for the block with type == "tool_use" and read block.input. When the model calls a tool, stop_reason is "tool_use".

tools = [{
  "name": "extract_invoice",
  "description": "Record the fields extracted from an invoice document.",
  "input_schema": {
    "type": "object",
    "properties": {
      "invoice_number": {"type": "string"},
      "total": {"type": "number"}
    },
    "required": ["invoice_number", "total"]
  }
}]
msg = client.messages.create(
    model="claude-...", max_tokens=1024, tools=tools,
    tool_choice={"type": "tool", "name": "extract_invoice"},
    messages=[{"role": "user", "content": document}])
data = next(b.input for b in msg.content if b.type == "tool_use")

tool_choice controls whether and which tool the model calls, and it is the single most testable idea in this task statement.

• {"type": "auto"} (the default when tools are present): the model decides. It may call a tool, or it may return an ordinary text response. For extraction this is a trap, because the model can choose to answer in prose and your parser gets nothing to read.
• {"type": "any"}: the model must call one of the provided tools, but it chooses which. Use this when several extraction schemas exist and you do not yet know the document type.
• {"type": "tool", "name": "extract_metadata"}: forced selection. The model must call that exact tool. Use this when exactly one schema applies, or when a specific extraction must run before later steps.
• {"type": "none"}: prevents tool use entirely (rarely relevant here).

One behavioral detail worth memorizing: when you force a tool (either any or a specific name), the model goes straight to the tool call and cannot emit leading reasoning text, which also makes forced choice incompatible with extended thinking. If you need the model to reason before extracting, use auto with strong instructions, or split into two calls.

A required field the model cannot find in the source is a hallucination generator. To satisfy the schema, the model will invent a plausible value rather than leave the slot empty. The fix is to make any field the document might legitimately lack either optional (simply leave it out of the required array) or nullable so the model has a sanctioned way to say "not present."

"properties": {
  "total": {"type": "number"},
  "due_date": {"type": ["string", "null"]},
  "po_number": {"type": ["string", "null"]}
},
"required": ["total"]

Here total is mandatory, while due_date and po_number can come back as null. Reserve required for fields that must always exist. This one design choice does more to cut fabrication than any prompt instruction, because it removes the pressure that caused the model to guess in the first place.

For categorical fields, an enum constrains the model to a fixed set of legal values, which is far more reliable than free text you later have to normalize. But rigid enums cause two problems: the model is forced to pick a category even when the source is ambiguous, and any real-world value outside your list forces a wrong choice.

Solve both with two additions. Add an "unclear" value so the model can flag genuine ambiguity instead of guessing. And add an "other" value paired with a free-text other_detail field so novel categories are captured rather than mis-slotted into the nearest enum member.

"document_type": {
  "type": "string",
  "enum": ["invoice", "receipt", "purchase_order", "other", "unclear"]
},
"other_detail": {"type": ["string", "null"]}

This keeps the schema strict and machine-friendly while remaining extensible, and it surfaces the cases a human should review instead of burying them inside a confident-looking but wrong category.

This is the highest-value nuance in the whole task statement. A strict JSON schema via tool use guarantees the output is well-formed and type-correct. It does not guarantee the output is correct. The model can still place the tax amount in the subtotal field, return line items that do not add up to total, or transpose the invoice date and the due date. The schema is completely blind to all of these because each one is a semantic error, not a shape error.

Design defensively. Have the model extract both a calculated_total (the sum it computed from the line items) and a stated_total (the figure printed on the document), then compare them in code. Add a conflict_detected boolean for sources that contradict themselves. The schema gets you a clean object to work with; your own validation logic decides whether that object is trustworthy. (Task 4.4 covers the retry-with-error-feedback loop that consumes these validation signals.)

A JSON Schema constrains structure and type, but it cannot normalize the content of a value. Source documents render the same amount as $1,200.00, 1200 USD, or 1.200,00, and dates as 03/04/25, 4 March 2025, or 2025-03-04. If you only supply a schema, the model may faithfully copy whatever ambiguous string it saw.

So pair the strict output schema with explicit normalization rules in the system or user prompt. For example: express all dates as ISO 8601 YYYY-MM-DD; return monetary amounts as a decimal number with no currency symbol or thousands separator, and put the currency in the dedicated currency field; strip surrounding whitespace from identifiers. The schema enforces the container; the prompt tells the model how to fill it. Using both together is what produces output that is consistent across a large, messy corpus rather than merely syntactically valid.