CONCEPT A single forced tool is a structured-output mechanism
You can turn tool use inside-out to guarantee a JSON shape. The trick has three parts:
- Define one tool whose
input_schemais the shape you want back. You never intend to "execute" it — the schema is a declaration of the output contract. - Force it with
tool_choice: {"type": "tool", "name": "…"}. Claude must emit exactly that tool call. - Read
tool_use.inputfrom the response — that object is your structured result. There's no round-trip; you don't send atool_resultback.
input_schema — no stray
prose, no markdown fences, no "Here is the JSON:" preamble.CONCEPT Harden it — and know the native alternative
Two upgrades and one comparison the exam cares about:
- Add
strict: trueto the tool sotool_use.inputis validated against the schema (requiresadditionalProperties: false+required). Now the shape isn't just requested — it's guaranteed to parse to your exact schema. - Force + strict together gives you both guarantees: the tool will be called and its input conforms.
- Native structured outputs (
output_config: {"format": {"type": "json_schema", "schema": …}}) are the newer, purpose-built path when you want the whole response to be JSON. Reach for the forced-tool pattern when you also want other tools available, or need the "extract into this shape" framing; reach foroutput_config.formatwhen the response itself should just be a JSON document.
tool_use block. And it's incompatible with extended thinking (4.1): you can't force
a tool while thinking is on.DIAGRAM Schema in, structured object out
input_schema = desired shape"] --> B["tool_choice:
{type:tool, name:record}"] B --> C["Claude MUST emit
tool_use(record, input={...})"] C --> D{"strict: true?"} D -->|"yes"| E["🟢 input validated
to schema exactly"] D -->|"no"| F["🔵 input matches shape
(parse it yourself)"] E --> G["Read tool_use.input
= your structured result"] F --> G G --> H["No tool_result sent —
the call IS the output"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef mid fill:#cce5ff,stroke:#4a90d9,color:#0a3a6a; class E ok; class F mid;
CODE One forced, strict tool as the output schema
The record_contact tool is never run — its input_schema defines the JSON you want,
and tool_use.input hands it back, schema-validated.
resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=[{ "name": "record_contact", "description": "Record the extracted contact fields.", "strict": True, # validate input to the schema "input_schema": { "type": "object", "properties": { "name": {"type": "string"}, "email": {"type": "string"}, "plan": {"type": "string", "enum": ["free", "pro", "enterprise"]}, }, "required": ["name", "email", "plan"], "additionalProperties": False, # required by strict }, }], tool_choice={"type": "tool", "name": "record_contact"}, # force it messages=[{"role": "user", "content": "Jane Doe, jane@co.com, wants the enterprise plan."}], ) block = next(b for b in resp.content if b.type == "tool_use") data = block.input # {'name':'Jane Doe','email':'jane@co.com','plan':'enterprise'} # No tool_result round-trip — the tool_use.input IS the answer.
TRADE-OFFS Forced tool vs. native structured outputs
| Aspect | Forced tool (tool_choice: tool) | output_config.format |
|---|---|---|
| What it constrains | The tool_use.input object | The whole text response (valid JSON) |
| Read from | tool_use.input | First text block (parse JSON) |
| Other tools available too? | Yes — one is just forced | Not a tool concept; separate feature |
| Schema validation | Add strict: true | Enforced by the format |
| Works with thinking? | No (forcing + thinking error) | Yes |
output_config.format when the deliverable is a JSON document.EXAM TRAPS
tool_result back for the forced "schema" tool. → There's
nothing to execute. The structured data is already in tool_use.input; stop there.strict) constrains. Use the schema as the contract.tool_choice: tool
prefills the assistant turn, so no natural-language text precedes tool_use.strict: true without additionalProperties: false
and required. → Strict mode needs both, or the request is rejected.PRACTICE
Q1 · How does one tool double as an output-schema mechanism?
Define the tool's input_schema to be the JSON shape you want, force it with
tool_choice:{"type":"tool","name":…}, and read tool_use.input from the response —
that object is your structured result. The tool is never executed; the schema is the contract.
Q2 · What does adding strict: true change, and what does it require?
It makes the API validate tool_use.input against the schema, guaranteeing it
conforms exactly. It requires additionalProperties:false and a required list on the
object.
Q3 · When would you pick output_config.format over a forced tool?
When the entire response should be a JSON document (and you want it to coexist with extended thinking, which forced tools can't). The forced-tool pattern shines when you're extracting into a shape while other real tools are also available.