Strict Tool Use: Enforcing Schema-Valid Tool Calls

Every custom tool you give Claude is defined by a name, a description, and a JSON Schema input_schema describing the arguments. By default, Claude reads that schema and does a good job of following it — but "a good job" is a probabilistic statement. Under load, with unusual inputs, or with complex nested schemas, you will occasionally see an argument object that doesn't validate: a missing required field, an extra invented one, an enum value that isn't in your list. Strict tool use closes that gap.

What strict mode adds

Set "strict": true on a tool definition and the API guarantees that any call to that tool uses a valid tool name and an input object that matches your schema exactly. Under the hood this works like structured outputs: the model's generation is constrained by a grammar compiled from your schema, so invalid shapes cannot be produced at all. Strict tool use shares its JSON Schema rules with output_config.format (the structured-outputs parameter), and the two can be used together in the same request.

tools = [{
    "name": "create_ticket",
    "description": "Open a support ticket in the helpdesk system.",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "priority": {"type": "string",
                         "enum": ["low", "normal", "urgent"]},
        },
        "required": ["title", "priority"],
        "additionalProperties": False,
    },
}]

Note additionalProperties: false — objects in strict schemas should set it, and it is the only value the strict validator accepts for that keyword.

Schema features that strict mode rejects

Grammar-constrained generation cannot express everything JSON Schema can. Using any of the following in a strict schema returns a 400 error:

Recursive schemas and external $ref references
Numeric constraints: minimum, maximum, multipleOf
String length constraints: minLength, maxLength
additionalProperties set to anything other than false
Array constraints beyond minItems of 0 or 1

pattern regexes are allowed with limits: quantifiers, character classes, and groups work, but backreferences, lookahead/lookbehind, and word boundaries (\b) do not. The practical pattern is to keep structural validation (types, required fields, enums) in the strict schema and enforce ranges and lengths in your own handler code — which you should be doing anyway, since tool inputs drive real systems.

There are also per-request complexity caps: at most 20 strict tools, 24 total optional parameters across all strict schemas, and 16 union-typed parameters (via anyOf or type arrays).

Latency, refusals, and other operational notes

The first request with a given schema pays a grammar-compilation cost, after which the compiled grammar is cached automatically for 24 hours from last use. Changing the schema or the tool set invalidates that cache; changing only a tool's name or description does not. Design schemas to be stable and tweak wording freely.

Two response cases still need handling. A safety refusal returns HTTP 200 with stop_reason: "refusal" — you are billed, and output may not match any schema. And stop_reason: "max_tokens" can leave a tool call truncated mid-argument; retry with a higher max_tokens. See the stop reasons article for the full branching logic. The Python SDK's client.messages.parse() helper with Pydantic models will auto-transform unsupported schema constraints and validate responses client-side.

Rule of thumb: strict mode guarantees the shape of arguments, not their sense. {"priority": "urgent"} is schema-valid even when the ticket isn't urgent. Keep business validation in your handler, and return failures as tool_result blocks with "is_error": true so Claude can correct course.

Platform availability

Structured outputs and strict tool use are generally available on the Claude API, Claude Platform on AWS, Amazon Bedrock, and Google Vertex AI, and in beta on Microsoft Foundry. One incompatibility to remember: structured outputs cannot be combined with citations in the same request.

Where to go next

Strict mode covers the model's side of the contract; tool choice controls whether and which tools get called, and tool result errors covers the failure path. The feature matrix shows platform support across the board.

Sources

← All articles