One row of SQL is the whole contract for a capability, and the 892nd took 3.1 seconds
Every column of the directory row that defines a callable capability on this build, the four runner types with a real row of each, why secrets are named but never stored, and the verbatim POST, receipt and delete that proved a brand-new capability live in 3.126 seconds.
A capability on this build is one row in a SQLite table on Cloudflare D1 called directory. The row is the whole contract: what the capability is, how to call it, what comes back, which credential it needs, and who is allowed to run it. There is no companion file, no registration call in application code, and no deploy step. On 2026-07-26 the table held 891 rows.
Scope note: this article covers the directory table's row shape only — the contract for API calls, shell commands, agents and other executable capabilities. It is one of at least two object families on this build; content (articles, their claims, their revisions) lives in a separate articles/article_slots pair of tables with its own resolver, not in directory. 892 rows, 8 of them MCP draws that line explicitly.
Every field below is published rather than paraphrased, every runner type has a real row printed as stored, and the failure strings are copied out of the code that emits them. The volume argument — why holding 891 tool definitions in a model's context is the wrong shape — is tooling as data. The call sequence around a row is the four-step loop. The Model Context Protocol view of the same rows is MCP as a projection.
Evidence status
Observed marks first-party measurements or runtime receipts from the named environment. Derived marks arithmetic calculated from cited inputs. Specified marks vendor or standards documentation. Implemented and deployed name code and live-state evidence, respectively. Reproduced means the stated procedure was rerun. Externally attested marks operator reports; those reports show that an experience occurred, not that it is universal.
Eighteen columns, of which six existed on the first day
The table as it stands in production. Read it back yourself:
cd /Users/owner/miscsubjects-pages
npx wrangler d1 execute loop-content-spine --remote \
--command "SELECT sql FROM sqlite_master WHERE name='directory';"CREATE TABLE directory (
key TEXT PRIMARY KEY,
type TEXT NOT NULL CHECK (type IN ('fn','http','agent','flow')),
target TEXT,
auth TEXT,
content TEXT,
updated_at TEXT NOT NULL
, category TEXT, allowed_categories TEXT, seq INTEGER, enabled INTEGER DEFAULT 1,
planner_visible INTEGER DEFAULT 1, planner_rank INTEGER DEFAULT 100,
input_schema TEXT, examples TEXT, sensitive INTEGER DEFAULT 0, runner TEXT,
includes TEXT, created_at TEXT)The first six columns came from migrations/0007_directory.sql:1-8. Everything after the closing parenthesis of the original statement is an ALTER TABLE bolted on later, which is why the SQL reads the way it does.
| Column | Type · default | Required | What it holds | Real value |
|---|---|---|---|---|
key | TEXT, primary key | yes | The invocation name. Unique by constraint, uppercase by convention. | GROK_MODELS |
type | TEXT, CHECK IN ('fn','http','agent','flow') | yes | Decides how target and content are read. The only constrained column in the table. | http |
target | TEXT | by type | fn: a function name. http: "METHOD url". agent: a model id. flow: empty. | GET https://api.x.ai/v1/models |
auth | TEXT | no | The name of an environment variable and how to apply it. Never a secret value. | bearer:GROK_API_KEY |
content | TEXT | yes, gated | fn/http: comment docstring plus the argument template. agent: the system prompt. flow: the step DSL. | see the four rows below |
updated_at | TEXT, NOT NULL | yes | ISO timestamp of the last write. The only change marker on the row. | 2026-06-10 02:22:52 |
category | TEXT | no | Grouping label. 110 distinct values live. | grok |
allowed_categories | TEXT | no | On agent rows: the categories that agent's tool listing is restricted to, or *. | * |
seq | INTEGER | no | Manual ordinal used to pin a row to a position. Null for almost every row. | null |
enabled | INTEGER, default 1 | no | 0 hides the row from every projection. 13 rows are disabled. | 1 |
planner_visible | INTEGER, default 1 | no | Whether planners and the MCP projection list it. | 1 |
planner_rank | INTEGER, default 100 | no | Sort weight for candidate selection. Lower wins. | 100 |
input_schema | TEXT | no | JSON Schema string, used when the row is projected as a typed tool. 256 rows carry one. | null |
examples | TEXT | no | JSON array of worked argument strings. 63 rows carry one. | `["37.77\ |
sensitive | INTEGER, default 0 | no | 1 routes the call through the watcher before it runs. 227 rows are marked. | 0 |
runner | TEXT | no | Overrides the runner inferred from type. 301 rows have a value. | null |
includes | TEXT | no | On agent rows: comma-separated prompt-block keys composed in front of content at runtime. | BLOCK_VOICE,BLOCK_REASONING_A |
created_at | TEXT | no | Present in the live table. No migration in the repo adds it. | null on old rows |
row_num | computed, not stored | — | 1-based position in the canonical ordering, attached by the read path. | 412 |
Column provenance, by migration: 0012_directory_category.sql:7-9 added category, allowed_categories, seq. 0018_planner_columns.sql:5-9 added the five planning and schema columns. 0064_substrate.sql:5 added runner. 0118_add_directory_sensitive.sql:2 added sensitive. 0183_prompt_blocks.sql:2 added includes. created_at has no such line — grep -rn "ALTER TABLE directory" --include="*.sql" . returns fourteen matches and none of them mention it, so that column entered the production table out of band. A rebuild should add it in a migration.
Two columns exist in the table but cannot be written through the REST surface. The PATCH handler's field allow-list at functions/api/directory/[key].js:223 contains thirteen names, and neither sensitive nor runner is one of them:
curl -sS -X PATCH "https://miscsubjects.com/api/directory/ZZ_TEST_TEMPERATURE" \
-H "x-terminal-key: $TERMINAL_KEY" -H 'content-type: application/json' \
-d '{"runner":"edge"}'
# {"error":"no recognized fields"} HTTP 400The type column decides everything else, and it has exactly four legal values
fn runs a function inside the build's own Worker. http calls somebody else's API. agent sends content to a model as a system prompt. flow chains other rows. The dispatcher branches on the column at functions/api/dispatch.js:1145-1156; a fifth value is rejected by the CHECK constraint before that branch is reached.
| Type | Live rows | target holds | content holds | Pick it when |
|---|---|---|---|---|
fn | 480 | a key into the runner map | a JSON array template of the function's positional arguments | the work is code you control and want to run at the edge |
http | 303 | "METHOD url", with $1 slots | the request body template, or nothing for GET | the work is an existing API |
agent | 57 | a model id, e.g. grok-4.3 or gw:openai/gpt-4.1-mini | the system prompt | the work needs judgement, not a deterministic call |
flow | 51 | empty string | steps separated by >, each KEY: args | the work is two or more capabilities in order |
Counted live:
npx wrangler d1 execute loop-content-spine --remote \
--command "SELECT type, COUNT(*) AS n FROM directory GROUP BY type ORDER BY n DESC;"
# fn 480 | http 303 | agent 57 | flow 51 → 891One real row of each type, exactly as stored.
fn — NOW
key NOW | type fn | target now | auth (null) | category time
content # Return the current time from the build clock in Pacific time (America/Los_Angeles).
# WHEN_TO_USE: any object or model that needs the current date or time.
# ARGS: none
# EX: [NOW][/NOW]
# OUTPUT: { now, today, time, zone, iso } — Pacific-offset ISO; today is the Pacific calendar date.Every line of content beginning with # is stripped before execution by stripDocs at dispatch.js:440-452. What is left is the executable payload. NOW has no payload line, so runFn falls back to the default template ["$1"] at dispatch.js:1170.
http — GROK_MODELS
key GROK_MODELS | type http | category grok | auth bearer:GROK_API_KEY
target GET https://api.x.ai/v1/models
content # WHAT: List every model on the xAI API. No args
# WHEN_TO_USE: you need to grok models
# ARGS: see content
# EX: [GROK_MODELS][/GROK_MODELS]
# List every model on the xAI API. No args.agent — PROMPT_LAB_AGENT
key PROMPT_LAB_AGENT | type agent | target grok-4.3 | auth bearer:GROK_API_KEY
content You are a friendly peptide concierge (LAB TEST v1). One warm sentence,
then end with [REPLY]your text[/REPLY].An agent row with includes composes shared prompt blocks in front of content at runtime: ROUTER carries BLOCK_VOICE,BLOCK_IMESSAGE,BLOCK_EMOJI,BLOCK_ROUTING,BLOCK_ARA, so the voice rules are written once and referenced by six rows.
flow — BLOOIO_FINISH
key BLOOIO_FINISH | type flow | target (empty)
content # Phase C of the inbound turn: given the full agent output text in $1, extract the
# LAST [REPLY], send via blooio to $2, return the send result.
# $1=agent output text. $2=recipient phone.
LAST_REPLY_OF: $1
> SEND_BY_CHANNEL: blooio|$2|$PREVThe flow reader splits on a top-level > and runs each step against the previous step's output, bound to $PREV (dispatch.js:1686-1731). A step is KEY: body. Appending => NAME binds that step's output to $NAME for later steps. A { A: x | B: y } block fans out concurrently. A step whose output starts with ERR: stops the flow.
Arguments are one string, split on the pipe character, and that is a deliberate trade
The invocation body is a single string. The dispatcher splits it on | and hands the pieces to the runner as args:
const args = String(body == null ? '' : body).split('|');That is dispatch.js:1144. In a template, $1 is the first piece, $2 the second. Two arguments:
curl -sS -X POST https://miscsubjects.com/api/dispatch \
-H "x-terminal-key: $TERMINAL_KEY" -H 'content-type: application/json' \
-d '{"key":"ZZ_TEST_TEMPERATURE","body":"37.77|-122.42"}'$1 becomes 37.77, $2 becomes -122.42, and the target GET https://api.open-meteo.com/v1/forecast?latitude=$1&longitude=$2¤t=temperature_2m resolves to a real URL.
The obvious break: a pipe inside an argument. A JSON body, a prompt, a shell command, a sentence with a pipe in it — the naive split shreds all of them. The handled form is $N+, which rejoins arguments N through the end with the pipe put back:
if (/^\d+\+$/.test(key)) {
const v = args.slice(+key.slice(0, -1) - 1).join('|');
return raw ? v : escFor(mode, v);
}dispatch.js:171-175. So a row that takes a JSON blob as its last argument uses $2+, not $2. DIR_PATCH is the live example — it edits another row, so its second argument is arbitrary JSON:
key DIR_PATCH
type http
target PATCH https://miscsubjects.com/api/directory/$1
content # ARGS: key | json_body
# EX: [DIR_PATCH]ROUTER|{"content":"new prompt text"}[/DIR_PATCH]
$2+Called as body: 'ROUTER|{"content":"a|b"}', the key is ROUTER and the body template $2+ receives {"content":"a|b"} intact. The rule that follows: only the last argument of a row may contain a pipe, and only if the template uses $N+. A row with two free-text arguments in the middle of its signature is unrepresentable, and that is the real cost of the format.
Substitution is escape-aware. subVars at dispatch.js:156-201 takes a mode — url, json-string or raw — and escapes each value for the position it lands in, so a quote inside an argument cannot break out of a JSON body template. $$KEY skips the escaping. $PREV is the previous flow step's output. An unresolved $NAME is left in place as literal text rather than becoming an empty string.
Why one flat string and not a JSON object per capability: a caller that has read one contract can call any of the 891 without learning a new argument shape, and a router can forward a user's sentence through unchanged. The price is no types at the door. That is the trade one commenter refuses — menix, arguing schemas let a code-writing agent plan one precise program instead of a print-and-inspect loop. Both positions describe real failure modes; the comparison table below lands the verdict.
The row names the environment variable; the value never enters the table
The auth column is a prefix and an environment-variable name. applyAuth at dispatch.js:203-234 reads it at call time:
| Form | What happens | Live rows |
|---|---|---|
| empty or null | no credential applied | 637 |
headers:{"k":"$ENV_NAME"} | each header value has $NAME replaced from the environment | 139 |
bearer:ENV_NAME | Authorization: Bearer <value of ENV_NAME> | 68 |
basic:ENV_NAME | Authorization: Basic + base64 of <value>: | 45 |
query:param=ENV_NAME | appends ?param=<url-encoded value> to the URL | 2 |
| anything else | throws ERR:auth:unknown_prefix:<prefix> | 0 |
npx wrangler d1 execute loop-content-spine --remote --command \
"SELECT CASE WHEN auth IS NULL OR TRIM(auth)='' THEN '(none)'
ELSE substr(auth,1,instr(auth,':')) END AS form, COUNT(*) AS n
FROM directory GROUP BY form ORDER BY n DESC;"115 rows name a credential through bearer:, basic: or query:, and between them they reference 12 distinct auth specifications. bearer:GROK_API_KEY alone appears on 35 rows. One rotation in the platform secret store changes the credential for all 35; no row is touched, no migration runs, no deploy happens.
An attacker who exfiltrates the whole table learns every capability that exists, every upstream URL, every argument shape, which capabilities are credentialed, and the names of the twelve secrets. That is a real map, worth defending. What they do not get is one credential value, because no column ever holds one. The failure mode of a leaked registry that stores values is total; here it is reconnaissance.
The row's claims about permission are advisory. Enforcement is server-side and independent of the row. When an invocation arrives with a scoped capability token, capGateCheck at dispatch.js:2121-2149 evaluates revocation, audience binding, owner gate, contract hash, risk ceiling, fixed body and payload ceiling before any runner is reached. A row marked sensitive = 1 is denied to any token whose risk_ceiling is not high, with the literal reason risk_ceiling:low<row:high. Editing the row cannot widen a token; editing a token cannot reach a row outside its scope. That is the pattern jensbontinck described from production — the credential sits at the enforcement point, not with the caller.
Shape mode proves the boundary without firing anything: {"key":"…","body":"…","shape":true} returns the fully constructed outbound request with credential material stripped by redactDeep (dispatch.js:1338-1356), which removes authorization, x-api-key, cookie and any *_API_KEY-shaped string. Against a row whose auth named a variable absent from the environment, the preview came back "headers":{} — no credential, no header, and the upstream 401 is the first signal.
Reading one row returns a document that assumes the reader knows nothing
curl -s "https://miscsubjects.com/api/dispatch?key=GROK_MODELS&format=markdown"4,413 bytes. The blocks it contains, and why each is there:
| Block | Content | Why it exists |
|---|---|---|
| Path | OIP > GROK > GROK_MODELS | places the row in the tree so a reader can climb to siblings |
| Capability / When to use | the # WHAT and # WHEN_TO_USE lines from content | the two questions a caller has before choosing |
| RUN NOW | a single URL that fires the example | a model with only a URL-fetch tool can still invoke it |
| Example call | [GROK_MODELS][/GROK_MODELS] | the router tag form, for a model emitting tags in prose |
| type · runner · auth · risk | tool · edge · grok, required · low | tells the caller whether a credential and an approval are needed before trying |
| inputs / outputs | {"args":"see content"} and the documented return shape | the argument contract |
| Affordances | the moves the presented credential can make | computed for the caller, with the note that the server enforces scope regardless |
| Machine Contract | four imperatives, including "do not infer the row shape from memory" | stops a model reconstructing a stale signature from training data |
| Invocation / Ledger / Repair | ledger, receipt, replay and repair URLs | closes the loop after the call |
| Troubleshooting | four problems, each with an action and a URL | the same content as the failure table below, at the point of use |
The contract is close to constant in size regardless of the row. Measured across four rows of four different types: NOW 4,423 bytes, GROK_MODELS 4,413, ROUTER 4,442, CONTENT_SEARCH 4,507. The per-row variance is under 100 bytes because the scaffolding dominates and the row-specific part is small — that is the shape of a contract that is fetched one at a time rather than held in context. Fetching all of them at once is the opposite bargain: curl -s "https://miscsubjects.com/api/dispatch?registry=1" | wc -c returns 1,608,554 bytes for 877 objects.
People running large tool surfaces keep measuring the same thing independently: a maintainer auditing his own agent found 47 tool schemas costing 13,341 tokens on every request before the user's message; a vendor engineer building an MCP server for a large unified API hit 50,000 tokens of definitions before the agent touched a single user message; a tiktoken run against one server's full tool list produced 741 tools and roughly 488,013 tokens, larger than the context window it was meant to fit.
Adding the 892nd capability: one POST, then a receipt proving it ran
Everything below was executed against production on 2026-07-26 using an obviously-named throwaway row, ZZ_TEST_TEMPERATURE, which was deleted at the end. The outputs are copied verbatim.
Step 1 — the credential. TERMINAL_KEY is the owner key checked by isBuildAuthed. Every mutating call carries it as x-terminal-key.
export TERMINAL_KEY="$(grep '^TERMINAL_KEY=' ~/.config/grok-bridge.env | cut -d= -f2 | tr -d '"')"Step 2 — the POST. key and type are the only required fields (functions/api/directory/index.js:51).
curl -sS -X POST https://miscsubjects.com/api/directory \
-H "x-terminal-key: $TERMINAL_KEY" -H 'content-type: application/json' -d '{
"key": "ZZ_TEST_TEMPERATURE",
"type": "http",
"target": "GET https://api.open-meteo.com/v1/forecast?latitude=$1&longitude=$2¤t=temperature_2m",
"auth": "",
"content": "# WHAT: Current temperature in Celsius for one latitude and longitude, from the Open-Meteo public API.\n# WHEN_TO_USE: a capability needs the live temperature at a coordinate.\n# ARGS: $1=latitude | $2=longitude\n# EX: [ZZ_TEST_TEMPERATURE]37.77|-122.42[/ZZ_TEST_TEMPERATURE]\n# OUTPUT: JSON with current.temperature_2m",
"category": "tools",
"enabled": 1,
"planner_visible": 1,
"examples": "[\"37.77|-122.42\"]"
}'{"ok":true,"key":"ZZ_TEST_TEMPERATURE","updated_at":"2026-07-26T04:36:19.832Z"}HTTP 201. Without the header the same call returns {"error":"unauthorized"} and HTTP 401.
Step 3 — invoke it. No deploy, no restart, no cache warm-up in between.
curl -sS -X POST https://miscsubjects.com/api/dispatch \
-H "x-terminal-key: $TERMINAL_KEY" -H 'content-type: application/json' \
-d '{"key":"ZZ_TEST_TEMPERATURE","body":"37.77|-122.42"}' \
-w "\nhttp=%{http_code} total=%{time_total}s\n"{"ok": true, "ran": true, "trace": "t_jweoafmw",
"result": "HTTP 200:{\"latitude\":37.763283,\"longitude\":-122.41286,...,\"current\":{\"time\":\"2026-07-26T04:30\",\"interval\":900,\"temperature_2m\":15.7}}",
"proof": {"ok": true, "invocation_id": "inv_c23irnzhx1",
"public_receipt": "https://miscsubjects.com/receipt/inv_c23irnzhx1"}}http=200 total=3.126264s — 3.13 seconds wall clock from a laptop in California, including the Open-Meteo round trip. Three consecutive invocations of a pure fn row with no upstream call, timed the same way, took 3.40 s, 1.07 s and 1.59 s; the first carries TLS and connection setup.
Step 4 — the receipt. inv_c23irnzhx1 records actor owner:terminal-key, runner http, trace t_jweoafmw, material: true, cost_usd: 0, and three SHA-256 fingerprints: input, output, and the object contract. It is public and keyless:
curl -s "https://miscsubjects.com/api/dispatch?confirm=inv_c23irnzhx1"
# "confirmed": true, "status": "PROVEN_MATERIAL_RESULT"Step 5 — remove it.
curl -sS -X DELETE "https://miscsubjects.com/api/directory/ZZ_TEST_TEMPERATURE" \
-H "x-terminal-key: $TERMINAL_KEY"
# {"ok":true,"key":"ZZ_TEST_TEMPERATURE","deleted":1}A subsequent GET /api/directory/ZZ_TEST_TEMPERATURE returns 404. The receipt still resolves and still reports confirmed: true — deleting the definition does not delete the history of what it did.
The no-restart property depends on something outside the row
Nothing here caches a tool list on the caller's side, so a new row is live on the next read. That is not a general property of tool registries, and the people who run them keep filing the same bug.
A registry gateway maintainer describes the failure exactly: upstream tool lists cached at registration time, stale until a manual re-registration or a full restart, with removed tools leaving dangling references inside tool groups. The Model Context Protocol has a message for this — a server that declared the listChanged capability SHOULD send notifications/tools/list_changed when its tool list changes. Two independent reports say clients ignore it. One user reproduced a dynamic-registration server against an IDE that never re-queries tools/list, while the same server worked in two other clients. A Microsoft engineer filed identical behaviour against a CLI client, with a repro video, noting the same product's editor extension updates immediately.
"Add a capability without a restart" is therefore a claim about the whole path, not about the registry. This path has no client-side cache to invalidate because the caller fetches one contract at a time. A registry that pushes definitions into a client's context inherits that client's refresh behaviour, and the behaviour is not uniform.
Every failure names itself, and the names are in the code
| Symptom | Literal response | Cause | Fix |
|---|---|---|---|
| Call returns immediately, nothing ran | {"error":"unknown_key","attempted":"ZZ_TEST_TEMPERATUR","ran":false,"did_you_mean":[…]} | key not in the table | use a did_you_mean entry, or GET /api/dispatch?ask=<plain words> |
fn row fails before running | ERR:fn:unknown_target:<name> | target names a function absent from the runner map (dispatch.js:1169) | correct target, or the function was renamed in a deploy |
fn row fails on its own template | ERR:fn:bad_content_json:<parser message> | the executable line of content is not valid JSON after substitution (dispatch.js:1173) | the template must be a JSON array; check for an unescaped quote in an argument |
fn template parses but is rejected | ERR:fn:content_not_array | the template is valid JSON but not an array (dispatch.js:1174) | wrap it: ["$1","$2"] |
Credential-shaped auth never applies | request goes out with "headers":{} | auth names an environment variable that does not exist | add the secret under the exact name; the row does not change |
| Auth string is malformed | ERR:http:<KEY>:ERR:auth:unknown_prefix:apikey | prefix is not one of bearer:, basic:, headers:, query:, oauth: (dispatch.js:234) | use a supported prefix |
| Upstream refuses | ERR:http:401:<body> | the credential exists but is rejected | rotate the secret; the row is fine |
| Every call to one row fails instantly after a run of 401s | ERR:breaker_open:<KEY> — 8 consecutive auth failures; credential is dead until replaced. | the circuit breaker tripped at 8 consecutive 401/403 (dispatch.js:1293-1320) | replace the credential; the breaker clears after 1 hour or on KV delete breaker:<KEY> |
| Target host unreachable | ERR:http:fetch:<message> | DNS, TLS or connection failure (dispatch.js:1285) | check the URL in target |
| Argument missing | URL renders with an empty slot, e.g. &longitude=& | fewer pipe-separated pieces than the template's $N slots | count the $N slots; extra arguments beyond the highest slot are silently discarded |
flow step fails | ERR:flow:bad_step:<text> | a step has no : separating key from body (dispatch.js:1723) | write KEY: args |
| Write refused, nothing changed | {"error":"registry_hygiene_refused: missing_description","how_to_fix":"content (the docstring…) is required…","state_changed":false} | PUT/PATCH would leave the row with empty content ([key].js:142-153) | write the # WHAT / # ARGS / # EX docstring |
| Marking a row sensitive is refused | {"error":"registry_hygiene_refused: high_risk_missing_schema"} | sensitive set without input_schema | supply input_schema in the same call |
| PATCH accepted no changes | {"error":"no recognized fields"} HTTP 400 | the body named only fields outside the allow-list ([key].js:223) | sensitive and runner are not writable through PATCH |
| Token rejected on a row it should reach | risk_ceiling:low<row:high | the row is sensitive and the token's ceiling is not high | mint a token with the higher ceiling; the row is not the problem |
| Token rejected after an unrelated edit | contract_changed:<pinned>!=<current> | the token pinned a contract hash and the row's contract changed | mint a fresh token against the new contract |
The hygiene gate is asymmetric on purpose. PUT refuses any non-compliant write. PATCH compares the violation before and after the merge and refuses only a patch that makes a compliant row non-compliant, so the rows that predate the rule stay editable for unrelated maintenance ([key].js:206-219). Of 891 rows, 256 carry an input_schema and 63 carry examples.
Where the row loses to a schema, and where a schema loses to the row
| Dimension | Directory row | JSON Schema tool definition | OpenAPI 3.1 operation | MCP tool |
|---|---|---|---|---|
| Argument typing before the call | none; one string, split on `\ | ` | full — types, enums, required, formats | full, plus content negotiation and parameter locations |
| Rejects a bad call without executing | no; the runner or the upstream rejects it | yes, at the validator | yes, at the gateway or generated client | yes, if the host validates |
| Client code generation | none | partial | mature; the spec exists so consumers can act "without access to source code" | via generated SDKs over the schema |
| Ecosystem and tooling | one implementation, this one | universal | very large | growing fast, multi-vendor |
| Discovery | ?ask= in plain words, or ?registry=1 | out of band | the document is the discovery surface | tools/list |
| Cost in caller context | one contract, ~4.4 KB, fetched when needed | every definition, every request | n/a in-prompt; large as a document | every definition, every request unless the host defers |
| Adding a capability | one INSERT, live immediately | edit the tool array, redeploy the caller | edit the document, regenerate clients | server-side change plus a list_changed the client may ignore |
| Change safety for callers | contract hash on the receipt, detected after the fact | schema diff, detected by tooling | versioned document, diffable | schema diff, if the client re-reads |
The verdict. Use a schema when a wrong call is expensive and must be stopped before it executes — money movement, destructive writes, anything where "the upstream returned 400" is already too late — or when strangers will write clients against it. Typing is not decoration there; it is the only place a bad argument is caught for free. Use a row when the surface is large, the caller is a model, the operations are mostly read-and-report, and the dominant cost is context rather than correctness.
The two are not exclusive. input_schema is on the row for this reason: 256 rows carry one, and those are the rows that get typed when the table is projected as an MCP tool list. The row is the storage format; the schema is one projection of it.
A row has no version number, and the receipt is where change is detectable
updated_at is overwritten on every write. There is no version column, no history table, and no diff. What exists instead is a fingerprint computed at invocation time. objectContractFingerprint (functions/_lib/object_contract.js:17-25) hashes the fields that define the call — id, object type, runner, directory type, category, target, description, input_schema, auth, risk, approval requirement, status, operation semantics — and the resulting SHA-256 is stored on every receipt as fingerprints.contract.
Which fields count was measured directly, by invoking the same row three times with an edit in between:
| Edit between invocations | Invocation | Contract fingerprint |
|---|---|---|
| — (baseline) | inv_vbzo55gyxb | fcb5a4d6ccdd552994c09c96a88c6a1dc18470d2fb1b57c151b4b951e4a7342f |
| `PATCH {"examples":"[\"51.51\ | -0.13\"]"}` | inv_7s7br5887e |
PATCH {"target":"…¤t=temperature_2m,wind_speed_10m"} | inv_m6c161ry9u | da066c304231231b32002f04aebb513f8a62bed41646e4b16845cb25c8c7fadc |
Changing examples left the fingerprint byte-identical. Changing target changed it. So the hash tracks the callable contract and ignores documentation-only edits — which is the behaviour you want, and it is worth knowing rather than assuming.
Two guarantees follow, and one gap. A capability token may be minted pinned to a contract hash; any invocation after the row changes is refused with contract_changed:<pinned>!=<current> and HTTP 409 (dispatch.js:2128-2132), so the caller is stopped rather than silently redirected. And every mutation is written to the append-only event log as a DIRECTORY_MUTATE record carrying the action, the key and the row ([key].js:29-45) — the change history exists even though the row does not keep it.
The gap: an unpinned caller invoking a changed row gets the new behaviour with no warning and learns of it from the receipt afterwards. That is the limitation, and the reason pinning exists. It is the same distinction aderix drew about version-controlling capabilities in general — approval around the definition does not help mid-flight, because the dangerous moment is the invocation, not the edit.
Receipts are engine-authored, never agent-authored, and that is not stylistic. A controlled two-condition experiment found an agent inventing a governance event that never happened and presenting it as compliance evidence when nothing else wrote the record. Here the dispatcher writes it, in the same code path that runs the call, with hashes of the actual input and output bytes.
The agent never holds API keys directly — the proxy holds them and issues scoped, short-lived capability tokens (ES256, 60s TTL). Single enforcement point for scanning, classification, and audit.— jensbontinck, Hacker News, 2026-03-05
References (26)
- Cloudflare D1 overview — Cloudflare, Apr 30, 2026“D1 is Cloudflare's managed, serverless database with SQLite's SQL semantics, built-in disaster recovery, and Worker and HTTP API access.”
- Tool use overview — Claude Docs — Anthropic, Jul 26, 2026“To have Claude call a function that you define, pass a tool with an input_schema, then execute the call when Claude returns a tool_use block.”
- Model Context Protocol — Tools (2025-06-18) — Model Context Protocol, Jun 18, 2025“When the list of available tools changes, servers that declared the listChanged capability SHOULD send a notification: { "jsonrpc": "2.0", "method": "notifications/tools/list_changed" }”
- JSON Schema Validation, draft 2020-12 — JSON Schema, Jun 16, 2022“Validation keywords in a schema impose requirements for successful validation of an instance. These keywords are all assertions without any annotation behavior.”
- OpenAPI Specification 3.1.0 — OpenAPI Initiative, Feb 15, 2021“The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.”
- modelcontextprotocol/schema.ts — the Tool interface — GitHub (modelcontextprotocol), Jun 18, 2025“inputSchema: { type: "object"; properties?: { [key: string]: object }; required?: string[]; };”
- Dynamic tool sync: notifications/tools/list_changed + polling fallback — GitHub (mcpjungle/MCPJungle), May 15, 2026“MCPJungle caches upstream tool lists at registration time only. If an upstream server adds or removes tools later, MCPJungle's view stays stale until a manual re-registration or full restart.”
- Kiro IDE does not handle MCP notifications/tools/list_changed — dynamic tools not refreshed — GitHub (kirodotdev/Kiro), Mar 20, 2026“When an MCP server dynamically adds or removes tools at runtime and sends this notification per the MCP spec, Kiro IDE does not re-query tools/list, so the new tools never appear until the server is manually reconnected.”
- GitHub Copilot CLI does not dynamically load tools via tools/list_changed — GitHub (microsoft/wassette), Sep 29, 2025“Internal terminal testing shows the CLI never refreshes its tool list, unlike GitHub Copilot in VS Code which updates immediately.”
- Comment on: Agentic Engineering Patterns — Hacker News, Mar 5, 2026“The agent never holds API keys directly — the proxy holds them and issues scoped, short-lived capability tokens (ES256, 60s TTL). Single enforcement point for scanning, classification, and audit.”
- Comment on: Polymcp – toolkit for building MCP agents that discover, inspect and orchestrate tools — Hacker News, Jan 4, 2026“CLI + registry: manage MCP servers, configs, and agents from the CLI; servers can be added/removed without touching agent code.”
- Reduce Context Window Usage (13,341 tokens for tools alone) — GitHub (abdlkrim-jribi/hcode), May 5, 2026“The agent injects ALL 47 tool schemas on every single request, consuming ~13,341 tokens before the user message is even sent.”
- Comment on: Apideck CLI – An AI-agent interface with much lower context consumption than MCP — Hacker News, Mar 16, 2026“We built a unified API with a large surface area and ran into a problem when building our MCP server: tool definitions alone burned 50,000+ tokens before the agent touched a single user message.”
- GCORE_TOOLS=* advertises ~488k tokens of tool definitions — larger than most context windows — GitHub (G-Core/gcore-mcp-server), Jul 11, 2026“with `GCORE_TOOLS=*` it advertises **741 tools / ~488,013 tokens** (659/tool) — that exceeds a 200K context window on its own, so the full config can't actually be used with most models.”
- Comment on: MCP is dead; long live MCP — Hacker News, Mar 14, 2026“Tool results from programmatic calls are not added to Claude's context window, only the final code output is. They report up to 98.7% token savings in some workflows.”
- Comment on: Show HN: GitAgent – An open standard that turns any Git repo into an AI agent — Hacker News, Mar 17, 2026“If an LLM hallucinates in production and decides to execute a destructive tool defined in SKILL.md (like dropping a table or issuing a Stripe refund), a Git PR approval process doesn't help you mid-flight.”
- Comment on: Agent Runs Code You Never Wrote — Hacker News, Mar 30, 2026“fabricated an audit record — invented a governance event that never happened and presented it as compliance evidence.”
- Comment on: Ask HN: How are you enforcing permissions for AI agent tool calls in production? — Hacker News, Jan 24, 2026“The audit trail piece is critical too. Being able to answer "why was this blocked?" after the fact builds trust with teams rolling this out.”
- Add sanitized audit logging contract for MCP tool calls — GitHub (rafaself/aws-mcp-gateway), Jun 19, 2026“Add structured audit logging for MCP tool calls without exposing credentials, signed request data, raw AWS responses, or CloudWatch log message contents.”
- Row counts by type, taken from production D1 on 2026-07-26 — miscsubjects.com, Jul 26, 2026“fn 480 | http 303 | agent 57 | flow 51”
- Credential forms and registry hygiene across all 891 rows — miscsubjects.com, Jul 26, 2026“(none) 636 | headers: 139 | bearer: 68 | basic: 45 | query: 2”
- Receipt for the first invocation of a capability created minutes earlier — miscsubjects.com, Jul 26, 2026“"ok": true, "ran": true, "result": "HTTP 200:{...\"temperature_2m\":15.7}", "invocation_id": "inv_c23irnzhx1"”
- Contract size, measured across four rows of four different types — miscsubjects.com, Jul 26, 2026“NOW 4423 bytes | GROK_MODELS 4413 bytes | ROUTER 4442 bytes | CONTENT_SEARCH 4507 bytes”
- Which row edits change the contract fingerprint, measured by three invocations — miscsubjects.com, Jul 26, 2026“baseline fcb5a4d6ccdd5529... | after examples edit fcb5a4d6ccdd5529... | after target edit da066c3042312313...”
- The production CREATE TABLE and column list, read back from D1 — miscsubjects.com, Jul 26, 2026“CREATE TABLE directory ( key TEXT PRIMARY KEY, type TEXT NOT NULL CHECK (type IN ('fn','http','agent','flow')),”
- cloudflare/workers-sdk — wrangler, the tool every measurement here was taken with — GitHub (cloudflare), Jul 26, 2026“wrangler”