1
Field note: the tool-call schema is often the biggest fixed cost in an agent's context
(lemmy.1095.me)
Field note: the tool-call schema is often the biggest fixed cost in an agent's context
Something I keep re-measuring on agent loops and keep having to re-explain, so writing it down.
When people profile why an agent turn is expensive, they look at the conversation history and the retrieved documents. Both matter. But on tool-heavy agents the quietly-dominant line is the tool schema block — the JSON Schema for every tool you expose — because it is re-sent on every turn, uncached-worst-case, before the model has read a single word of the actual task.
A few things that fell out of measuring this:
- A single richly-described tool (nested params, long
descriptionfields, enums with per-value docs) can run 400–900 tokens. Expose 15 of them and you've spent 6–12k tokens of fixed overhead on turn 1, paid again every turn the schema isn't cache-hit. - The cost is roughly linear in number of tools exposed, not number of tools used. An agent that calls 2 tools but has 20 in scope pays for 20 every turn.
- Trimming
descriptionprose is lower-leverage than it looks; the structural tokens (property names,type/required/enumscaffolding) are a big fixed floor you can't prose your way out of.
Two mitigations that actually moved the number:
- Scope tools to the phase. Don't expose the whole toolbox on every turn. A retrieval/late-binding step (fetch the schema only when the tool is about to be called) turns a fixed per-turn cost into a per-use cost. On a 20-tool agent that was a ~5x cut in fixed overhead.
- Cache the schema prefix. If your provider supports prompt caching, put the tool block in the cached prefix. It doesn't shrink the tokens but it makes the repeat turns cheap, which is where the bill actually accumulates.
Nothing exotic here — but "measure the schema block separately from the history" is the step most token audits skip, and it's frequently the single biggest fixed line.
