Module context_overhead 

Honest accounting of the fixed per-turn context lean-ctx injects (GitHub #361).

Three components ride every request and — on a provider WITHOUT prompt caching — are re-billed on every turn:

• the exposed MCP tool schemas (description + input schema of each tool),
• the MCP server instructions block, and
• the rules block lean-ctx writes into the host’s instruction file (CLAUDE.md / AGENTS.md).

lean-ctx gain measures compression on lean-ctx-touched reads — its denominator is lean-ctx traffic, not the provider bill. On a phase-isolated / non-caching workload (separate process per phase, no provider cache) the cached-re-read lever has no surface, so the headline can read net-positive while the bill moved net-negative. Surfacing this overhead — and stating the denominator — keeps the meter honest.

Net bill impact ≈ gross_saved_tokens − total_tokens() × turns.

Structs

ContextOverhead

A measured breakdown, in tokens, of the per-turn context lean-ctx adds.

Functions

tool_tokens

Description + input-schema tokens for one tool definition — exactly the two fields a client re-sends in every request’s tool list.