playbook · updated 2026-10-26

Tool-schema token bloat

Agent requests carry thousands of input tokens of tool definitions on every turn; cache reads help but the schemas themselves are padded.

Why it happens

Pretty-printed descriptions, double spaces and trailing whitespace inside JSON schemas are tokens the model pays for on every call, and inconsistent formatting between callers breaks prefix caching.

Fixes

  1. The gateway minifies tool and parameter descriptions losslessly (same words, same order) and deterministically, never touching names, enums, defaults or examples; X-TokenZero-Compaction-Tokens-Saved reports the saving per request.
  2. The cache-tier guard never minifies when that would drop the prefix below the model's cache minimum, because the cache discount is worth more than the tokens.
  3. Keep the tool list stable and first in the request so the whole block is one cacheable prefix.

Start here

curl -s -X POST https://tokenzero.sh/v1/signup -d '{}'   # workspace + key, no form
npx -y @tokenzero/cli init                                # or: audits the repo, writes .env
OPENAI_BASE_URL=https://tokenzero.sh/w//v1
ANTHROPIC_BASE_URL=https://tokenzero.sh/w/
# provider keys stay in your code exactly as they are; nothing else changes

Questions

Can minification change what the model sees?
Only whitespace runs inside description strings are collapsed. Enum values, names, defaults, examples and patterns are data and are never modified.