Claude Code First, specification version 0.1.0. The plain-language guide

Version 0.1.0. Grade R3/S4.

F4 Served MCP tool schemas were measured as a fixed cost of every session and held by a failing budget, which forced trims or argued raises

Claim

The two projects that serve MCP tools to their own agent measured the serialized tool schemas as a cost paid at the start of every session, put a ceiling on it that fails the build, and met every later addition by trimming a description or raising the ceiling with a written reason; a third project chose a CLI over MCP on the strength of one of those measurements.

Mechanism

A tool's name, description and input schema are sent to the model so that it can call the tool, whether or not the session ever does. A CLI verb reached through the shell costs nothing until it is run. So each tool, and each paragraph added to a tool's description, is a charge on sessions that never use it, and nothing surfaces the charge unless it is measured. Whether all definitions are in fact sent up front depends on the harness (H9).

Observations

• Shio. The budget file calls the tool list "the priciest fixed cost on the surface" [shio@821f18d74:shio-app/src/test/resources/token-budgets.properties#L13].

SH132 made it a measured budget held by a test: "Measured 2026.3: 1655 est. tokens over 8 tools" [shio@821f18d74:docs/CHANGELOG.md#L31]. The test then failed on a real change: adding an operation took the list "3 tokens over its 2200 ceiling" [shio@821f18d74:docs/CHANGELOG.md#L22], and a description was "trimmed instead of the ceiling raised" [shio@821f18d74:docs/CHANGELOG.md#L22]. A later tool raised it, "so the ceiling rose to 2500" [shio@821f18d74:docs/CHANGELOG.md#L369]. One feature was built with no tool at all because "a tool schema is paid on every turn of every session (P3) and a coding agent has a shell" [shio@821f18d74:docs/CHANGELOG.md#L392].

• roadkeep. RK1059 recorded "the largest every-turn surface is measured and held by nothing" [roadkeep@91754240:docs/CHANGELOG.md#L645]

and added a per-tool ceiling, since "Raised from 2600" [roadkeep@91754240:roadkeep.toml#L82] and "Raised from 2800" [roadkeep@91754240:roadkeep.toml#L87] to "characters = 2850" [roadkeep@91754240:roadkeep.toml#L95], each raise with its reason in the comment. The session total stands at "session = 69665" [roadkeep@91754240:roadkeep.toml#L232] against a reading of 69,544 [roadkeep@91754240:roadkeep.toml#L227]. The comment above it records twelve raises, each with the task that paid for it, from "Raised from 63,700" [roadkeep@91754240:roadkeep.toml#L108] to "Raised from 69425" [roadkeep@91754240:roadkeep.toml#L225] (grep -c "Raised from" over lines 96 to 232 of the file). RK1601 compared the two costs directly: "2,437 code units on the turns that open a page, against 9,939 of schema every session pays at connect" [roadkeep@91754240:docs/CHANGELOG.md#L803].

• freewilly. It serves no MCP tools. Its specification decides "CLI first; MCP only if a shell-less client ever matters" [freewilly@c1c2eaf:docs/specs/DD23-agent-first-freewilly.md#L120]

and caps any future MCP head at six tools and 1,100 schema tokens [freewilly@c1c2eaf:agent-budget.json#L256-L257]. The argument is Shio's, and says so: "The measurement is borrowed, and it is specific." [freewilly@c1c2eaf:docs/specs/DD33-mcp-is-a-second-head.md#L24]

• winwright. It serves four tools [winwright@861b82e:tools/Winwright.Mcp/Served.cs#L62-L96];

no measurement of their schema cost was found at the pin.

Independence

Two origins. Shio invented the measured tool-list budget (SH132, 2026-07-26). roadkeep's RK1059 came later from the same author, and describes itself as its own earlier argument about the resident file "made about the schema" [roadkeep@91754240:roadkeep.toml#L77]; it counts as a second origin because roadkeep measured its own surface and changed the remedy for a reason it states, a ceiling per tool rather than per list [roadkeep@91754240:roadkeep.toml#L77-L79] (grading rule 2). freewilly's decision is a copy of Shio's argument, as its own text says, and adds no origin. winwright is silent.

Counter-evidence

• The harness documentation disagrees with the mechanism as the corpus states it. Shio

and roadkeep both say the schemas are paid every session or every turn. The MCP page read on 2026-09-24 says that with tool search enabled, the default, Claude Code does not send all tool definitions to the model (H9). The measurements are of serialized size and are not in doubt; what each session actually pays under the current default is. A rule resting on this finding must name H9 and be re-checked against the harness version.

• The budget did not bound the surface in roadkeep: the session ceiling was raised twelve

times in the comment's own record, from 63,700 to 69,665. What it did was make each raise a written decision.

Grade

R3: two independent origins. S4: Shio's tool-list budget test encodes the claim, and its ledger records it failing on a real change, three tokens over, answered by a trim. The S4 concerns the size of the schema; the claim that the size is paid by every session is contested by H9.