Token economics

Every tool name, description and schema is context the model pays for on every planning turn. Every response field is context it pays for on every observation. MCP Fusion treats both as a budget, with features that spend deliberately and a profiler that finds the leaks.

Descriptions: TOON

.toonDescription() replaces the prose description with a pipe-delimited tabular form generated from the action schema:

billing actions|desc|required
get_invoice|Retrieve an invoice by ID|id
refund|Refund an invoice|id,amount_cents
list_invoices|List the tenant invoices|-

The agent reads a table in roughly half the tokens of the same information in sentences. It is generated from the schema, so it cannot drift: change a required field and the table changes.

Responses: limit, select, groups

Three levers, in order of impact:

.agentLimit(max) caps a collection and, when it truncates, injects a corrective first block:

📊 Summary: Dataset truncated. 50 shown, 4200 hidden. Use filters to narrow results.

The model is told what happened and what to do, instead of silently reasoning over a partial list.

.enableSelect() adds a _select argument whose enum is the union of root schema fields. The data block ships only the requested fields, while UI blocks and rules still see the full object. A wide invoice model becomes a five-field answer when the question was small.

Grouping trades schema size for name count: a namespace of twelve actions becomes one tool with a discriminator, and the menu shrinks accordingly. See Tool exposition.

.toonSuccess(data) applies the same table encoding to a uniform collection response, collapsing repeated keys into one header row.

FSM compaction

A state-bound connector can ship a compactDescription() while the machine is in its initial state and reveal the full description later. The menu the agent reads at the start of the workflow is smaller than the one it reads where the risky actions live. See FSM state gating.

The profiler

The framework ships a static analyzer because response inflation is invisible until the bill arrives. profileResponse splits a response into payload and overhead blocks, computes the overheadRatio, and classifies risk:

with advisories such as COGNITIVE OVERLOAD, HIGH TOKEN DENSITY and OVERHEAD WARNING (default overhead ceiling around 30% of the response). The same module classifies a tool's static inflation risk from its schema: an unbounded collection plus more than ten fields is critical, unbounded alone is high, more than twenty fields is medium. That classification is hashed into the capability lockfile, which means an inflation regression fails CI instead of shipping quietly. See Contracts.

Token estimates use the standard heuristic of roughly one token per 3.5 characters on JSON-shaped text, which is accurate enough to compare variants and never presented as a provider count.

The budget order of operations

1. Group actions so the menu is small
2. Turn on _select for wide entities
3. Set .agentLimit() on every collection
4. Use .toonDescription() and .toonSuccess() for uniform shapes
5. Compact descriptions under FSM states that do not need the full story
6. Run the profiler in CI and treat a risk escalation as a regression

Next steps

• Wire format: what each block costs
• Contracts: the lockfile that locks the budget
• Tool exposition: grouping mechanics