Structured Output with Tool Use, Strict Mode and tool_choice

1.Why tool use is the structured-output channel

If you ask Claude in plain text to "reply in JSON", your code still has to parse whatever text comes back. The structured outputs documentation lists what goes wrong even with careful prompting: parsing errors from invalid JSON syntax, missing required fields, inconsistent data types, and schema violations that need error handling and retries.

Tool use avoids this. You define a tool that exists only to receive data. Anthropic's extraction cookbook defines custom tools for this purpose, getting well-structured JSON for summarization, entity extraction, sentiment analysis and text classification. Your code never has to perform an action with the tool. The arguments Claude supplies are the result, and because a JSON Schema describes those arguments, you decide the shape of the output.

The documentation also offers a second, complementary route: JSON outputs through output_config.format. This returns schema-valid JSON in a text block instead of a tool call. You can use the two separately or together in the same request. This lesson focuses on the tool-use route, because that is where the tool_choice control applies.

A schema settles the shape of the output, not the formatting of the values inside it. A field typed as string will accept "2024-01-15", "15/01/2024" and "Jan 15, 2024" equally, and source documents rarely agree on a format. That is why the schema and the prompt work as a pair. The extraction cookbook's open-ended example provides an input_schema and instructs Claude via prompting how to interact with the tool, and the tool-choice cookbook says that even when a tool is forced, you should still employ some basic prompt engineering. Put your format normalization rules in that prompt, next to the strict schema: state the date format, the currency and decimal convention, the casing for names and codes, and how to treat missing punctuation or abbreviations. The define-tools page names format-sensitive parameters as a case where input_examples help, so you can also show a normalized value in an example. The schema then guarantees the structure and the prompt makes the values consistent.

Sources1234

2.Defining an extraction tool and reading the tool_use block

A user-defined tool has three core fields: name, description and input_schema. The input_schema is a JSON Schema object defining the expected parameters. The documentation's standard example contains the three parts you reuse for extraction: typed properties, an enum that limits a field to fixed values, and a required array that separates mandatory fields from optional ones.

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

In this example, location is required. unit is optional, but if it appears it must be one of the two enum values. The description fields are part of your extraction instructions. The documentation calls detailed descriptions by far the most important factor in tool performance. It recommends at least 3–4 sentences per tool, covering what the tool does, when to use it, and what each parameter means.

When Claude calls the tool, the response has a stop_reason of tool_use and one or more tool_use content blocks. Each block has an id, the tool's name, and input, an object that conforms to the tool's input_schema. That input object is your structured data.

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

tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

Schema design: required versus optional. The required array is a promise that every extraction will carry those fields. That is the right promise for data every document has, such as an invoice number on an invoice. It is the wrong promise for data a document may lack. With strict mode the schema is enforced by constrained sampling, so a required field cannot be omitted, and if the source has no value for it the model has to put something there. The result is a fabricated value that looks exactly like a real one. The defence is to leave such fields out of required, as the weather example does with unit, so the model can simply omit them, as the tool_use block above shows. A nullable type is the other option when downstream code wants the key present but empty. The structured outputs page's API-response example declares errors as list[dict] | None for exactly that reason.

Schema design: enums that admit uncertainty and growth. An enum keeps a field to fixed values, which is what makes it useful for categorisation. The same fixed list is a trap when the source is ambiguous or the category is one you did not anticipate. Two additions solve this. Add an "unclear" value so the model has an honest answer when the document does not settle the question, instead of guessing between the listed values. And when the categories are open-ended, add an "other" value together with a separate optional detail string, for example category_other_detail, where the model writes what it actually found. Both patterns keep the enum strict, which strict mode requires, while giving the model a schema-valid way to say "none of these". Describe in the enum's description when each value applies, since the description is what the model reads to choose.

Sources4561

3.Strict mode: eliminating syntax and type errors

With a plain tool definition, input that matches the schema is expected but not guaranteed. Adding strict: true makes it a guarantee. Token sampling is constrained so that only schema-valid output can be produced, a technique the documentation calls grammar-constrained sampling. The documentation's example is a booking system that needs passengers as an integer. Without strict mode, Claude might send "two" or "2". With strict: true, the response always contains passengers: 2.

Strict tool use compiles tool schemas into grammars using the same pipeline as structured outputs. The schema uses standard JSON Schema with some limitations. The guarantees it lists are about form: tool input strictly follows the input_schema, and the tool name is always valid. The structured outputs page describes the benefits in the same terms: no more JSON.parse() errors, guaranteed field types and required fields, and no retries for schema violations. All of these are syntax and type failures. Whether the values themselves are correct is a separate question, and schema design is where you start to answer it.

Sources61

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

Defining an extraction tool does not make Claude call it. The tool_choice parameter controls how much freedom Claude has. It is part of the tool configuration that the API includes in the system prompt it builds from your tools.

auto is the default. Claude decides whether a tool is needed, so an extraction pipeline running on auto can get a plain-text reply instead of data. The tool-choice cookbook shows this. With a sentiment tool and a calculator available on auto, Claude answered one tweet in prose (stop_reason end_turn) and called the calculator for another. If your pipeline must always produce structured output, do not use auto.

any tells Claude it must call one of the provided tools but lets it choose which. This fits extraction when you have several schemas, for example one per document type, and you don't know in advance which kind of document you have. Every response is a tool call, and Claude picks the schema that fits. The cookbook's SMS assistant uses any so that it never gives a non-tool response. Even a gibberish message still produced a tool call.

A named tool, {"type": "tool", "name": ...}, takes the choice away completely. You must set type to tool and also give the tool's name. In the cookbook, once print_sentiment_scores was forced, Claude called it for every tweet, including one written to tempt it toward the calculator. Forcing is also how you control order in a multi-step pipeline. If a step such as extract_metadata must run before any enrichment tools, force that tool on the turn where it has to happen, then use a less restrictive tool_choice on later turns.

Sources436

Exam traps

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

1. 1.Once an extraction tool is provided, tool_choice auto is enough to guarantee Claude will call it.Why is that wrong?

   auto lets Claude decide whether to call a tool at all, and it may answer in plain text. To guarantee a tool call, use any, or force the tool by name.

   Covered in tool_choice: auto, any, or a named tool

2. 2.With several extraction tools and an unknown document type, you have to force one specific tool to be sure you get structured output.Why is that wrong?

   any already guarantees a tool call and still lets Claude choose the schema that matches the document. Forcing one named tool would push every document into that single schema.

   Covered in tool_choice: auto, any, or a named tool

3. 3.Marking every extraction field as required makes the output more complete and therefore more accurate.Why is that wrong?

   Strict mode guarantees required fields are present, so when the source lacks the information the model must invent a value to satisfy the schema. Fields the document may not contain belong outside required, or should be nullable, so absence is a valid answer.

   Covered in Defining an extraction tool and reading the tool_use block

4. 4.A strict schema with a date field typed as string ensures every extracted date comes back in the same format.Why is that wrong?

   The schema constrains the type and structure, not the formatting of a string's contents. Consistent formatting comes from normalization rules in the prompt, and optionally input_examples, alongside the schema.

   Covered in Why tool use is the structured-output channel