4.3 Structured Output with Tool Use

Often you don't want Claude to write prose — you want STRUCTURED DATA your program can use: extract an invoice into fields, pull entities from a document, return a JSON object your code parses. Task Statement 4.3 is about getting that structure RELIABLY. The naive approach — 'please respond in JSON' in the prompt — works most of the time, which in production means it FAILS some of the time: a stray comma, an unescaped quote, a missing bracket, and your parser crashes.

There's a much more reliable mechanism, and it reuses something you already know: tool use. Recall from Domain 2 that a tool is defined with a JSON SCHEMA describing its inputs. When Claude calls a tool, the API guarantees the call conforms to that schema — valid JSON, right field names, right types. So you can define a 'tool' whose only purpose is to RECEIVE your structured data (an extract_invoice tool with fields for date, total, line items), have Claude 'call' it, and read the structured result straight out of the tool call. It's like the difference between asking someone to write their answer freehand versus handing them a form with labelled boxes — the form guarantees you get the fields you need in the shape you expect.

The headline: tool_use with a JSON schema is the most reliable way to get schema-compliant structured output, and it ELIMINATES JSON syntax errors. But — and this is the lesson's most important nuance — it does NOT eliminate every kind of error. Let's see exactly what it guarantees and what it doesn't.

For structured output you usually need to GUARANTEE Claude calls your extraction tool rather than replying in prose. That's the tool_choice setting from Domain 2.3, applied here for output structure. There are exactly four values, and the exam tests that you know them precisely.

Two patterns matter for extraction. Use 'any' when you have multiple possible extraction schemas and the document type is unknown — it guarantees Claude calls ONE of them rather than chatting. Use a forced specific tool ({type:'tool',name:'extract_metadata'}) when a particular extraction MUST run first — e.g. extract metadata before any enrichment step — then handle later steps in follow-up turns. And for an ironclad guarantee, combine tool_choice:'any' with strict:true on the tool, which forces both that a tool IS called AND that its inputs strictly match your schema.

Now the single most important — and most tested — idea in this lesson. tool_use with a strict schema guarantees the SHAPE of the output: valid JSON, all required fields present, correct types. It does NOT guarantee the output is CORRECT. The schema is a form; it checks that every box is filled with the right TYPE of thing, but it can't check that the VALUES are right.

Concretely, a schema-valid extraction can still contain SEMANTIC errors: line items that don't add up to the stated total, a value placed in the wrong field (the invoice number where the PO number belongs), or outright fabricated data that happens to fit the schema. Every one of those passes schema validation — the JSON is perfectly well-formed — yet the data is wrong. The exam tests this directly: don't assume tool_use means the answer is correct. Schema = structure; correctness needs separate checking (which is the whole subject of the next lesson, 4.4).

Schema design itself can prevent one common error: fabrication. Here's the trap. If you mark every field REQUIRED, you're telling the model 'this field must have a value' — so when the source document doesn't contain that information, the model FABRICATES one to satisfy the requirement. You've literally pressured it into making things up. The fix is to make fields that may be absent OPTIONAL or NULLABLE, which permits an honest null when the data isn't there. A nullable field says 'it's fine to say you don't know' — and that's exactly what you want for extraction.

Two more schema design moves help with ambiguity and varied formats. For categorization, add an 'unclear' enum value for genuinely ambiguous cases (so the model isn't forced to pick a wrong category) and an 'other' + a free-text detail field for things outside your fixed categories (extensible without fabrication). And put format-NORMALIZATION rules in the prompt alongside the schema — e.g. 'express all dates as ISO-8601' — so inconsistent source formatting gets cleaned up as it's extracted.

The 4.3 traps cluster around three ideas: tool_use ≠ correctness, the right tool_choice for structure, and required-fields-cause-fabrication.

• •Thinking tool_use guarantees correctness. ✗ Assuming a schema-valid extraction is right. ✓ It's structurally valid only; semantic errors (sums, misplaced values, fabrication) still need validation (4.4).
• •Wrong tool_choice for structure. ✗ Leaving tool_choice on 'auto' when you must get structured output. ✓ Use 'any' (or a forced tool); add strict:true.
• •All fields required. ✗ Marking every field required, pressuring fabrication of absent data. ✓ Make maybe-absent fields nullable for honest nulls.
• •Confusing auto/any/tool. ✗ Mixing up the four tool_choice values. ✓ auto may return text; any forces some tool; tool forces a specific one; none disables tools.

You now know how tool_use guarantees structure, the four tool_choice values, the critical structure-vs-correctness limit, and schema design that prevents fabrication. The exercise builds a real extraction tool and exposes both what the schema guarantees and what it doesn't.

tool_use guarantees structure; it can't guarantee correctness. The next lesson, 4.4, closes that gap — validation and retry loops that catch and fix the semantic errors the schema lets through.