Extraction Tools and tool_choice: Forcing Structured Output

1.Why a tool schema beats asking for JSON

If you ask Claude in plain prose to 'reply in JSON', the result depends on how well it follows instructions. You can get a stray preamble, a missing brace, or a number written as a string. Tool use takes a different approach. Anthropic describes it as a contract: your application states which operations exist and what shape their inputs take, and Claude decides when to call them. Claude never runs anything itself. It produces a structured request that matches your schema.

For extraction, that structured request is the output you want. The Anthropic cookbook describes a print_sentiment_scores tool whose only job is to get Claude to produce well-structured JSON. The tool does nothing. Its schema defines the shape of the answer.

On its own, a schema guides Claude but does not guarantee anything. The strict tool use docs say that without strict mode Claude can still return the wrong types or leave out required fields. Setting strict: true closes that gap with grammar-constrained sampling: Claude can only generate tokens that keep the output valid for the schema. Malformed JSON can't be produced at all.

Sources123

2.Defining the tool and reading the tool_use block

Setup takes three steps. First, write a JSON schema as the tool's input_schema. Second, add strict: true at the top level of the tool definition, next to name, description and input_schema. Third, handle the call. When Claude uses the tool, the response has stop_reason set to tool_use and contains one or more tool_use content blocks. Each block has an id, the tool name, and an input object that follows your schema.

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

Your code finds this block in response.content and reads input. That object is your structured record. For an extraction tool, input is already the result, so there's no real work to run on it. In an agentic loop, your code would run the operation and send the output back in a tool_result block. Strict mode also guarantees the tool name is always valid, so your dispatch code can trust it.

Sources42

3.tool_choice: auto, any, or a named tool

Defining a tool doesn't make Claude use it. The tool_choice field controls whether a call happens. In the cookbook's deliberately weak example, Claude got a sentiment tool and a calculator under auto. For an excited tweet about a meal it replied with friendly chat and called no tool. For a tweet about cats it called the calculator. Strict mode doesn't help here: it controls the shape of a tool call, not whether one is made.

any fits a document classifier that has several extraction schemas. The cookbook describes it as telling Claude "you must call a tool, but you can pick which one". A text-free response is ruled out, but Claude still chooses the schema that fits the document. Forcing a named tool is stricter. Use it when one particular extraction has to happen, for example pulling metadata before later steps depend on it.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": " ? ", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

Sources53

4.What forcing costs, and where it is rejected

With any or a named tool, the API prefills the assistant turn so that a tool call is required. As a result, Claude writes no natural-language explanation before the tool_use block, even if your prompt asks for one. Anthropic says its testing shows this should not reduce performance. If you need commentary as well as the tool call, the documented approach is to keep tool_choice at auto and add an explicit instruction in the user message, for example telling Claude to use the get_weather tool.

Forced tool use also isn't supported everywhere. In those cases any and named-tool choices fail, while auto and none still work. Two situations matter. The first is manual extended thinking, thinking: {type: "enabled"}. The second is the newest models: Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 and Claude Mythos 5.1, which return a 400 error whatever the thinking settings.

On those models, auto plus strict: true still guarantees that any tool call is schema-valid. The documentation notes that your prompt still influences which tool Claude picks under auto, so it's the prompt, not the API, that makes Claude call the extraction tool.

Sources5

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.With a forced tool choice, you can still ask Claude to explain its reasoning in text before the tool call.Why is that wrong?

   With any or a named tool, the API prefills the assistant turn, so Claude writes no natural-language text before the tool_use block. To get commentary, use auto and ask for the tool in the user message.

   Covered in What forcing costs, and where it is rejected

2. 2.tool_choice any or a named tool works with every model and every thinking mode.Why is that wrong?

   Manual extended thinking rejects both, and Claude Opus 5.5, Sonnet 5.5, Fable 5.1 and Mythos 5.1 return a 400 error. Adaptive thinking does not block forced tool use on models that support it.

   Covered in What forcing costs, and where it is rejected