Structured Output with Tool Use

Official Exam Guide Objectives

Task 4.3: Enforce structured output using tool use and JSON schemas

Knowledge of

• Tool use (tool_use) with JSON schemas as the most reliable approach for guaranteed schema-compliant structured output, eliminating JSON syntax errors
• The distinction between tool_choice: "auto" (model may return text instead of calling a tool), "any" (model must call a tool but can choose which), and forced tool selection (model must call a specific named tool)
• That strict JSON schemas via tool use eliminate syntax errors but do not prevent semantic errors (e.g., line items that don't sum to total, values in wrong fields)
• Schema design considerations: required vs optional fields, enum fields with "other" + detail string patterns for extensible categories

Skills in

• Defining extraction tools with JSON schemas as input parameters and extracting structured data from the tool_use response
• Setting tool_choice: "any" to guarantee structured output when multiple extraction schemas exist and the document type is unknown
• Forcing a specific tool with tool_choice: {"type": "tool", "name": "extract_metadata"} to ensure a particular extraction runs before enrichment steps
• Designing schema fields as optional (nullable) when source documents may not contain the information, preventing the model from fabricating values to satisfy required fields
• Adding enum values like "unclear" for ambiguous cases and "other" + detail fields for extensible categorization
• Including format normalization rules in prompts alongside strict output schemas to handle inconsistent source formatting

What You Need to Know

Where the requirement is output that reliably conforms to a schema, two approaches are available and they are not close:

1. tool_use with JSON schemas — eliminates JSON syntax errors entirely
2. Prompt-based JSON — model can produce malformed JSON

That ordering is worth committing to memory, because several exam items rest on it. A tool's JSON schema constrains the shape of what comes back, so the failure modes of hand-produced JSON — an unclosed bracket, a trailing comma, an unquoted key — stop being possible rather than becoming rarer. Note that the schema constrains the shape; it is the separate tool_choice parameter that determines whether the tool is called at all. Asking for JSON in a text response offers no structural guarantee whatever, and at production volumes will periodically return something that does not parse.

tool_choice: The Three Modes

Whether and how the model reaches for a tool is governed by tool_choice, and all three settings are examinable:

"auto" (default): The choice is the model's — it may call a tool or it may answer in text. Appropriate where responding conversationally is a legitimate outcome, and unsuitable wherever structured output is mandatory, because nothing obliges it to call the extraction tool.

"any": A tool call is compulsory; which tool remains open. This is the setting for a bank of schemas — extract_invoice, extract_receipt, extract_contract — against a document whose type is not known in advance. Structured output is guaranteed, and the selection stays flexible.

{"type": "tool", "name": "extract_metadata"}: One named tool, compulsory. Use it to make a particular step unavoidable — metadata extraction running before any enrichment, for instance. No selection, maximum control.

// Force guaranteed structured output with unknown document type
const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  tool_choice: { type: "any" },
  tools: [extractInvoiceTool, extractReceiptTool, extractContractTool],
  messages: [{ role: "user", content: documentText }]
});

// Force a specific extraction step
const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  tool_choice: { type: "tool", name: "extract_metadata" },
  tools: [extractMetadataTool],
  messages: [{ role: "user", content: documentText }]
});

# Force guaranteed structured output with unknown document type
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    tool_choice={"type": "any"},
    tools=[extract_invoice_tool, extract_receipt_tool, extract_contract_tool],
    messages=[{"role": "user", "content": document_text}],
)

# Force a specific extraction step
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    tool_choice={"type": "tool", "name": "extract_metadata"},
    tools=[extract_metadata_tool],
    messages=[{"role": "user", "content": document_text}],
)

What tool_use Does NOT Prevent

Here is where items get sharp. Schema enforcement removes syntax failures and leaves semantic ones entirely untouched:

• Sum discrepancies: the individual amounts are all present and correct, and they do not add up to the total the document states
• Field placement errors: the right value in the wrong property — a date sitting in an amount field passes validation whenever both are typed as strings
• Fabrication: a required field with nothing in the source to fill it gets filled anyway, with something that looks like the real thing

Every one of those produces JSON that validates perfectly. The schema is a statement about shape, and shape is silent on whether the values are right — which is what Task Statement 4.4 exists to address.

Schema Design for Production

A well-shaped schema removes whole categories of error before any validation logic runs:

Optional/nullable fields — Where a source document may simply not carry a piece of information, the corresponding field should be optional or nullable, and this is the main structural defence against fabrication. A required field presents the model with a demand it must satisfy, and something plausible is easier to produce than nothing. Make the field nullable and null becomes an available, honest answer.

{
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string" },
    "vendor_name":    { "type": "string" },
    "payment_terms":  { "type": ["string", "null"] },
    "purchase_order": { "type": ["string", "null"] },
    "tax_reference":  { "type": ["string", "null"] }
  },
  "required": ["invoice_number", "vendor_name"]
}

"unclear" enum value — Classification fields need somewhere to put a genuinely ambiguous case. Without an explicit unclear option the model must pick one of the definite categories, which converts uncertainty into a confident-looking answer.

"other" + detail string — For categories that will not stay closed, pair an other enum member with a freeform detail field. Cases outside your taxonomy are then recorded rather than forced into the nearest approximation.

{
  "category": {
    "type": "string",
    "enum": ["invoice", "receipt", "contract", "unclear", "other"]
  },
  "category_detail": {
    "type": ["string", "null"],
    "description": "Freeform detail when category is 'other'"
  }
}

Format normalisation rules — Formatting consistency belongs in the prompt rather than the schema, because the schema constrains types and not conventions. State the rules alongside it: dates in ISO 8601, currency amounts as decimal numbers with the symbol stripped.

Deep Dive

tool_choice: four values, not three, in the API reference

The lesson's three-mode framing (auto / any / forced) is the exam's practical grouping, but the API reference actually documents four tool_choice types: "The model can use a specific tool, any available tool, decide by itself, or not use tools at all" — auto, any, tool, and none. none prevents Claude from using any tools and is the default when no tools are provided; if you supply no tools at all, tool_choice: "none" costs zero additional system-prompt tokens. auto is the default the moment any tools array is present.

Sources: https://platform.claude.com/docs/en/api/messages (the four types) · https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools (none as the default without tools) · https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview (zero additional tokens) (fetched 2026-07-30)

Combine tool_choice "any" with strict:true for a double guarantee

Guaranteeing "a tool was called" and guaranteeing "the tool's input matches the schema" are two separate guarantees, and the docs spell out how to get both at once: "Combine tool_choice: {\"type\": \"any\"} with strict tool use to guarantee both that one of your tools will be called AND that the tool inputs strictly follow your schema. Set strict: true on your tool definitions to enable schema validation." tool_choice: "any" alone only forces a tool call — without strict: true the input JSON can still technically satisfy an unvalidated schema. This is the mechanism the reliability hierarchy in this lesson is built on.

Sourceplatform.claude.com › implement-tool-usefetched 2026-07-30

A newer, separate mechanism: the Structured Outputs feature

Beyond tool_use, the API now offers a distinct structured outputs feature that constrains a plain-text JSON response (not a tool call) via constrained decoding: "Structured outputs constrain Claude's responses to follow a specific schema, ensuring valid, parseable output for downstream processing... through constrained decoding." It exposes two related controls that solve different problems and can be combined: output_config.format shapes what Claude says (JSON outputs), while strict: true on a tool definition validates how Claude calls your functions (tool parameters).

Sourceplatform.claude.com › structured-outputsfetched 2026-07-30

What structured-output schemas can and cannot express

The constrained-decoding grammar supports a defined subset of JSON Schema: "All basic types: object, array, string, integer, number, boolean, null; enum (strings, numbers, bools, or nulls only — no complex types); ... required and additionalProperties (must be set to false for objects)." Several common constraints are explicitly not supported: "Recursive schemas; ... External $ref; Numerical constraints (such as minimum, maximum, multipleOf); String constraints (minLength, maxLength)." A schema with additionalProperties set to anything other than false is also rejected. Note that null appears in the supported list both as a basic type and as a permitted enum member, so nullability has first-class support in the grammar.

Sourceplatform.claude.com › structured-outputsfetched 2026-07-30

First-request latency and a 24-hour grammar cache

Constrained decoding is not free on the first call: "The first time you use a specific schema, there is additional latency while the grammar compiles... Compiled grammars are cached for 24 hours from last use." Changing output_config.format also invalidates the prompt cache for that conversation thread, and using structured outputs adds a small hidden system prompt ("Claude automatically receives an additional system prompt explaining the expected output format"), which slightly raises input token counts on every call, not just the first.

Sourceplatform.claude.com › structured-outputsfetched 2026-07-30

Prefill — a retired workaround, now a 400 error on the newest models

Before tool_use and structured outputs existed as reliable mechanisms, teams forced JSON/YAML output by prefilling part of the assistant turn. The docs now describe this as a historical technique with a clear successor: "Prefills have been used to force specific output formats like JSON/YAML, classification, and similar patterns... The Structured Outputs feature is designed specifically to constrain Claude's responses to follow a given schema." Crucially, prefill is no longer just discouraged — it is rejected outright on the newest models: "Starting with Claude 4.6 models and Claude Mythos Preview, prefilled responses... on the last assistant turn are no longer supported. Requests with prefilled assistant messages to these models return a 400 error." (Note separately that when tool_choice is any or tool, the API itself prefills the assistant message to force the tool call — that API-side mechanism is unaffected and is how forced tool use suppresses preamble text.)

