AnthropicClaude Certified Architect – Foundations2026-104.3 Enforce structured output using tool use and JSON schemas
Route documents before allowing enrichment calls
Completed by the knowledge check
Learning objective
Use tool_choice: "any" for unknown document types or force extract_metadata before enrichment where the model supports forced selection; enforce must-run ordering in application code otherwise.
Core idea
An unknown document type and a mandatory first extraction are different decisions. When several extraction contracts are valid candidates, require a call and let Claude select the contract. When enrichment depends on metadata, require that specific extraction before the enrichment stage can execute.
tool_choice can express either decision on models that support forcing. It cannot make unsupported request combinations valid, and a request-level choice does not create a persistent workflow prerequisite. Your application owns the progression from accepted metadata to enrichment.
See 2.3.4 for the general choice modes and 2.3.5 for required-first-tool control. This lesson applies them to a document inbox where both record type and prerequisite evidence determine the next step.
How it works
Require a suitable extraction contract
Suppose your tools list contains extract_invoice, extract_credit_note, and extract_receipt. Their descriptions identify the evidence and document type each accepts. If any of those contracts could fit the input, the request field is tool_choice: {"type": "any"}. The objective’s tool_choice: "any" is the guide’s shorthand for that object.
On supported models, any requires a call to one of the provided tools while leaving the name to Claude. It does not identify the correct document type for the model, and it does not guarantee that the chosen contract matches the document. The application still reads the returned tool_use.name and checks whether its extracted fields fit the evidence.
Set strict: true on the extraction tools to add schema enforcement. Selection and input shape are independent: any requires a call, while strict mode constrains the arguments of the call. See 4.3.2 for those guarantees and 4.3.4 for representing ambiguous evidence within a record.
When the endpoint accepts exactly one extraction call per document, add disable_parallel_tool_use: true inside tool_choice. With any or a named forced tool, this limits the response to exactly one tool call. Without that control, requiring a tool is not the same as imposing your one-record cardinality contract.
Check the selected contract against the document
A schema-valid call to extract_invoice can still be the wrong response to a credit note. Check the returned tool_use.name against the document’s evidence before accepting input or dispatching enrichment. For example, a document explicitly labelled “credit note” should not enter the invoice path merely because the selected schema accepts its identifier and amount.
When the selected contract does not fit, reject that extraction result and keep enrichment closed. If the source contains decisive evidence that the extraction missed, re-ask with that evidence and the distinction between the candidate tools. If the source itself is ambiguous, route it to review rather than converting an arbitrary tool selection into a document type. These are application acceptance decisions; any supplies a call, not a verified classification.
Keep tool descriptions specific to the distinctions the inbox needs. extract_invoice can describe invoice-number evidence and the stated invoice total; extract_credit_note can describe credit-note evidence and the credited amount. If the descriptions overlap so completely that either tool appears suitable, requiring a call preserves the ambiguity. See 2.1.1 for description design; here the deciding evidence is which record contract the document supports.
Do not use a second schema-valid response alone as proof that the first classification was repaired. The acceptance question remains whether the selected contract fits the source. Record which contract was accepted so the downstream consumer reads invoice, credit-note, or receipt fields under their intended meanings. Only a selected contract that fits the source opens enrichment; a mismatch is re-asked or routed to review.
Consider one extraction tool with a type field
An alternative is one application-defined extract_document tool with a document_type property in its input_schema. A string enum can contain invoice, credit_note, receipt, and unclear. The tool’s descriptions explain the evidence for each type, while its record carries the fields the consumer needs.
This moves classification from tool_use.name into tool_use.input.document_type. It suits a shared record whose fields have consistent meanings across document types. If invoice and credit-note records need substantially different fields or interpretations, separate extraction tools keep those contracts visible instead of building one large record full of inapplicable values.
The unclear value provides a structured answer when no type can be established. Three tools under any without an ambiguity path require selection among their offered contracts; they do not create a fourth unresolved state. A shared type enum makes that state explicit, and the consumer holds unclear records for review. See 4.3.4 for the distinction between ambiguous evidence, absent values, and a recognized but unlisted category.
Neither design determines truth through its schema alone. Choose multiple tools when distinct record contracts are useful; choose one type-bearing tool when a common record and an explicit unresolved classification fit the consumer. In either design, check source evidence before using the classification to enable enrichment.
Require metadata before enrichment
When supplier lookup and order matching need metadata first, a supported first-stage request can name that application-defined extraction tool:
{
"tool_choice": {
"type": "tool",
"name": "extract_metadata",
"disable_parallel_tool_use": true
}
}extract_metadata must appear in tools, and its input contract captures the prerequisite evidence. Accept that record before enabling enrichment. See 2.3.5 for the follow-up return to auto and thinking behavior, and 1.4.1 for the application-owned prerequisite gate.
Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1 reject any and named tool forcing with a 400 error. Manual extended thinking, thinking: {"type": "enabled"}, also rejects both modes. For unsupported configurations, use an application-controlled stage with auto and strict tools, or native JSON outputs through output_config.format; see 2.3.5 for the fallback control flow and 4.3.2 for the output contract.
Key distinctions and trade-offs
Unknown type versus known first operation: any leaves the tool name open. A named tool choice fixes it. Forcing every document into extract_invoice removes the selection that a mixed inbox needs.
Required call versus exactly one call: disable_parallel_tool_use: true controls cardinality. It does not determine which schema fits the source or validate extracted values.
Prompt preference versus executable gate: Under auto, prompting influences tool selection. The application gate prevents enrichment execution until accepted metadata exists. This remains useful even when model selection is usually correct.
Contract name versus type field: Multiple tools classify through tool_use.name; one extract_document tool classifies through a field in input. The latter needs an explicit unclear branch if unresolved classification is a permitted outcome. Neither location removes the need to check the evidence.
Architecture / decision scenario
An accounts-payable inbox receives invoices, receipts, and credit notes without reliable type labels. Its supported forcing configuration provides three strict extraction tools and sends tool_choice: {"type": "any", "disable_parallel_tool_use": true}. One response selects extract_invoice for a document labelled “credit note.” The consumer rejects the mismatch, does not dispatch enrichment, and re-asks with the label evidence and the distinction between the two contracts.
A second document has no evidence sufficient to select a type. Requiring another choice among the same three tools cannot establish the missing evidence. The team considers a shared extract_document contract with a document_type enum including unclear; its consumer sends that state to review. It keeps separate tools where the invoice and credit-note fields need distinct meanings.
Accepted documents proceed to metadata extraction before supplier and order enrichment. Where forcing is supported, the first-stage request names extract_metadata. A deployment using Claude Sonnet 5.5 instead uses an application-controlled extraction stage because the forced request would return 400. In both cases, the prerequisite gate from 1.4.1 opens only after the metadata record is accepted. A wrong contract, unclear classification, or missing required extraction leaves enrichment closed.
Common exam traps
- Using
anywhen a specific tool must run first. - Forcing an invoice contract when the document type is unknown.
- Assuming strict inputs guarantee a call under
auto. - Treating a schema-valid extraction call as proof of correct document classification.
- Treating an unsupported forcing 400 as a classification failure.
- Equating tool-list order with prerequisite enforcement.
Where the exam guide differs
The guide presents any and forcing extract_metadata as ways to guarantee extraction and first-step ordering without the product’s model and thinking restrictions. Anthropic documents those restrictions. The guide writes tool_choice: "any"; the Messages API takes {"type": "any"}, and an exam option printing the shorthand means the any mode. Read an exam item using forcing as assuming a supported configuration; for a named unsupported model or a hard workflow requirement, choose an application-controlled extraction stage and prerequisite gate.
What to remember
Use any for a choice among extraction schemas and a named tool for a specific supported first call. Check forcing support, control call count when needed, and let application acceptance unlock enrichment. Under auto, missing extraction is an outcome to handle, not a guarantee strict mode supplies.
Knowledge check
An accounts-payable inbox receives invoices, credit notes, and receipts without reliable type labels. The request offers extract_invoice, extract_credit_note, and extract_receipt, the deployed model supports forced tool use, and Claude sometimes answers in text instead of calling a tool. Each document must use a single request that requires an extraction call while leaving the contract selection open. Which design meets that requirement?
tool_choice: {"type": "any"}extract_invoice by nameauto and a prompt requiring a callany requires a call to one of the offered tools while leaving the choice of contract to Claude, which is what an inbox of unknown types needs. Forcing extract_invoice pushes credit notes and receipts into the invoice contract, a prompt under auto still permits a text reply, and forcing each tool in turn produces wrong-contract records you then have to choose among.Supplier lookup and order matching need the record that extract_metadata produces. The application already blocks enrichment until it accepts metadata, and later requests must allow supplier lookup and order matching calls. On a model that supports forced tool use, the first request offers metadata, supplier lookup, and order matching tools and must produce the metadata call. Which selection policy meets that requirement?
tool_choice to {"type": "any"} and describe the ordering in the promptextract_metadata first in tools and keep tool_choice on autoextract_metadata by name on the first request onlyextract_metadata by name on every request in the conversationtool choice requires the metadata call rather than leaving the tool name open; the existing application gate allows enrichment only after accepting that record. any leaves the name open, tool-list order is not enforcement, and forcing the same tool on every request leaves no turn in which an enrichment tool can be called.A pipeline moves to Claude Sonnet 5.5, and its first-stage request that forces extract_metadata by name now returns 400. Enrichment must still never run before the metadata record is accepted. What should the team change?
tool_choice: {"type": "any"}auto with strict tools and gate enrichment in application codeany and named tool forcing with 400, and manual extended thinking rejects them too, so no forcing variant is available and retrying resends an unsupported configuration. The documented alternative is auto with strict tool use, with the prerequisite enforced by an application gate that opens enrichment only after the metadata record is accepted.Under tool_choice: {"type": "any"} with three strict extraction tools, a document labelled “Credit note” comes back as a schema-valid extract_invoice call. What should the consumer do?
any guarantees a call, not a verified classification, and strict mode checks only the shape of the chosen contract, so a schema-valid invoice record can still be the wrong contract. The consumer checks tool_use.name against the evidence, keeps enrichment closed, and re-asks with the decisive label. Another schema-valid call proves no more about the contract than the first did, and relabelling invoice fields gives them meanings they were not extracted under.A single-record endpoint sends tool_choice: {"type": "any"} on a model that supports it. Some responses contain two extraction calls for one document, and the endpoint accepts exactly one. Which change enforces that?
strict: true on every extraction tooltool_choice to {"type": "auto"}disable_parallel_tool_use: true inside tool_choicedisable_parallel_tool_use: true as a top-level request fieldany or a named tool, disable_parallel_tool_use: true inside the tool_choice object limits the response to exactly one tool call. Strict mode constrains each call’s arguments, not how many calls there are; auto alone neither limits the count nor requires a call; and the setting is a field of tool_choice , not a top-level request parameter.References
- Anthropic, Define tools
- Anthropic, Parallel tool use
- Anthropic, Handle tool calls
- Anthropic, Strict tool use
- Anthropic, Structured outputs
- Anthropic, Claude Certified Architect – Foundations Exam Guide