D2 · Tool Design & MCP › Cluster 4 · Advanced Tool Use

4.2 · Forcing Structured JSON via Tools

input_schema as the output contract

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:

  1. Define one tool whose input_schema is the shape you want back. You never intend to "execute" it — the schema is a declaration of the output contract.
  2. Force it with tool_choice: {"type": "tool", "name": "…"}. Claude must emit exactly that tool call.
  3. Read tool_use.input from the response — that object is your structured result. There's no round-trip; you don't send a tool_result back.
🔑 The schema is the contract. Where a free-text prompt "please reply in JSON" only asks, forcing a tool constrains the model to your 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:

⚠️ Forcing a tool prefills the assistant turn — Claude emits no natural-language text before the 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

flowchart TD A["Define tool
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

AspectForced tool (tool_choice: tool)output_config.format
What it constrainsThe tool_use.input objectThe whole text response (valid JSON)
Read fromtool_use.inputFirst text block (parse JSON)
Other tools available too?Yes — one is just forcedNot a tool concept; separate feature
Schema validationAdd strict: trueEnforced by the format
Works with thinking?No (forcing + thinking error)Yes
Rule of thumb: forced tool when you're "extracting into a shape" alongside real tools; output_config.format when the deliverable is a JSON document.

EXAM TRAPS

Trap: Sending a tool_result back for the forced "schema" tool. → There's nothing to execute. The structured data is already in tool_use.input; stop there.
Trap: Relying only on a prompt ("reply as JSON") for a guaranteed shape. → Prompts ask; a forced tool (optionally strict) constrains. Use the schema as the contract.
Trap: Expecting a chatty preamble before the tool call. → tool_choice: tool prefills the assistant turn, so no natural-language text precedes tool_use.
Trap: Setting 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.