Sources: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices (prefill history and the 400 error) · https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools (the API-side prefill under forced tool choice) (fetched 2026-07-30)

required vs optional in a tool's input_schema

The lesson's nullable-field defence against fabrication rests on ordinary JSON Schema mechanics inside input_schema: fields listed in the schema's required array are mandatory; everything else is optional, and enum restricts a field to a fixed set of values (the documented example limits a unit parameter to "celsius" or "fahrenheit"). There is nothing tool_use–specific about optionality — it is the same JSON Schema required array the constrained-decoding structured-outputs feature also reads.

Sourceplatform.claude.com › implement-tool-usefetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Build a Structured Extraction Tool with JSON Schema

Difficulty: Intermediate (2/4)

45 minutes

1. Define an extraction tool with a JSON schema: 3 required fields, 3 optional/nullable fields, an enum with unclear and other options, and a detail string field for the other category

Why: Schema design directly prevents fabrication. Required fields pressure the model to invent values when information is absent. Optional/nullable fields allow honest null responses. This is the root cause fix for hallucinated extraction data.

You should see: A valid JSON schema with required array containing only the 3 always-present fields, nullable type definitions for optional fields, and an enum array including unclear and other alongside the standard categories.

2. Test with tool_choice auto and observe cases where the model returns text instead of calling the tool

Why: The exam tests the distinction between auto, any, and forced tool_choice. Auto allows the model to respond conversationally instead of calling a tool, which means no guaranteed structured output. You need to see this failure mode firsthand.

You should see: At least one response where the model returns a text message describing the document contents instead of calling the extraction tool. This demonstrates why auto is unsuitable when you need guaranteed structured output.

3. Switch to tool_choice any and verify the model always returns structured output via a tool call

Why: tool_choice any guarantees a tool call while letting the model choose which tool. This is the correct setting for guaranteed structured output when the document type is unknown, a key exam distinction from auto.

You should see: Every response has stop_reason of tool_use and contains a valid tool call with structured output conforming to your schema. No text-only responses.

4. Force a specific tool with tool_choice {type: tool, name: extract_metadata} and verify the mandatory extraction step runs

Why: Forced tool selection ensures a mandatory first step executes regardless of the model decision. The exam tests this for scenarios like metadata extraction that must run before enrichment steps.

You should see: The response always calls the exact tool you specified, even when the document content might suggest a different tool would be more appropriate. The model has no flexibility in tool selection.

5. Process 5 documents — 3 with complete data and 2 with missing fields — and verify nullable fields return null rather than fabricated values

Why: This validates the most important schema design principle: optional/nullable fields prevent fabrication. The exam specifically tests the scenario where required fields pressure the model to invent plausible-looking data for absent information.

You should see: For the 3 complete documents, all fields populated with correct values. For the 2 documents missing information, the nullable fields return null instead of fabricated values. No invented dates, amounts, or identifiers.

Sources

• Claude Certified Architect Foundations Exam Guide — Task Statement 4.3 — Anthropic
• Tool Use (Function Calling) — Anthropic
• Building with Claude API (Skilljar) — Anthropic
• Messages API Reference — Anthropic
• Implementing Tool Use — Anthropic
• Structured Outputs — Anthropic
• Claude Prompting Best Practices — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Define an extraction tool with a JSON schema: 3 required fields, 3 optional/nullable fields, an enum with unclear and other options, and a detail string field for the other category

Why: Schema design directly prevents fabrication. Required fields pressure the model to invent values when information is absent. Optional/nullable fields allow honest null responses. This is the root cause fix for hallucinated extraction data.

You should see: A valid JSON schema with required array containing only the 3 always-present fields, nullable type definitions for optional fields, and an enum array including unclear and other alongside the standard categories.

const extractTool = {
  name: "extract_document",
  description: "Extract structured data from a document",
  input_schema: {
    type: "object",
    properties: {
      invoice_number: { type: "string" },
      vendor_name: { type: "string" },
      document_date: { type: "string", description: "ISO 8601 format" },
      payment_terms: { type: ["string", "null"] },
      purchase_order: { type: ["string", "null"] },
      tax_id: { type: ["string", "null"] },
      category: { type: "string", enum: ["invoice", "receipt", "contract", "unclear", "other"] },
      category_detail: { type: ["string", "null"], description: "Detail when category is other" }
    },
    required: ["invoice_number", "vendor_name", "document_date"]
  }
};

