CUT TOKEN BLOAT

"Keep tool descriptions short" is true and useless — it doesn't tell you which five words to cut or which field to delete. Below are the specific changes that, in practice, move the number reported by the token ledger the most, ranked roughly by impact per minute of effort. Paste your schema before and after each change to see the actual delta; don't trust intuition on this, schema token cost is not proportional to how the JSON looks on screen.

1. Write the description for "should I call this," not "how does this work." Models decide whether to invoke a tool from its name and description alone. Implementation detail, caveats, and prose about internals cost tokens on every single request and rarely change that decision. Move that content to your own docs; the schema only needs enough to disambiguate this tool from its neighbors.
2. Delete examples arrays from inputSchema unless the shape is genuinely ambiguous. Example payloads are the single most common source of schema bloat we've seen — a two-line schema can carry a fifteen-line example block that repeats field names already declared in properties. Keep one, short, only where the parameter type alone doesn't make usage obvious.
3. Flatten nesting where the extra level adds no meaning. { options: { options: { format: ... } } } costs more in brace and key overhead than a flat { format: ... } — and nested optional objects are exactly what token counters flag as "heavy." If a wrapper object exists purely for namespacing and every caller sets it, inline its fields.
4. Merge near-duplicate tools instead of registering variants. search_docs, search_code, and search_issues with near-identical schemas are three full name + description + inputSchema payloads sent on every request. One search tool with a type enum parameter is one schema, not three — and the model still gets full disambiguation from the enum values.
5. Don't restate constraints the JSON Schema keywords already enforce. If "type": "integer", "minimum": 1, "maximum": 100 is declared, the description doesn't also need "must be a whole number between 1 and 100" — that's the same constraint paid for twice, once in schema and once in prose.
6. Drop enum descriptions that just repeat the enum value. A field documented as "status: one of 'open', 'closed', 'archived'" next to an actual "enum": ["open", "closed", "archived"] is paying twice for the same three words. Describe the enum only if a value's meaning isn't obvious from its name.
7. Re-measure after every change, not just once at the end. Token cost per field is uneven — cutting a verbose description on a rarely-hit optional parameter can outweigh flattening three "obvious" nested objects. Paste the schema into the ledger after each edit instead of guessing which change mattered; the worst-offender-first ranking will tell you immediately whether you fixed the right tool.

None of the above matters until it's measured against your actual tool list. The ledger runs entirely in your browser — paste your schema, get a table ranked worst offender first, apply a fix, paste again.

→ OPEN THE TOKEN LEDGER