Structured Output via Tools

A tool you never run

Need clean JSON, such as an extracted invoice? Define a tool whose input schema is the shape you want (record_invoice with fields for vendor, date and total) and force it with tool_choice. The model fills the arguments, which arrive as a parsed object. You do not actually run anything; the arguments are the result. Still validate values, because the schema controls shape, not truth.

Forcing the extraction tool

INVOICE_TOOL is a schema like the earlier examples. The structured data is in block.input.

reply = client.messages.create(
    model=MODEL, max_tokens=512,
    tools=[INVOICE_TOOL],
    tool_choice={"type": "tool", "name": "record_invoice"},
    messages=[{"role": "user", "content": invoice_text}],
)
block = next(b for b in reply.content if b.type == "tool_use")
data = block.input        # {"vendor": ..., "date": ..., "total": ...}

Keep extraction schemas small

A schema with forty fields invites mistakes. Extract a few well-named fields per call, mark uncertain ones as optional, and let the model return null instead of inventing a value.

Quick check: Does a schema guarantee the extracted values are correct?

• Yes, always
• Only for numbers
• No, it fixes the shape, so you still validate the values
• Only in Hindi