extract_tool = {
    "name": "extract_document",
    "description": "Extract structured data from a document",
    "input_schema": {
        "type": "object",
        "properties": {
            "invoice_number": {"type": "string"},
            "vendor_name": {"type": "string"},
            "document_date": {"type": "string", "description": "ISO 8601 format"},
            # Nullable rather than required: a required field pressures the
            # model into inventing a value it cannot find.
            "payment_terms": {"type": ["string", "null"]},
            "purchase_order": {"type": ["string", "null"]},
            "tax_id": {"type": ["string", "null"]},
            "category": {
                "type": "string",
                "enum": ["invoice", "receipt", "contract", "unclear", "other"],
            },
            "category_detail": {
                "type": ["string", "null"],
                "description": "Detail when category is other",
            },
        },
        "required": ["invoice_number", "vendor_name", "document_date"],
    },
}

Step 2. Test with tool_choice auto and observe cases where the model returns text instead of calling the tool

Why: The exam tests the distinction between auto, any, and forced tool_choice. Auto allows the model to respond conversationally instead of calling a tool, which means no guaranteed structured output. You need to see this failure mode firsthand.

You should see: At least one response where the model returns a text message describing the document contents instead of calling the extraction tool. This demonstrates why auto is unsuitable when you need guaranteed structured output.

const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  tool_choice: { type: "auto" },
  tools: [extractTool],
  messages: [{ role: "user", content: documentText }]
});
console.log("Stop reason:", response.stop_reason);
// If stop_reason is "end_turn", the model returned text, not structured output

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    tool_choice={"type": "auto"},
    tools=[extract_tool],
    messages=[{"role": "user", "content": document_text}],
)
print("Stop reason:", response.stop_reason)
# If stop_reason is "end_turn", the model returned text, not structured output

Step 3. Switch to tool_choice any and verify the model always returns structured output via a tool call

Why: tool_choice any guarantees a tool call while letting the model choose which tool. This is the correct setting for guaranteed structured output when the document type is unknown, a key exam distinction from auto.

You should see: Every response has stop_reason of tool_use and contains a valid tool call with structured output conforming to your schema. No text-only responses.

const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  tool_choice: { type: "any" },
  tools: [extractInvoiceTool, extractReceiptTool, extractContractTool],
  messages: [{ role: "user", content: documentText }]
});
// stop_reason should always be "tool_use"
// Check which tool was selected: response.content[0].name

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    tool_choice={"type": "any"},
    tools=[extract_invoice_tool, extract_receipt_tool, extract_contract_tool],
    messages=[{"role": "user", "content": document_text}],
)
# stop_reason should always be "tool_use"
# Check which tool was selected:
tool_use = next(b for b in response.content if b.type == "tool_use")
print(tool_use.name)

Step 4. Force a specific tool with tool_choice {type: tool, name: extract_metadata} and verify the mandatory extraction step runs

Why: Forced tool selection ensures a mandatory first step executes regardless of the model decision. The exam tests this for scenarios like metadata extraction that must run before enrichment steps.

You should see: The response always calls the exact tool you specified, even when the document content might suggest a different tool would be more appropriate. The model has no flexibility in tool selection.

const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  tool_choice: { type: "tool", name: "extract_metadata" },
  tools: [extractMetadataTool, extractDetailTool],
  messages: [{ role: "user", content: documentText }]
});
// response.content[0].name will always be "extract_metadata"

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    tool_choice={"type": "tool", "name": "extract_metadata"},
    tools=[extract_metadata_tool, extract_detail_tool],
    messages=[{"role": "user", "content": document_text}],
)
# The tool_use block's name will always be "extract_metadata"

Step 5. Process 5 documents — 3 with complete data and 2 with missing fields — and verify nullable fields return null rather than fabricated values

Why: This validates the most important schema design principle: optional/nullable fields prevent fabrication. The exam specifically tests the scenario where required fields pressure the model to invent plausible-looking data for absent information.

You should see: For the 3 complete documents, all fields populated with correct values. For the 2 documents missing information, the nullable fields return null instead of fabricated values. No invented dates, amounts, or identifiers.

// Document missing payment_terms and tax_id
const incompleteDoc = "Invoice #1234 from Acme Corp, dated 2024-03-15. Total: $500.00";

// With nullable fields, expect:
// payment_terms: null
// tax_id: null
// With an all-required schema, the model invents plausible values.

const toolUse = response.content.find(b => b.type === "tool_use");
const result = toolUse.input as Record<string, unknown>;
console.assert(result.payment_terms === null, "Should be null, not fabricated");
console.assert(result.tax_id === null, "Should be null, not fabricated");

# Document missing payment_terms and tax_id
incomplete_doc = "Invoice #1234 from Acme Corp, dated 2024-03-15. Total: $500.00"

# With nullable fields, expect:
#   payment_terms: None
#   tax_id: None
# With an all-required schema, the model invents plausible values.

tool_use = next(b for b in response.content if b.type == "tool_use")
result = tool_use.input
assert result["payment_terms"] is None, "Should be None, not fabricated"
assert result["tax_id"] is None, "Should be None, not fabricated"

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the schema and code you actually wrote.