F409 Measured on the same canonical tasks, an agent path shaped to the task cost a fraction of the tokens of the generic interface, and the gap came from fewer reads rather than from the transport

Field	Value
Status	active
Topic	Environment, permissions, and agent-facing products
Grade	R3/S4
Cases	Shio, freewilly
Contrary	none
Harness facts	none

Claim

The two projects that benchmarked named tasks through their agent surface and through the generic interface the same system already offered found the shaped path cheaper in tokens by a measured ratio, held that ratio and the task's own cost by a test, and traced the advantage to fewer and narrower reads, not to the transport, which on both sides was HTTP.

Mechanism

A generic interface built for a user interface answers in entities keyed by id: to act, the agent lists, resolves ids, reads whole records and writes one at a time, and every intermediate payload passes through its context. A path shaped to the task does that work where the data is and answers the question asked, such as a lint that names the defective post instead of a read of every candidate. The saving is in the number and width of the reads, so it survives a change of transport and shrinks when the generic side itself gets leaner. A per-response ceiling cannot see a task that got dearer by taking more calls, each under its ceiling; a benchmark over the whole task can.

Observations

Shio. SH112 runs four canonical jobs twice, "once over the agent surface and once over the same instance's id-keyed console/CDA endpoints" [shio@821f18d74:docs/CHANGELOG.md#L388],

asserting calls, tokens and both ratios, while "wall clock is recorded and never asserted" [shio@821f18d74:docs/CHANGELOG.md#L388]. The first run found tokens "cheaper on the agent path, so the ≈10× target is met on three tasks of four" [shio@821f18d74:docs/CHANGELOG.md#L389]. The advantage then fell as the console's own REST reads were fixed: "Block M measured 3.8x-23.3x. Block N measures 2.6x-12.6x against an unchanged agent path" [shio@821f18d74:shio-app/src/test/resources/token-budgets.properties#L373], after "SH117 retired the id-keyed, entity-shaped" [shio@821f18d74:shio-app/src/test/resources/token-budgets.properties#L376] endpoint the console used, and the budget file concludes that the advantage "was never the protocol — it was the console reads being entity-shaped" [shio@821f18d74:shio-app/src/test/resources/token-budgets.properties#L387]. SH164 attributed what remained to its sources, because "one number per task could no longer distinguish" [shio@821f18d74:docs/CHANGELOG.md#L478] a cheaper protocol from a fat console: "The lint carries the token claim and is the only source that scales without bound" [shio@821f18d74:docs/CHANGELOG.md#L479], and "Batching buys turns, not bytes" [shio@821f18d74:docs/CHANGELOG.md#L479]. The shaped surface is itself HTTP, for example "GET /api/v2/agent/resolve" [shio@821f18d74:docs/CHANGELOG.md#L37]. The latest recorded run reads 2.8x to 10.5x in tokens [shio@821f18d74:shio-app/src/test/resources/token-budgets.properties#L416-L420].

freewilly. One canonical task, "What the canonical task costs through the transport an agent reaches today: a container list" [freewilly@c1c2eaf:agent-budget.json#L42],

measured 6 calls and 11,711 tokens over the Docker Engine API [freewilly@c1c2eaf:agent-budget.json#L47-L50] against 4 calls and 812 tokens through the shaped verbs [freewilly@c1c2eaf:agent-budget.json#L82-L86], a token ratio of 14.4 [freewilly@c1c2eaf:agent-budget.json#L93], asserted by AgentBudgetTests [freewilly@c1c2eaf:tests/FreeWilly.Preflight.Tests/AgentBudgetTests.cs#L634-L636]. The file notes that the Docker command line is dearer than the API it measured: "an agent going through the CLI pays several times this for the same entity" [freewilly@c1c2eaf:agent-budget.json#L66]. The assertion fired on a real change: "771 became 814 when DD96 widened the doctor's mounts row. The gate caught it on the commit" [freewilly@c1c2eaf:agent-budget.json#L113].

Independence

Two origins. Shio's SH112 is the earliest, on 2026-07-26 [shio@f3bc1b51e]. freewilly adapts Shio's design laws and says its measurement of tool schemas is borrowed, "The measurement is borrowed, and it is specific." [freewilly@c1c2eaf:docs/specs/DD33-mcp-is-a-second-head.md#L24], but its canonical task, fixtures and baseline are its own, and it changed the benchmark in response to its own failure: a band in which a "response that grew by 100 tokens landed inside it silently" [freewilly@c1c2eaf:agent-budget.json#L109] was replaced by exact figures (DD78). Under the copy rule it counts as a second origin, as F406 counts it for the per-surface ceilings.

Counter-evidence

The ratio is partly a measure of the baseline. Shio's advantage fell by more than half

with no change to the agent path, because the generic side was improved; the file says the floors "drop with the measurement rather than being defended" [shio@821f18d74:shio-app/src/test/resources/token-budgets.properties#L406]. A ratio reported without its baseline overstates what the shaped surface is worth.

Calls fell far less than tokens. Shio's tool-call target was "not met anywhere" [shio@821f18d74:docs/CHANGELOG.md#L389],

and freewilly's call ratio is 1.5 [freewilly@c1c2eaf:agent-budget.json#L92].

The benchmarks can measure their own fixtures. Shio found its attribution figures

order-dependent, since "addressing read" [shio@821f18d74:docs/CHANGELOG.md#L473] 26.2x or 11.8x depending on which test ran first, and freewilly's gate went red on a date in a fixture with no commit to blame [freewilly@c1c2eaf:agent-budget.json#L137-L139]. Both had to isolate their inputs before a red meant a regression.

Tokens are estimated at four characters each in both projects, and both baselines were

written by the same author as the surface they are compared with.

Grade

R3: two independent origins, Shio and freewilly. S4: freewilly's canonical-task assertion failed on the commit that widened a response by 43 tokens, which is a check that encodes the task's cost seen to fire on a real change; Shio's benchmark reaches S3 with counted figures across four runs, and its red run was a fixture confound, not a regression. The claim that the transport does not decide the cost rests on Shio's shaped surface being HTTP itself and on freewilly's note about the command line; neither project benchmarked the same shaped surface over two transports.