Summary

Some customer MCP tools expose large input schemas that exceed Codex's compact schema budget even after description stripping. Today, the final compaction pass collapses complex schemas starting at depth 2, which can erase important shallow call structure such as small anyOf branches, required fields, and help-mode entry points. In one reported case, this degraded a tool schema into query: any | any, leaving the model without enough structure to discover the required help call.

This change raises the deep-schema collapse boundary from depth 2 to depth 3. That preserves one additional layer of the tool contract while still collapsing deeper expensive subtrees to {} when a schema remains over budget.

What Changed

• Increased MAX_COMPACT_TOOL_SCHEMA_DEPTH from 2 to 3.
• Updated the schema compaction traversal test to assert the new collapse boundary.
• The resulting compacted shape keeps useful shallow structure, for example:
  • top-level argument names
  • shallow anyOf branches
  • required object fields
  • nested property names one level deeper than before

Validation

• Ran just test -p codex-tools: 81 tests passed.
• Ran a golden schema corpus comparison over 214 discovered tool input schemas under golden_schemas/*/mcp_tools/*/input_schema.json.
  • Depth 2 and depth 3 had identical percentile token counts across the corpus.
  • Both ended with 0 / 214 schemas over 1k tokens.
  • Both ended with 0 / 214 schemas over the 4,000-byte compact JSON budget.
  • Only one golden schema changed, increasing from 49 to 56 tokens, so this does not appear to introduce a meaningful corpus-wide regression.

Corpus percentile results: