tool_use for Guaranteed Structure

You asked Claude for JSON and parsed the reply with json.loads(). It worked 95% of the time. The other 5%? A stray markdown fence, a trailing comma, a chatty preamble like "Here's the JSON you requested:" — and your pipeline throws.

For a Claude Certified Architect, that 5% is the whole problem. Production extraction, classification, and routing flows can't depend on the model happening to format text correctly. This lesson shows how tool_use plus a JSON Schema turns a probabilistic format into a guaranteed one — eliminating syntax errors and enforcing required fields.

A tool isn't only for taking actions. A tool definition is also a typed output contract. When you declare a tool with an input_schema, you're telling Claude exactly what shape its arguments must take — and the API validates the tool call against that schema.

So instead of asking for JSON in prose and hoping, you define a tool whose parameters are the structure you want, then force Claude to call it. The model fills in the fields; the schema guarantees the shape. Per the fact sheet: tool_use + JSON Schema eliminates syntax errors and enforces required fields.

Here's an extraction tool. Note the three pillars of a good tool definition: a clear name, a descriptive description, and a precise input_schema with per-property descriptions and a required list.

The schema below extracts a support ticket. We require only the fields that are always present — more on that decision soon.

Declaring the tool isn't enough — with the default, Claude might answer in text instead. The tool_choice parameter controls that decision:

• {"type": "auto"} — Claude picks text or a tool (the default).
• {"type": "any"} — Claude must call some tool. This is what guarantees structured output.
• {"type": "tool", "name": "X"} — force one specific tool by name.

When you have exactly one schema tool and want a guaranteed call to it, force it by name. This removes the "answer in prose" escape hatch entirely.

When Claude calls the tool, the response contains a tool_use content block. The structured data lives in block.input — already parsed into a Python dict by the SDK, conforming to your schema.

One discipline from the fact sheet: always parse with the SDK's parsed object, never raw-string-match the serialized input. Recent models may escape Unicode or forward slashes differently, so treat block.input as structured data, not text.

This is the single most tested decision in this lesson. The rule from the fact sheet is blunt:

Mark a field required ONLY if it is always present. NEVER require a field that may be absent — the model will fabricate a value to satisfy the schema.

If customer_id sometimes isn't in the source text but you list it under required, Claude won't return an empty result — it will invent a plausible-looking ID to make the tool call valid. That's a silent data-integrity bug. Required means "guaranteed by the source," not "nice to have."

Fields that may be absent simply stay out of the required array. Claude omits them when the source lacks the data, instead of hallucinating.

Here customer_id and attachments are optional; only summary and priority — which we can always derive — are required.

Enums constrain a field to a fixed set of values — great for categories, labels, and priorities. But a rigid enum forces every input into one of your predefined buckets, which breaks on edge cases you didn't anticipate.

The fact-sheet pattern for extensibility: use enums with an "other" value plus a free-text detail field. When Claude hits something outside your categories, it picks other and explains in the detail field — instead of mislabeling.

The schema guarantees syntactic shape, but you still validate semantics — totals that add up, dates in range, cross-field consistency. Use a Pydantic-style validator on block.input.

When validation fails on a format, structural, or arithmetic error, use retry-with-feedback: resend the original source, the wrong output, and the exact validation error. Critically, the fact sheet warns: retry does NOT help when the information is simply absent from the source — retrying just invites fabrication.

For numeric extraction, a powerful schema trick is to make Claude expose its work so discrepancies are detectable. Per the fact sheet: extract both a calculated_total and a stated_total to detect discrepancies.

If the document says "Total: $1,200" but the line items sum to $1,150, two separate fields surface the mismatch — your validator catches it instead of trusting a single number. The schema becomes an audit instrument, not just a container.

Structured output is one stop in the larger agentic loop: request → inspect stop_reason → if tool_use, handle the tool → repeat until end_turn. A forced schema call returns stop_reason: "tool_use"; you read block.input and proceed.

Two architect-grade reminders: terminate on the stop_reason, never by parsing text for words like "done." And keep provenance — map each extracted claim back to its source (doc name, quote, date) so downstream consumers can trust and audit the structured result.

You're extracting invoices. The source PDFs sometimes omit a purchase-order number. A teammate proposes putting po_number in the schema's required array "so we always get one." What should you do?

Key takeaways for the exam and for production:

• tool_use + JSON Schema eliminates syntax errors and enforces required fields — far more reliable than parsing prose JSON.
• tool_choice: "any" guarantees some tool call; {"type":"tool","name":"X"} forces a specific schema tool; "auto" leaves it optional.
• required = always present. Never require a possibly-absent field — it causes fabrication. Optional fields simply stay out of required.
• Enums need an "other" + detail field for extensibility.
• Read structured data from block.input; never raw-string-match the serialized tool input.
• Retry-with-feedback fixes format/arithmetic faults — not absent information. Use calculated_total vs stated_total for self-correction, and keep provenance.