Claude Code First, specification version 0.1.0. The plain-language guide
Version 0.1.0. Grade R2/S2.
F8 Where the consuming agent had a shell, Shio kept new capabilities off its MCP tool list and on its CLI, because the list is paid before any call
| Field | Value |
|---|---|
| Status | active |
| Topic | Context economy and agent prose |
| Grade | R2/S2 |
| Cases | Shio |
| Contrary | winwright |
| Harness facts | H9 |
Claim
Shio decided on three separate occasions to ship a capability as a CLI verb and not as an MCP tool, each time because a tool's schema is a charge on every session while a verb costs nothing until it runs, and a coding agent can reach a verb through its shell; freewilly adopted the same order as policy, and winwright chose MCP where the schema was what kept the caller's input correct.
Mechanism
A tool is offered to the model by its name, description and input schema, which are sent whether or not the session calls it. A CLI verb is reached through a shell tool the agent already has, and costs context only when it is run and its output read. So for an agent with a shell, each capability placed on the tool list adds a fixed charge that a verb does not, and the tool buys something only for a client with no shell, or where the schema does work a verb cannot, such as refusing a malformed input before it is sent. How much of the list a session is sent depends on the harness (H9).
Observations
- Shio. Instance memory shipped with "No MCP tool" [shio@821f18d74:docs/CHANGELOG.md#L392],
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] (SH114, 2026-07-26, [shio@f3bc1b51e]). The handoff report followed the next day with no tool either, since "the artifact's consumer is a human, so per-turn schema would be paid for something the agent hands to someone else" [shio@821f18d74:docs/CHANGELOG.md#L135] (SH104, [shio@3f6f2bd6a]). Snapshots stayed off the instance: "raster stays in the CLI, where the agent has a shell and the human opens a local PNG" [shio@821f18d74:docs/CHANGELOG.md#L1096] (SH265). The cost behind all three is the measured tool-list budget of F4.
- freewilly. It serves no MCP tools of its own and decides "CLI first; MCP only if a shell-less client ever matters" [freewilly@c1c2eaf:docs/specs/DD23-agent-first-freewilly.md#L120],
on an argument it says it took from Shio: "The measurement is borrowed, and it is specific." [freewilly@c1c2eaf:docs/specs/DD33-mcp-is-a-second-head.md#L24]
- winwright (contrary). It serves four MCP tools [winwright@861b82e:tools/Winwright.Mcp/Served.cs#L62-L96]
so that "the format arrives as a schema rather than as prose somebody loaded and then typed a key out of" [winwright@861b82e:README.md#L85-L86], after it recorded that "the schema of a case arrives as flag names typed from memory" [winwright@861b82e:docs/CHANGELOG.md#L347] and chose to "give the tools the loader's own schema" [winwright@d678d09]. Its consumers are coding agents with a shell, so the difference is not the shell but the input: a structured document that the served schema validates.
Independence
One origin, Shio, seen on three occasions separated in time (SH114 on 2026-07-26, SH104 on 2026-07-27, SH265 later), which is recurrence within one project. freewilly's policy is a copy of Shio's argument by its own statement and adds no origin (grading rule 2). winwright's contrary choice is its own.
Counter-evidence
- Shio's own first law orders the other way. "every capability lands MCP → files/CLI → REST → console" [shio@821f18d74:agents.md#L20].
The law serves clients without a shell, which the three decisions set aside because their consumers had one; the finding is scoped to that case and does not contradict the law for the other.
- winwright, above: where the input is a structured document, the schema was the
remedy for a recorded failure, and a verb would have carried the format as prose.
- The harness disputes the cost. With tool search on, the default read on 2026-09-24,
Claude Code does not send every tool definition up front (H9), so the fixed charge each decision avoided may be smaller than the measurements in F4 say.
Grade
R2: three decisions in one project, on different capabilities and different days. S2: each is a ledger entry recording the decision and its reason; the cost it rests on is measured in F4, but no check fails when a capability is placed on the list instead of the CLI, so the placement itself is not measured. The contrary observation in winwright is explained by the kind of input, which is a stated property a rule can be scoped by.