feat: best-effort compact large tool schemas (#23904)

## Why

The `dev/cc/ref-def` branch preserves richer JSON Schema detail for
connector tools, including `$defs` and nested shapes. That improves
fidelity, but it pushes the largest connector schemas well past the
intended tool-schema budget. This PR adds a best-effort compaction pass
for unusually large tool input schemas so the p99 and max tails stay
small while ordinary schemas are left alone.

## What Changed

- Added best-effort large-schema compaction in
`codex-rs/tools/src/json_schema.rs` after schema sanitization and
definition pruning.
- Compaction runs as a waterfall only while the compact JSON budget
proxy is exceeded:
  1. Strip schema `description` metadata.
  2. Drop root `$defs` / `definitions`.
  3. Collapse deep nested complex schema objects to `{}`.
- Kept top-level argument names and immediate schema shape where
possible.

## Corpus Results

Scope: 2,025 schemas under `golden_schemas`, all parsed successfully.
Token count is `o200k_base` over compact JSON from
`parse_tool_input_schema`.

| Percentile | Before `origin/main` `4dbca61e20` | After branch
`dev/cc/ref-def` `f9bf071758` | After this PR |
|---|---:|---:|---:|
| p0 | 9 | 9 | 9 |
| p10 | 59 | 63 | 63 |
| p25 | 81 | 86 | 86 |
| p50 | 114 | 127 | 125 |
| p75 | 174 | 205 | 202 |
| p90 | 295 | 335 | 322 |
| p95 | 391 | 526 | 422 |
| p99 | 794 | 1,303 | 689 |
| max | 2,836 | 3,337 | 887 |

After this PR, `0 / 2,025` schemas are over 1k tokens.

### Compaction Savings

These are cumulative waterfall stages over the same corpus. Later passes
only run for schemas that are still over the compact JSON budget proxy.

| Stage | Total tokens | Step savings | Schemas changed by step |
|---|---:|---:|---:|
| No compaction | 391,862 | - | - |
| Strip schema `description` metadata | 350,961 | 40,901 | 66 |
| Drop root `$defs` / `definitions` | 340,683 | 10,278 | 13 |
| Collapse deep complex schemas to `{}` | 335,875 | 4,808 | 6 |
This commit is contained in:
Celia Chen authored and GitHub committed 2026-05-22 01:26:17 +00:00
1 parent 7e802b22f1
commit 464ab40dfa
2 files changed
+553

No files matched your search

+387
View File
@@ -779,6 +779,393 @@ fn parse_tool_input_schema_preserves_explicit_enum_type_union() {
);
}
fn many_string_properties(count: usize) -> serde_json::Map<String, serde_json::Value> {
(0..count)
.map(|index| {
(
format!("field_{index:03}"),
serde_json::json!({ "type": "string" }),
)
})
.collect()
}
#[test]
fn parse_large_tool_input_schema_stops_after_descriptions_when_under_budget() {
let schema = parse_tool_input_schema(&serde_json::json!({
"type": "object",
"description": "x".repeat(4_500),
"properties": {
"metadata": {
"$ref": "#/$defs/metadata"
}
},
"$defs": {
"metadata": {
"type": "string",
"description": "Metadata value"
}
}
}))
.expect("parse schema");
assert_eq!(
serde_json::to_value(schema).expect("serialize schema"),
serde_json::json!({
"type": "object",
"properties": {
"metadata": {
"$ref": "#/$defs/metadata"
}
},
"$defs": {
"metadata": {
"type": "string"
}
}
})
);
}
#[test]
fn parse_large_tool_input_schema_ignores_dropped_metadata_for_budget() {
let schema = parse_tool_input_schema(&serde_json::json!({
"type": "object",
"properties": {
"event": {
"type": "object",
"title": "Calendar event",
"properties": {
"recurrence": {
"type": "object",
"examples": [
{
"payload": "x".repeat(4_500)
}
],
"properties": {
"pattern": {
"type": "string",
"title": "Recurrence pattern"
}
}
}
}
}
}
}))
.expect("parse schema");
assert_eq!(
serde_json::to_value(schema).expect("serialize schema"),
serde_json::json!({
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"recurrence": {
"type": "object",
"properties": {
"pattern": {
"type": "string"
}
}
}
}
}
}
})
);
}
#[test]
fn parse_large_tool_input_schema_stops_after_dropping_root_definitions_when_under_budget() {
let schema = parse_tool_input_schema(&serde_json::json!({
"type": "object",
"description": "x".repeat(4_500),
"properties": {
"event": {
"type": "object",
"description": "Calendar event",
"properties": {
"recurrence": {
"type": "object",
"description": "Recurrence settings",
"properties": {
"pattern": {
"type": "string",
"description": "Recurrence pattern"
}
}
}
}
},
"metadata": {
"$ref": "#/$defs/metadata"
}
},
"$defs": {
"metadata": {
"type": "object",
"description": "metadata object",
"properties": many_string_properties(/*count*/ 300)
}
}
}))
.expect("parse schema");
assert_eq!(
serde_json::to_value(schema).expect("serialize schema"),
serde_json::json!({
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"recurrence": {
"type": "object",
"properties": {
"pattern": {
"type": "string"
}
}
}
}
},
"metadata": {}
}
})
);
}
#[test]
fn parse_large_tool_input_schema_strips_descriptions_without_removing_description_property() {
let schema = parse_tool_input_schema(&serde_json::json!({
"type": "object",
"description": "x".repeat(4_500),
"properties": {
"description": {
"type": "string",
"description": "User-facing description value"
},
"metadata": {
"type": "object",
"description": "Metadata object",
"properties": {
"label": {
"type": "string",
"description": "Metadata label"
}
}
},
"tags": {
"type": "array",
"description": "Tag list",
"items": {
"type": "string",
"description": "Tag value"
}
},
"extras": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "Extra value"
}
},
"choice": {
"description": "Choice value",
"anyOf": [
{
"type": "string",
"description": "String choice"
},
{
"type": "number",
"description": "Number choice"
}
]
}
}
}))
.expect("parse schema");
assert_eq!(
serde_json::to_value(schema).expect("serialize schema"),
serde_json::json!({
"type": "object",
"properties": {
"choice": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"description": {
"type": "string"
},
"extras": {
"type": "object",
"properties": {},
"additionalProperties": {
"type": "string"
}
},
"metadata": {
"type": "object",
"properties": {
"label": {
"type": "string"
}
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
}
})
);
}
#[test]
fn parse_large_tool_input_schema_preserves_object_enum_literal_descriptions() {
let schema = parse_tool_input_schema(&serde_json::json!({
"type": "object",
"description": "x".repeat(4_500),
"properties": {
"choice": {
"enum": [
{
"description": "first literal",
"id": 1
},
{
"description": "second literal",
"id": 2
}
]
}
}
}))
.expect("parse schema");
assert_eq!(
serde_json::to_value(schema).expect("serialize schema"),
serde_json::json!({
"type": "object",
"properties": {
"choice": {
"type": "string",
"enum": [
{
"description": "first literal",
"id": 1
},
{
"description": "second literal",
"id": 2
}
]
}
}
})
);
}
#[test]
fn collapse_deep_schema_objects_traverses_schema_children() {
let mut schema = serde_json::json!({
"type": "object",
"properties": {
"object_parent": {
"type": "object",
"properties": {
"complex": {
"type": "object",
"properties": {
"leaf": { "type": "string" }
}
},
"scalar": {
"type": "string"
}
}
},
"array_parent": {
"type": "array",
"items": {
"type": "object",
"properties": {
"leaf": { "type": "string" }
}
}
},
"map_parent": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"leaf": { "type": "string" }
}
}
},
"union_parent": {
"anyOf": [
{
"type": "object",
"properties": {
"leaf": { "type": "string" }
}
},
{ "type": "string" }
]
}
}
});
super::collapse_deep_schema_objects(&mut schema, /*depth*/ 0);
assert_eq!(
schema,
serde_json::json!({
"type": "object",
"properties": {
"object_parent": {
"type": "object",
"properties": {
"complex": {},
"scalar": {
"type": "string"
}
}
},
"array_parent": {
"type": "array",
"items": {}
},
"map_parent": {
"type": "object",
"additionalProperties": {}
},
"union_parent": {
"anyOf": [
{},
{ "type": "string" }
]
}
}
})
);
}
#[test]
fn parse_tool_input_schema_preserves_string_enum_constraints() {
// Example schema shape: