DEV Community: wolfejam.dev

Beyond Valid: What an Agent Needs From a SKILL.md

wolfejam.dev — Mon, 26 Oct 2026 17:35:16 +0000

TL;DR: The Agent Skills validator tells you a SKILL.md is well formed. It can't tell you whether an agent will pick the skill at the right moment, run it safely, and know when to stop. This tutorial takes one skill from valid to useful in six steps, by hand, using only the Agent Skills specification and its reference validator.

New here? Agent Skills is an open format for giving AI agents new abilities: a folder with a SKILL.md file (YAML frontmatter, then Markdown instructions), plus any scripts or references it needs. It's an AAIF project, and many agent products read it.

The skill we'll fix

Here's a complete, valid skill:

---
name: release-notes
description: Helps with releases.
---

Write release notes.

Check it with skills-ref, the specification's reference validator. With uv installed, no setup is needed:

uvx --from skills-ref agentskills validate release-notes

Valid skill: release-notes

It passes. The specification's own description guidance calls Helps with PDFs. a poor example, and ours has the same problem. Valid is the floor, not the goal.

How an agent meets your skill

Two moments matter, and the specification describes both under progressive disclosure:

Choosing. At startup the agent loads only each skill's name and description (about 100 tokens). That's all it has when deciding whether your skill fits the task.
Doing. Once it picks your skill, it loads the whole body (under 5,000 tokens recommended) and follows it.

You can see the choosing view yourself:

uvx --from skills-ref agentskills to-prompt release-notes

<available_skills>
<skill>
<name>
release-notes
</name>
<description>
Helps with releases.
</description>
...

That's the agent's whole view while it chooses. "Helps with releases" could mean tagging, publishing, versioning or notes. Steps 2 and 3 fix the choosing; steps 4 to 6 fix the doing.

Step 1: Make it valid

Run the validator on every skill, and fix every error before anything else. Here's what it catches:

---
name: Release_Notes
description: Helps with releases.
author: me
---

Validation failed for Release_Notes:
  - Unexpected fields in frontmatter: author. Only ['allowed-tools', 'compatibility', 'description', 'license', 'metadata', 'name'] are allowed.
  - Skill name 'Release_Notes' must be lowercase
  - Skill name 'Release_Notes' contains invalid characters. Only letters, digits, and hyphens are allowed.

The usual fixes:

name: lowercase letters, digits and single hyphens, 64 characters at most, and the same as the folder's name.
description: 1 to 1,024 characters.
Extra fields (author, version, a client's own settings): move them under metadata, which takes any string keys.

Step 2: Say what it does, then when to use it

The specification says the description should cover both what the skill does and when to use it, with keywords that match real tasks. Put what it does first, in the third person (as the specification's good example does), then the trigger:

description: Drafts release notes for a new version from the git log and the pull requests merged since the previous tag. Use when the user asks for release notes, a changelog entry, or "what changed since v1.2".

The trigger words are the ones a user would actually type: release notes, changelog, what changed.

Step 3: Say what it's not for (when a neighbour could trigger it)

If a nearby task could pick your skill by mistake, say so in the description. Release notes sit close to commit messages and pull request descriptions:

... Not for commit messages or pull request descriptions.

Skip this when nothing nearby is easily confused. It's a guard, not a requirement.

Step 4: Say what it needs and what it touches

These are the facts an agent should have before step 1, not partway through:

**Needs:** git, and the GitHub CLI (`gh`) signed in to the repo.

**Touches:** reads tags, the git log and merged pull requests. Writes `RELEASE_NOTES.md` only. Publishes nothing: the user creates the release.

Needs tells the agent to check its tools first, rather than failing at step 3. Touches tells it (and the person approving its actions) what will change: which files it writes, and whether anything leaves the machine. "Publishes nothing" matters as much as "publishes": it tells the agent where to stop and hand back.

The specification has an optional compatibility field for environment requirements, such as Requires git, docker, jq, and access to the internet. Use it if you like. It's one free-text line, so the reads, writes and publishing still belong in the body.

Step 5: Give the steps, in order

The specification recommends step-by-step instructions. Number them, and put the exact command in each one where there is one:

## Steps

1. Find the previous tag: `git describe --tags --abbrev=0`.
2. List the commits since it: `git log <tag>..HEAD --oneline`.
3. List the pull requests merged since it: `gh pr list --state merged --search "merged:>=<tag date>"`.
4. Group them under Added, Changed and Fixed, one line each, in words a user would use.
5. Write `RELEASE_NOTES.md` and show it to the user.

Step 6: Say when it's done

An agent without a finish line keeps polishing, or stops early. Name the finished state of the work (a file, a result), not a step in the conversation:

**Done when:** `RELEASE_NOTES.md` lists every pull request merged since the previous tag, and the user has seen it.

That's also a check the agent can run on itself before it reports back.

The result

---
name: release-notes
description: Drafts release notes for a new version from the git log and the pull requests merged since the previous tag. Use when the user asks for release notes, a changelog entry, or "what changed since v1.2". Not for commit messages or pull request descriptions.
---

# Release notes

**Needs:** git, and the GitHub CLI (`gh`) signed in to the repo.

**Touches:** reads tags, the git log and merged pull requests. Writes `RELEASE_NOTES.md` only. Publishes nothing: the user creates the release.

## Steps

1. Find the previous tag: `git describe --tags --abbrev=0`.
2. List the commits since it: `git log <tag>..HEAD --oneline`.
3. List the pull requests merged since it: `gh pr list --state merged --search "merged:>=<tag date>"`.
4. Group them under Added, Changed and Fixed, one line each, in words a user would use.
5. Write `RELEASE_NOTES.md` and show it to the user.

**Done when:** `RELEASE_NOTES.md` lists every pull request merged since the previous tag, and the user has seen it.

Still valid:

uvx --from skills-ref agentskills validate release-notes

Valid skill: release-notes

Twenty lines. The specification asks for under 500 lines and about 5,000 tokens; if yours grows past that, move reference material into references/ and link it, one level deep, as the specification recommends. Then check those links point at files that exist.

The checklist

Run down this for any SKILL.md, yours or one you're about to install:

#	Check	Why the agent cares
1	`skills-ref validate` passes	Clients may skip or reject an invalid skill
2	Description: what it does, then "Use when…"	It's all the agent sees while choosing
3	"Not for…", if a neighbour could trigger it	Stops the wrong skill being picked
4	Needs and Touches, before the steps	Tools checked first; side effects known before they happen
5	Numbered steps	The order is part of the instructions
6	Done when	The agent knows when to stop and report
7	Under 500 lines; local links resolve	The whole body loads at once; a missing file is a dead end

Check 1 is the specification's hard rules. Checks 2 to 7 come from its should guidance and recommendations, plus three facts an agent needs that the specification leaves to you: needs, touches and done.

Optional: the same facts as data

Steps 4 to 6 are prose, which suits a model reading the body. If you also want tools to read those facts, some authors put them in a small YAML block at the top of the body, called a FAF Block (also called a Context Block):

<!-- faf:start -->
```yaml
v: 1
needs: [git, "gh, signed in"]
reads: [tags, "git log", "merged pull requests"]
writes: [RELEASE_NOTES.md]
network: [github.com]
publishes: false
done_when: "RELEASE_NOTES.md lists every pull request merged since the previous tag, and the user has seen it"
```
<!-- faf:end -->

It's valid in any skill today: the specification puts no restrictions on the body, and the body loads only after the skill is chosen, so the block costs nothing while the agent is choosing. Further reading on the format it comes from: faf.one/links.

Where to go deeper

Specification: agentskills.io/specification
Reference validator: skills-ref (uvx --from skills-ref agentskills --help)
What Agent Skills are: agentskills.io

Valid gets your skill loaded. The rest gets it chosen at the right moment, run safely, and finished.

How to Shuffle the Pack: MCP Server Card census reproduction guidance

wolfejam.dev — Fri, 23 Oct 2026 14:50:01 +0000

TL;DR: The numbers in Checked Yours? come from three small scripts, 166 lines in all, that only ever read. You can run them yourself in an afternoon. This is how, step by step, and the four choices that move the answer from 8.5% to under 3%.

In Plain English
What the census is. A count of how many MCP servers in the public registry publish a Server Card, the small file that tells an AI app who a server is and how to connect.
What this post does. Walks through the count in three steps: read the registry, check each server, add it up. Then a fourth, to compare two runs.
Why you'd run it. To check our numbers, to count again next week, or to point the same scripts at your own list of servers.

The steps follow below.

What you need

Node.js 22 or later, and git.
About three and a half hours, mostly waiting. Step 2 is resumable: stop it and start it again, and it picks up where it left off.
Nothing else. No keys, no accounts. Everything it reads is public.

git clone https://github.com/Wolfe-Jam/mcp-server-card-check
cd mcp-server-card-check
npm ci && npm run build
export CENSUS_DIR=./census-data && mkdir -p "$CENSUS_DIR"

Step 1: read the deck

node scripts/census/registry.mjs

The MCP Registry lists every published version of every server, 100 to a page. registry.mjs reads every page (about 20 minutes) and keeps one card per server:

the latest version only, not every release;
only servers with a remote endpoint (streamable-http). A server you install and run locally has no URL to check;
each URL once. Many entries point at the same address.

On October 20 that took 162,532 entries down to 30,142 unique addresses. 304 of those were templates, like https://{tenant}.example.com/mcp. They can't be requested as written, so they're set aside, not guessed. That leaves 29,838 to check.

If a page fails, the script waits and tries again, up to five times. It saves a checkpoint as it goes, so a dropped connection costs a page, not the whole read.

Step 2: check every card, read-only

CONCURRENCY=16 node scripts/census/probe.mjs

For each address, probe.mjs runs the same discovery checks as the Server Card Check web page: it looks for a card at <url>/server-card, then in the AI Catalog at /.well-known/ai-catalog.json, and checks what it finds against the v1 schema and the hosting rules (CORS, caching).

It can't change anything, by construction. Every request goes through this guard:

const readOnlyFetch = (url, init = {}) => {
  const method = (init.method ?? "GET").toUpperCase();
  if (method !== "GET" && method !== "OPTIONS") return Promise.reject(new Error(`census is read-only: ${method} refused`));
  return fetch(url, { ...init, redirect: "follow", headers: { ...(init.headers ?? {}), "User-Agent": UA } });
};

GET and OPTIONS only. The checker's transport checks send a POST, so for the census they're recorded as skipped, and nothing is ever sent to a server's MCP endpoint.

Be a good guest. At most 16 requests at a time, a 10-second timeout each, and a User-Agent that names the project and links to it, so anyone who sees the traffic knows what it is.

Results go to census.jsonl, one line per address. Stop it whenever you like; addresses already in the file are skipped next time. On October 20 the checks ran from 12:02 to 15:14 UTC, with no errors.

Step 3: count the hand

node scripts/census/summarize.mjs

No network. summarize.mjs is arithmetic over the two files from steps 1 and 2, and writes summary.json. A card is a 200 at a card location that parses as JSON. A valid card also passes the v1 schema. A 200 that isn't JSON (usually a website's catch-all page) is counted separately.

That gives four outcomes for every address, and they are different problems with different fixes. A reader asked for this split after the October 20 post. Here it is for the 27,966 endpoints outside the largest publisher:

Outcome	Endpoints	Share	The fix
No card	25,654	91.7%	Publish one
A web page where the card should be	733	2.6%	Serve JSON there, or a 404
A card that fails validation	912	3.3%	The checker names the field
A valid card	667	2.4%

More cards fail than pass. Every row comes from summary.json: no card is checked minus answered; failing is JSON cards minus valid ones.

Shuffle the pack: four choices that move the answer

The same rows give very different headlines, depending on what you divide by. October 20:

Count by	Valid	Share
Endpoint	2,539 of 29,838	8.51%
Endpoint, leaving out the largest publisher	667 of 27,966	2.39%
Distinct host	586 of 21,526	2.72%
Registry namespace	528 of 18,856	2.80%
Namespaces with a single endpoint	471 of 17,519	2.69%

Entries are not servers. One publisher put 1,872 valid cards behind one gateway. Count endpoints and they're 74% of the valid cards. Count hosts, namespaces, or leave that publisher out, and every answer lands under 3%. The script reports the largest publisher separately, so you can see the effect, but it doesn't name it in the headline.
Latest version only. Counting every release would count the same server many times.
Templates are skipped, not filled in. Guessing a tenant name would be checking a server that may not exist.
A web page isn't a card. 733 addresses answered the card's URL with 200 OK and HTML. Count every 200 as "has a card" and the figure goes up by about a fifth (4,184 instead of 3,451).

None of these is hidden. Each one is a line in summarize.mjs, and summary.json carries every denominator, so you can pick another one and say so.

Step 4: compare two runs, or two checkers

CENSUS_DIR=./census-data A=0.1.1 B=0.4.1 SAMPLE=200 npm run census:diff

When the checker's rules change between two counts, is a change in the numbers the servers or the checker? census:diff answers that. It installs both versions from npm and checks each sampled endpoint with A and then B, in the same minute, so a changed verdict comes from the code, not from the server changing in between. The sample is seeded (SEED), so the same command picks the same endpoints again.

Before the October 20 post we ran it on 200 endpoints. The October 12 way of counting CORS gave the same verdict on every JSON card in the sample under both versions. So 179 → 324 cards sending all four CORS headers was the servers, not the yardstick.

Run yours

Point the same scripts at your own servers, or count the registry again next week and compare. If your numbers differ from ours, open an issue on the repository. A count anyone can repeat is worth more than one only we can.

Run a remote MCP server? Paste its address into Server Card Check. Checked yours?

Originally published at faf.one on October 21, 2026.

Checked Yours? MCP Server Cards, counted twice

wolfejam.dev — Wed, 21 Oct 2026 00:34:21 +0000

TL;DR: MCP Server Cards went Final on October 6. We counted every remote MCP server in the registry on October 12, and again eight days later with the same method. The share of hosts with a valid card rose from 1.9% to 2.7%. The registry added 18% more hosts in eight days. Hosts with a valid card? 66% more. Nearly four times faster. We checked twice. Most cards still leave browsers out, but the number that don't nearly doubled.

In Plain English
What a Server Card is. A small public file that tells an AI app who an MCP server is and how to connect, before it connects. Think of it as the server's business card, pinned to the door.
What two counts found. Still very few servers have one, but more each week. Of the cards that exist, most are missing something browsers need to read them.
What you can do. Paste your server's address into Server Card Check. It tells you, rule by rule, what passes and what to fix.

The facts follow below.

The count, twice

SEP-2127 merged as Final on October 6. It gives every MCP server a card: a JSON document with the server's name, version, description and connection details. Clients find it at <server-url>/server-card, or through an AI Catalog at /.well-known/ai-catalog.json.

We read the whole MCP Registry and kept the latest version of every server with a remote endpoint. Then we checked each address the way a client would, read-only: GET and OPTIONS requests, nothing that changes state. Twice, with the same scripts.

What we counted	Oct 12	Oct 20
Registry entries read	145,157	162,532
Endpoints checked	26,105	29,838
Something answered at a card location	3,609	4,184
…a web page, not a card	637	733
Schema-valid cards	2,194 (8.4%)	2,539 (8.5%)
Valid, by distinct host	352 of 18,268 (1.9%)	586 of 21,526 (2.7%)
Valid, by registry namespace	344 of 15,926 (2.2%)	528 of 18,856 (2.8%)

Entries are not servers. 8.5% looks healthy until you see where it comes from. One gateway publishes a card for each of its registry entries: 1,791 on October 12, 1,872 now. Its cards are real, but they are one deployment. Count by host, by publisher, or leave that gateway out, and the answer lands in the same place: under 3%.

What moved. In eight days the registry added 12% more entries and 18% more hosts. Hosts with a valid card went from 352 to 586, up 66%. 246 hosts gained one, 197 of them on servers that weren't in the registry a week earlier. 12 lost theirs. Leaving the large gateway out, valid cards went from 403 to 667.

Valid is not the same as working

A card can pass the schema and still let its users down.

Web pages where the card should be. 733 endpoints answer the card's address with 200 OK and an HTML page, usually a catch-all route. A client asked for JSON and got a website. 37 of last week's are gone; 133 new ones appeared.
Browsers left out. The spec says hosted cards MUST send CORS headers and lists four. By the method we used on October 12, the number of JSON cards sending all four rose from 179 to 324 (6.0% to 9.4%). We checked that the yardstick hadn't moved: both versions of the checker, run on the same 200 endpoints in the same minute, agreed on every card. Under the stricter rule the checker uses now, the figure is 298.
Repeat visits. 553 cards answer a repeat request with 304 Not Modified, up from 433. The rest send the whole card every time.

We checked ours too, on October 12. Our card at context.faf.one passed the schema and failed two CORS rules. It's fixed, and the fix is the worked example below.

How to make yours pass

The most common failures on October 20, across the 1,579 JSON cards outside the large gateway:

Failure	Cards	Fix
`ETag` not exposed (MUST)	1,174	Send `Access-Control-Expose-Headers: ETag` on the GET
Preflight doesn't allow `If-None-Match` (MUST)	1,172	Answer `OPTIONS` with `Access-Control-Allow-Headers: Content-Type, If-None-Match`
No `ETag`, no `304` (SHOULD)	1,005	Send an `ETag`; answer a matching `If-None-Match` with `304`
Not schema-valid (MUST)	912	Run the checker; it names the field
Wrong content type (SHOULD)	888	Serve it as `application/mcp-server-card+json`
`$schema` missing or wrong (MUST)	791	Use the v1 Server Card schema URL exactly
`description` too long or empty (MUST)	722	1 to 100 characters

And the web pages: serve the JSON at /server-card, or return 404 there. Not a 200 with your homepage.

A worked example: ours. Our card carries a generated_at time that changes on every request, by design, so a strong ETag would never repeat. The card now sends a weak ETag, hashed without that one field. Weak validators mean "the same meaning", and that's what a client needs to get a 304. One field left out of a hash; two new tests.

npx mcp-server-card-check https://your-server.example/mcp

Server Card Check is the census's checker, made into a tool: MIT-licensed, vendor-neutral, 39 checks, each marked MUST or SHOULD and linked to the spec section it comes from. Read-only by default. It runs in the browser, from the command line, or as a library, and exits 1 on any MUST failure, so it fits in CI.

A shared test

MCP's official conformance suite doesn't test Server Cards yet. There's an open proposal for that scenario (conformance #550), and the offer to help write it stands. A shared test is better than anyone's private one, including ours.

Method

Registry read at 12:02 UTC on October 20; checks ran until 15:14 UTC, with no errors. 304 addresses were templates (such as {tenant}) and were skipped. The checker was v0.4.1. Its rules changed between the two counts (it was reviewed independently twice in between), so every figure compared here was counted by the October 12 method, and that method was re-checked against both versions. Both summaries are in the repository, with the scripts, so every number on this page can be reproduced.

We'll count again while it's moving.

Checked yours?

If you run a remote MCP server, paste its address into the checker. No card yet? The report tells you what a valid one needs. Have one? It takes ten seconds to see if browsers can read it.

Originally published at faf.one on October 13, 2026, and updated on October 20 with the second count.

I argued with AI (Codex) about AGENTS.md. Then I realized what it actually was.

wolfejam.dev — Thu, 15 Oct 2026 14:35:40 +0000

When I was building FAF, I built it with Claude, starting on Sonnet 3.5 (yes, I thought 3.7 had come down from heaven!). I needed to test other AIs too. The Big 3 were Anthropic, Google's Gemini, and OpenAI, who had just released Codex.

All three got FAF from the get-go. It had a schema and it was YAML, and they love structured data. It's like YAML and noodles to AI 🍜. Claude had CLAUDE.md, and Gemini reinforced that (copied it, lol) with GEMINI.md. But not OpenAI. There was no CODEX.md. They had AGENTS.md, and Codex kept telling me it "had context." I was fighting with an AI.

So I stopped using Codex for a while.

Then the industry chose. AGENTS.md became the file every coding agent reads: Codex, Cursor, Copilot, Windsurf, Amp, Devin. OpenAI gave it to the Linux Foundation's Agentic AI Foundation in December 2025, and it became an open standard.

Codex said it had context. I said it didn't. Then a developer from the Svelte community asked me, "Isn't this what AGENTS.md does?"

I had to sit back and look. And the penny dropped.

It's instructions

AGENTS.md is a guide for agents: how to build, how to test, the conventions, what not to touch. Instructions.

That's all it was ever meant to be, and it's good at it.

The argument I'd been having was never about which file wins. It was about something markdown doesn't do: say what the project is. What it's for, who it's for, what it's built on, what doesn't apply. Instructions need something to be about.

AGENTS.md is markdown, not YAML: prose, for instructions. project.faf sits upstream, next to package.json, and gives AGENTS.md the falsifiable facts about the project, on demand. AGENTS.md instructs the agents.

That's where the line came from:

FAF defines. MD instructs. AI codes.

becomes

FAF defines. AGENTS.md instructs. AI codes.

What "defines" means

project.faf is a small YAML file at the root of a repo. It is to context what package.json is to dependencies, and it sits right next to it:

project/
├── AGENTS.md        ← agents follow this
├── package.json     ← npm reads this
├── project.faf      ← AI reads this
├── README.md        ← humans read this
└── src/

It holds the facts: the goal, the stack, the who, what and why. Each one is a validated fact, from one of two places only:

the repo, which faf auto reads (runtime, build, CI, hosting);
a person, who writes or approves what code can't show (the goal and the who, what and why), through faf go.

Nothing is guessed. A placeholder like tbd counts as empty, because it has no source.

It feeds the facts to AI, so tokens are best spent on following instructions and coding.

FAF defines. Context, compiled.

Facts, not more instructions

This matters more than it sounds. A 2026 study, Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (Gloaguen et al., arXiv 2602.11988), found that "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average", for LLM-generated and developer-committed files alike. Their advice: use them for what's non-standard, and evaluate anything else before you rely on it.

Their latest version adds a finding that matters here: instructions in context files are well followed, but repository overviews, "although popular and recommended by model providers, are not helpful." That's the split this post is about. The paper doesn't say why. My read: an overview is, simply put, more prose. And prose can be stale, non-specific or contradictory, and an agent can't tell which.

So FAF doesn't write one. The definition stays in project.faf, where every fact has a source, and what lands in AGENTS.md is commands, guardrails and the stack: things an agent can run or check. The study tested markdown context files, so it shows the limits of prose. Structured data, a schema in YAML, wasn't in it. That's the right next test, and their advice says so too.

So: keep the file lean, and give the agent facts with a source.

That's how FAF writes it:

npx faf-cli export --agents

It writes the standard file, plain conformant markdown, never a FAF dialect. Inside it, FAF manages one block of facts: setup and build commands, how to run the tests, where things live, guardrails, the stack. Anything you wrote by hand outside that block is kept. When the facts change, run the same command and the block is rewritten from the source, so it doesn't drift.

The ladder

Here's where any repo stands. With the ladder and the managed block, FAF and AGENTS.md work together, streamlined:

	NONE	GOOD	BETTER	BEST
What it is	No `AGENTS.md`; agents guess	Any `AGENTS.md`	An `AGENTS.md` with the managed block: lean, current, checked	BETTER, plus `project.faf` in the repo: the source behind the block, and far more, with the app type and the human context (goal, who, why)
What happens	Every session starts blank	Goes stale, quietly	The block's facts have no source in the repo	Facts and instructions stay in step

Most repos are in the first column. Getting to GOOD is one file. BEST is where the facts stop drifting, because they're defined in one place and every instruction file points back to it.

The camps met

Here's the part I enjoy most. In September, Claude Code started reading AGENTS.md too: in a project with no CLAUDE.md, it uses AGENTS.md instead. The two camps I was choosing between have met.

Which makes the point for me. The file that instructs will keep changing names, vendors and rules. The facts underneath will not. Define them once, and let every instruction file, AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, point back to the same source.

Try it

Paste either into your terminal or AI 👇

npx faf-cli auto

npx faf-cli export --agents

★ bookmark repo: github.com/Wolfe-Jam/faf-cli

Then ask your agent what the project is. It won't have to guess.

Help guide what we build —
Comments · suggestions welcome.

It sounds like a House of Cards. Is it?

wolfejam.dev — Mon, 12 Oct 2026 16:15:11 +0000

N cards, N models, N governing bodies. What could possibly go wrong?

That was my first thought, too. So let's look at it properly.

The business card you hand over before the meeting

Before a meeting, you hand someone a business card. It doesn't do the work. It tells them who you are, what you do, and how to reach you, so the conversation can start in the right place.

AI agents have the same thing now. The A2A project describes its Agent Card in exactly those words: "It acts as a digital business card."

An agent's card is a small public file. It says who the agent is, what it can do, which version it runs, and where to reach it. Crucially, another program can read it before connecting, so it can decide whether to connect at all.

Agents have them. And, since 6 October, so do MCP servers.

A2A has had Agent Cards for a while. On 6 October 2026 MCP caught up: Server Cards (SEP-2127) went Final.

An MCP Server Card carries a server's name, version, description and the address of its endpoint. It deliberately leaves out the tools themselves, because those can change from user to user and from minute to minute. The card is the introduction; the connection is the conversation.

And then there are the others: the MCP Registry's own server listing, AI Catalog entries that point at cards, and identity files that projects keep about themselves. That's the "N cards".

The case for "yes, it's a house of cards"

I wanted to know how many servers actually carry a card, so I checked.

I took a sample of the official MCP Registry: about 50 servers with a public address. I asked each one for its card at the address the spec reserves for it.

One had one. And it was a good one: small and tidy, listed in the site's own AI Catalog, with an AGENTS.md for agents to read.

That's not a scandal; the spec had only been Final for a few days. But one in fifty shows the gap.

It gets more interesting. A card is advisory. The spec says so plainly: clients shouldn't treat a card as the truth, but check it against the live connection. A card can drift out of date, overstate what a server supports, or quietly break the small technical rules that let a browser read it at all.

So I pointed a checker at one of my own live servers, one I'd built and was rather pleased with. It failed two of the spec's required checks. Two headers a browser needs, to read the card and to ask politely whether it had changed, were both missing.

Then I checked the one good card I'd found. It failed one of the same checks: a browser still couldn't ask politely whether it had changed.

N cards, N models, N governing bodies, and cards that looked fine but weren't. That's the house of cards, right there.

The case for "no"

Here's what changes the answer.

N governing bodies is shrinking. MCP and A2A, the two big agent protocols, now live under one roof: the Agentic AI Foundation, at the Linux Foundation, alongside goose and AGENTS.md. And the roof keeps growing: agentgateway joined in June, A2A in August, and Agent Router (formerly Envoy AI Gateway) in September. The protocols, and the gateways that route traffic between them, now answer to the same neutral home.

The cards are being linked, by both camps. AI Catalog, currently maintained by the Linux Foundation, is one format for listing cards across protocols. A catalog can point at an MCP Server Card, an A2A Agent Card, or anything else, by type. Its technical steering committee has four seats: two nominated by MCP's core maintainers, two by A2A's steering committee. The bridge is literally built from both sides.

The rules are written down, and they're checkable. SEP-2127 says where a card lives, what it must contain, which headers it must send, and what it must never include (credentials, private addresses). Rules you can check are rules you can fix.

And that's exactly what happened. I found the two failures because the check exists. I fixed them and redeployed the same day. Checked again: no required failures.

A house of cards falls over when you touch it. This one got stronger.

A business card you can actually see

There's one more piece. Agent Cards and Server Cards are written for machines, in JSON. But a business card is meant to be handed to a person.

So I print one as a business card. On the front: the name, a title, and a one-liner, the way you'd read a real one. Flip it over and the back holds the detail: the full identity, the project's instructions for agents, what it remembers, and how machines find it.

Same facts, two readers: one for machines, one for humans.

Where it's heading

Three things are worth watching:

Verified cards. If a card is advisory, the next step is a card that someone has checked, with the check visible. AI Catalog is already working on how independent assessors can sign what they've checked.
Cards that don't drift. The spec asks that a card never contradict the server it describes. Tooling that keeps the two in step makes that the default rather than a hope.
Business cards for people, too. A business card works for a person as well as an agent. The title tells you which.

So: is it a house of cards?

It sounds like one: N cards, N models, N governing bodies. But the bodies are converging, the cards are being linked by the people who write the protocols, and the rules are specific enough to check.

The real risk isn't the number of cards. It's cards that nobody checks.

Check yours.

See a project's business card: npx -y mcp-context-card card, run in any project folder. mcp-context-card is open source (MIT), an MCP server for a project's context, memory and identity. It serves a Server Card that passes SEP-2127.
The specs: MCP Server Cards (SEP-2127) · A2A Agent Card · AI Catalog

Context Over MCP, Series Wrap: Six Lessons, FAQs, and What I'd Do Differently

wolfejam.dev — Tue, 06 Oct 2026 13:05:59 +0000

Seven pieces, one question: how does an agent get your project's context when it has no working directory?

AGENTS.md works because a coding agent opens your repo and reads a file. Connect that same agent to a project over MCP, or put a tool in a browser tab, and there's no folder to read. The instructions are still true. The agent just can't see them.

This wrap is the map, the six lessons, a few FAQs, and what I'd do differently.

The map

Part	Title	Read it if…
I	Invisible AGENTS.md? Meet the visible MCP context card	you want the problem in one page
II	Publishing an MCP server to the official Registry (and the parts nobody writes down)	you're about to publish a server
III	Horses for Courses	you're deciding what goes in prose and what goes in data
IV	No Working Directory At All	your client is a browser tab
Companion	Build a WebMCP Tool From Scratch	you'd rather build one than read about it
V	The Form Is the Tool	you have HTML forms and no time for script
VI	Context You Can See	you want to see what your agent sees

Six lessons

1. A file convention doesn't travel over a protocol. AGENTS.md is a filesystem convention. An MCP client has no working directory, so it never finds the file. The fix isn't a new file. It's serving the same context through MCP: tools and resources the client can call, discoverable from the server's metadata. (Part I)

2. Publishing is where the undocumented failures live. The official Registry is straightforward until it isn't: a case-sensitive login match, a 100-character server.json description cap, and versions drifting between the package and the registry entry. Automating the publish with GitHub Actions OIDC removes most of it. (Part II)

3. Prose for instructions, data for facts. Instructions read best as prose. Facts (versions, commands, paths) drift unless they're structured and checked. Keep them apart and derive one from the other, and a drift bug becomes a failed check instead of a confident wrong answer. (Part III)

4. The browser has no working directory either. With WebMCP, a page registers tools for an in-browser agent: document.modelContext.registerTool() natively, or a polyfill. The rules that kept it safe were small and boring: mark read-only tools readOnlyHint, return errors as data, and allowlist every fetch (exact host, HTTPS, no redirects). (Part IV and the companion)

5. A form can be the tool. Declarative WebMCP turns an existing HTML form into a tool with a few attributes, no script, and the human still confirms the submit. If your site already has forms, you're most of the way there. (Part V)

6. Context should be visible. If an agent works from context, you should be able to see that context. Part VI shows it as a card: inline as an MCP App where the host supports it, as text plus a browser view where it doesn't, and with no config by reading the project from MCP roots. Shown in goose and in the MCP Apps reference host. (Part VI)

One rename: "server card" → "context card"

Part I called it a "visible MCP server card". That name was a mistake I'll own. MCP Server Cards are a separate, spec-level idea: metadata that describes a server. What Part I meant, and what Part VI shows, is the context card: the project context an agent actually sees. From here on it's "context card" everywhere.

Works with Skills over MCP

Skills over MCP (SEP-2640) lets an MCP server serve its skills right alongside its tools, as skill:// resources the agent loads when they're relevant. Angie Jones put the idea in one line:

"Essentially, ship the manual with the product."
Angie Jones, Skills Over MCP

So the agent has the tools, and now it has the manual. One question is still open: what are we building, for whom, and why?

That's project context, and it's what Context over MCP serves: the AGENTS.md rules, memory and identity the agent would have read from disk if it had a working directory. Tools say what the agent can do. Skills say how. Context says what, for whom and why.

Skills over MCP ships the manual for the tools. Context over MCP ships the facts about your project. An agent needs both to do the right thing in the right place.

It's timely, too. Agent Skills, the SKILL.md format, is on its way to becoming an AAIF project, and AAIF has already called MCP and Skills "the two halves of a working agent". Project context is what tells those two halves where they are.

Skills + Context over MCP = an agent informed and ready.

FAQs

Does this replace AGENTS.md? No. AGENTS.md stays the source. Everything here is about getting the same context to agents that can't open the file.

My agent reads AGENTS.md fine. Do I need any of this? Not for a local coding agent in your repo. It matters when the agent reaches your project over MCP, from another machine, or from a browser.

Which clients show the card inline? Hosts that support MCP Apps render it inline; Part VI shows it in the MCP Apps reference host. Elsewhere you get the text card and a browser view, which is how Part VI shows it in goose.

Is WebMCP in every browser? No. Chrome has native support behind a flag (Parts IV and V ran in Chrome 153 with it on). Elsewhere, the polyfill covers it.

Stateless or stateful? The context card server runs over stdio and stateless Streamable HTTP, which keeps it simple to host. The WebMCP pieces run in the browser tab itself.

What I'd do differently

Name things once. The "server card" slip cost a rename. Check a name against the spec vocabulary before it goes in a title.
Lead with the picture. Part VI's card made the whole series click for readers. I'd show it in Part I.
Ship the tutorials first. The how-to pieces travelled further than the explanations. A run-it-yourself version of every idea, from the start.

What's next

A goose docs contribution for the context card is next, so the extension setup lives where goose users already look.

Thanks for reading along. Questions and corrections are welcome in the comments.

One engine, one number: how six scoring engines came to agree

wolfejam.dev — Sun, 04 Oct 2026 19:31:04 +0000

The same project.faf used to score 64 in one FAF tool and 100 in another. Not because either was broken: each tool had learned to score on its own, and they mostly agreed.

Mostly isn't good enough for a number people rely on. So we rebuilt it: one engine under every tool, and a test matrix that proves they agree. This is how it works, and the patterns are worth stealing for any product that has to give the same answer in several places.

What's being scored

project.faf is a small YAML file at a repo's root that tells any AI what the project is: what it does, who it's for, the stack, how to build it. FAF scores it from 0 to 100% for AI-readiness: how much of what an AI needs is actually written down.

Isn't that what AGENTS.md is for? We hear this a lot. They work together. AGENTS.md, the open standard, instructs: how to build, test and work in the repo. project.faf defines: what the project is, as validated facts.

FAF defines. AGENTS.md instructs. AI codes. If you already keep an AGENTS.md, project.faf doesn't replace it: it's the source of facts behind it, the same way it sits behind CLAUDE.md. One command writes them in: faf export --agents.

The score has to be trustworthy, because people gate on it. A CI check fails below a threshold. A team compares repos. An agent decides whether it has enough context to start.

Why the scores drifted

FAF grew one tool at a time: a CLI, then MCP servers for Claude, the IDEs, Gemini and Grok, then a Python SDK, then a hosted edge. Each one learned to score.

Two things drifted:

The slot model. The CLI counted 21 slots, while the newer scorers counted 33, with 12 enterprise slots (infrastructure, app, operations). The same file could read 21 of 21 in one place and 21 of 33 in another.
The implementations. Small differences crept in: placeholder values, rounding, slot names. Before the fix, the hosted scorer matched the reference on only 47 of 80 FAF repos.

The fix: always 33, and one engine

The model first. Every .faf is scored against the same 33 slots. A slot is in one of three states:

empty: every slot starts empty until it's filled. A placeholder such as tbd or todo still counts as empty.
populated: it holds a real value. A validated fact.
slotignored: the project's app type defines which slots it needs. The rest are marked not applicable, as slotignored, so there's no doubt, and they drop out of the count.

How FAF defines. A validated fact comes from only two places: the repo, which faf auto reads (runtime, build, CI, hosting), or a person, who writes or approves what code can't show (the goal and the who, what and why) through faf go. Nothing is guessed. That's why a placeholder counts as empty: it has no source.

The score is populated slots divided by active slots. A typical app fills the 21 base slots and marks the 12 enterprise slots slotignored: 21 of 21, so 100%. At 100%, every definition slot for the app type is filled: AI is optimized to code. The same file without those markers is 21 of 33, so 64%. That difference was the whole bug, made explicit.

Then the engine. The scoring logic lives in one place, and that place is Rust.

Why Rust: one engine has to run everywhere FAF does. Rust compiles to WebAssembly, so the same compiled code runs inside a Node CLI, behind the MCP servers and on Cloudflare's edge. There's one source and no ports to keep in step. A JavaScript copy and a Workers copy would be two more places to drift.

faf-kernel, a Rust crate (v1.1.1), is the engine.
It compiles to WebAssembly and ships on npm as faf-scoring-kernel.
faf-cli v8 carries that WASM build. faf score is the kernel.
The MCP servers (claude-faf-mcp v7, faf-mcp v4, grok-faf-mcp v2) don't score at all. They compose faf-cli in-process, so they return faf-cli's answer. They never shell out to a faf on your PATH, so the answer doesn't depend on what's installed on the machine.
mcpaas.live v1.8, the hosted edge on Cloudflare, runs the kernel itself on every hosted route, plus the README badges and repo cards.

That covers every JavaScript and edge surface with one copy of one engine. Python is the exception.

Where you can't compose, prove parity

faf-python-sdk v2 is a pure-Python implementation of the same rules. A second implementation is exactly how drift starts, so it comes with a parity test.

The test scores 845 files with both the kernel and the SDK, and compares more than the final number:

the score;
the tier;
the slot counts;
every slot's state, slot by slot.

The files range from real project.faf files to deliberately awkward YAML. Result: 845 of 845 match. The SDK also never raises: unreadable YAML scores 0 with every slot empty, for any str or bytes input.

from faf_sdk import score_faf

result = score_faf(open("project.faf").read())
print(result.score, result.tier)

gemini-faf-mcp v3 scores through that SDK, so Gemini inherits the parity for free.

The proof: 54 of 54

A claim like "every tool agrees" is only worth what you can check. So on September 30 we scored nine public project.faf files through six engines: the kernel, faf-cli, the Python SDK, and the three hosted MCP routes.

File	kernel	faf-cli	Python	/claude	/grok	/faf
agents-md-facts	52	52	52	52	52	52
mcp-context-card	56	56	56	56	56	56
claude-faf-mcp	100	100	100	100	100	100
faf-cli	100	100	100	100	100	100
faf-mcp	100	100	100	100	100	100
faf-python-sdk	100	100	100	100	100	100
gemini-faf-mcp	100	100	100	100	100	100
grok-faf-mcp	100	100	100	100	100	100
faf-cli, no markers	36	36	36	36	36	36

Nine files, six engines, 54 scores, all equal. claude-faf-mcp, faf-mcp and grok-faf-mcp score through faf-cli, and gemini-faf-mcp through the Python SDK, so the table covers them too.

The non-100 rows matter as much as the 100s. Agreeing on 52 and 56 shows the engines agree on partial credit, which is where implementations usually drift. The last row is the faf-cli file with its slotignored markers stripped: 36 everywhere, until you add them back.

The table is the September 30 run. Both partial files have since reached 100%: agents-md-facts with a single faf auto, the command in the next section.

Upgrading is one command

This was a breaking change on purpose. A file written before always-33 has no enterprise markers, so its 12 enterprise slots now count as empty, and a 21-slot file drops to 64%.

The fix is to run this once in the project:

npx faf-cli auto

It writes the 12 slotignored markers (unless your app type actually uses those slots), and the score returns. On four real v7-era files: 56 → 100, 56 → 100, 58 → 100, 52 → 100.

If anything gates on the score, such as a CI threshold, re-check the number after upgrading. A new file from faf init, faf auto or faf git already carries the markers.

Patterns worth stealing

None of this is specific to FAF. If your product computes the same answer in several places:

Make the model explicit before the code. "Not applicable" is not the same as "empty". Once that's a named state, half the disagreements disappear.
Compose, don't reimplement. Every surface that can call the one engine should. Our MCP servers went from "scoring" to "asking faf-cli", and a whole class of bugs went with it.
Where you must reimplement, test parity on every field. Comparing the final number hides compensating errors. Compare every intermediate state.
Publish the matrix. Real files, every engine, the partial scores included. It's the cheapest credibility there is.
Never resolve the engine from PATH. In-process composition means the answer is a property of the package version, not the machine.

Try it

Paste either into your terminal or AI 👇

bunx faf-cli auto

Install it:

npm i -g faf-cli

★ bookmark repo: github.com/Wolfe-Jam/faf-cli

Then ask Claude, your IDE, Gemini or Grok for the score. It will be the same number.

The full release series, one post per product: The Always33 Suite.

Help guide what we build —
Comments · suggestions welcome.

Context Over MCP, Part VI: Context You Can See

wolfejam.dev — Thu, 01 Oct 2026 13:09:12 +0000

Part I asked: Invisible AGENTS.md? Here's the fix.

Your coding agent works from context: the project's AGENTS.md, the facts
it remembered last week, what it thinks this project is. It reads all of
that before it writes a line. You don't see any of it. When the agent does
something odd, you go digging: open the repo, find the file, scroll, guess
which part it took to heart.

Context is vital. But context you can't see is context you can't check.
Cards are better when they're visible.

TL;DR — see what your AI sees. Nothing to configure.

Talk to it (goose): add the mcp-context-card extension, open your project, and say "Show me my context card."

Terminal: in your project, run npx mcp-context-card card.

Either way the full card opens in your browser. The rest of this post is
the deeper dive.

The repo: mcp-context-card: one MIT server for a project's context, memory and identity. 10 tools, 134 tests, on npm and the official MCP Registry, tested in goose.

Try it: the goose way

This is the easy route. You talk to goose; goose shows you the card.

Add the extension. In goose Desktop: Extensions → Add custom extension. Type Standard IO, command:

   npx -y mcp-context-card

Nothing else. No path, no environment variable.

Open your project. Point goose's working directory at the project you want to see: the folder chip at the bottom of the chat.
Ask:

Show me my context card.

The server's reply leads with what it did, as a plain fact: New file:
(or Updated:) context-card.html in your project, and the path. The
model may put that in its own words; in the screenshot below it says the
card was "saved to the project and opened in your browser."

Then comes the card as text: the project's name and description, its
AGENTS.md sections, the first sentence of each memory fact word for word,
and where each one lives. At the same moment the full card opens in your
browser.

browser" width="799" height="518">

How did it know which project? The server asks the host which folder
you're working in, through the standard MCP roots request, and reads
that folder. In goose, that's the folder chip. Switch it, and the next card
follows.

The file it saved is yours to keep. It's a snapshot of what your agent
reads, next to the code it describes.

Try it: the terminal way

No AI, no host. In your project folder:

npx mcp-context-card card

It writes context-card.html and opens it in your browser. Add
--expanded to open every section, for a screenshot or a review with
someone else.

What the card shows, and why it helps

One page, four parts:

Identity — what this project says it is: name, version, status, license, one line of description.
Context — your AGENTS.md, every section, collapsed so the card scans in one screen. Open any section, or all of them.
Memory — every fact the agent has been asked to remember, with a mark on the ones that are verified.
Discovery — where each of those lives, and in what format, so a machine can find it too.

That's the same material your agent reads. Seen as a page, it does three
things the files alone don't:

It shows intent. The top of the card is the purpose of the project, stated once. If that line is wrong, everything downstream is aimed wrong.
It shows alignment. Reading the card, you see what the agent will see. A stale build command or a fact that stopped being true stands out on a card in a way it never does in a file you haven't opened in a month.
It puts you back in the loop. You check the context before the agent acts on it, not after, without digging through the repo.

A thirty-second review before a big task:

Is the one-line purpose still true?
Are the build and test commands the ones you actually use?
Is anything in memory out of date?

Whatever's wrong on the card is wrong in what the agent reads. Fix the
file, ask again, and the card follows. It's generated from your files every
time, so it can't drift from them.

An empty project is a starting point

Try it on a project with no AGENTS.md and the card doesn't stop at
"nothing here". Each empty section says what to do next:

Context: No AGENTS.md yet. Ask your agent to draft one. The server's author_agents_md tool builds one from the repo's real build and test commands, with nothing invented. Outside a chat, npx agents-md-facts writes the same facts.
Memory: No facts yet. Ask your agent to remember something, and it lands here.

So the first card shows you the gap and the next step in the same place.

In other hosts

The same server works in any MCP host. For hosts that take a JSON entry
(Claude Desktop, Cursor, and others):

{
  "mcpServers": {
    "context-card": {
      "command": "npx",
      "args": ["-y", "mcp-context-card"]
    }
  }
}

In Claude Code, from your project folder:

claude mcp add context-card -- npx -y mcp-context-card

The server finds your project the same way everywhere: the host's MCP
roots first, then the folder it was started in, if that has an
AGENTS.md. Ask "Which project are you reading?" and it tells you the
path and how it found it. To pin one project regardless, set
MCP_CONTEXT_CARD_ROOT to its path.

What you see depends on the host:

Hosts that support MCP Apps (the MCP extension for interactive UI) show
the full card inline, in the chat. When the host says so as it connects,
the model gets a one-line summary instead of a page of HTML.

That's the MCP Apps reference host drawing the card. It renders apps but
doesn't announce that when it connects, so its Tool Result panel still
shows the full HTML: the server can only shorten what it knows the host
will draw.

Every other host gets the text card in the chat, as in the goose example
above, and the full card in the browser. The reply also carries a link to
the file, and its address in a code block you can copy, for hosts that won't
open a local file link.

Before this, asking for the card put about 16,500 characters of raw HTML
into the chat. Now the reply is about 1,700, and it's something you can
read. Ask for the full detail if you want every memory fact in full; the
saved page always has everything.

Keep it true, with you in the loop

A card you can see changes how you work with memory.

Remember that the API tests need DATABASE_URL set.

remember and forget are marked as tools that change your project, so a
host that respects that asks you first. In goose, that's the approval
mode: Manual asks before every tool, and Smart asks before any
tool marked as changing your project. You'll see the request and approve
it. Then ask for the card again, and there's the fact, on the page.

When a fact goes stale, you'll notice it on the card before the agent acts
on it. Ask it to forget or correct it. Memory is a plain file in your repo,
so it goes through code review like everything else.

That's the loop: the agent reads context, you see the same context, and
either of you can fix it.

How it works, for builders

If you run your own MCP server, the pattern is small, and it needs nothing
beyond the standard SDK.

Ask the host which project. Clients that support roots list the folders the user is working in. Read the first file:// root, and listen for the roots-changed notification. No config for the user to get wrong.
Declare a UI resource. A ui:// resource with the MIME type text/html;profile=mcp-app, serving the card as one self-contained HTML page: inline CSS, no external requests.
Link the tool to it. The tool that renders the card carries _meta.ui.resourceUri pointing at that resource. Hosts that support MCP Apps fetch it and draw it.
Check what the client can do. A client that supports MCP Apps can declare it when it connects. Send those clients a one-line summary; send everyone else what they got before.
Don't strand the rest. A second tool saves the card, opens it when the server is local, and replies with the card as text, leading with what it did. Server instructions tell the model to use it instead of pasting HTML.
Keep the text honest. Each memory fact in the short view is cut at the end of its first sentence, exactly as stored. When we cut mid-sentence with "…", the model tidied the endings into sentences of its own. Memory is the one thing it shouldn't reword.

The code is MIT: mcp-context-card.
To build an MCP App of your own and try it in goose, the goose docs walk
through it: Building MCP Apps for goose.

Check it yourself

Add the extension to goose with just npx -y mcp-context-card, open a project, and ask "Show me my context card." The card is that project's, saved in that project's folder, and it opens in your browser.
Switch goose to a different project and ask again. The card follows.
In a terminal, in any project with an AGENTS.md, run npx mcp-context-card card. Its sections match your file's headings. Change a line in AGENTS.md, run it again, and the card shows the change.
Ask the agent to remember a fact, then ask for the card again. The fact is on it.

(Checked 27–30 September 2026: mcp-context-card 1.3.0, installed from npm,
in goose Desktop 1.52.0 and in the MCP Apps reference host.)

Context was always there. Now you can see it, and so can everyone
reviewing the work with you.

Thanks for reading, and to everyone who's followed Context Over MCP since Part I.

Tried it? Tell me in the comments what your card showed you, and what it got wrong. That's what shapes the next version.

No time right now? ★ bookmark the repo and come back before your next big task. One command, and you'll see what your agent sees.

The series, Context Over MCP:

Part I — Invisible AGENTS.md?
Part II — Publishing to the Registry
Part III — Horses for Courses
Part IV — No Working Directory At All
Companion — Build a WebMCP Tool From Scratch
Part V — The Form Is the Tool
Part VI — Context You Can See (this post)

Context Over MCP: Part V The Form Is the Tool.

wolfejam.dev — Fri, 25 Sep 2026 22:38:16 +0000

Part IV showed a WebMCP page with three tools. The companion walked through
building one yourself, the JavaScript way: registerTool(), a schema, a
handler. It mentioned the other way in one sentence and moved on.

This is the other way. No registerTool(), and no schema written by hand.
It's an HTML form, with a few attributes that tell the browser it's also a tool.

The playground from Part IV is now listed in the W3C Web Machine Learning
group's awesome-webmcp,
under Demos. That page is the production version of what you're about to build.

Save a blank index.html, serve it with python3 -m http.server, and open
http://localhost:8000 in Chrome with chrome://flags/#enable-webmcp-testing
turned on. Opened straight from disk, the page has no origin and the tool won't register.

Step 1 — start with a form that already works

Before it's a tool, it's a form a person can use. This one estimates a
shipping price. It's read-only: it calculates a number and places no order.

<form id="ship">
  <label>Weight (kg)
    <input name="weight_kg" type="number" min="0.1" max="30" step="0.1" required>
  </label>
  <label>Destination
    <select name="zone" required>
      <option value="domestic">Domestic</option>
      <option value="eu">EU</option>
      <option value="world">Rest of world</option>
    </select>
  </label>
  <label>Speed
    <select name="speed">
      <option value="standard">Standard</option>
      <option value="express">Express</option>
    </select>
  </label>
  <button type="submit">Estimate</button>
  <p>Result: <output id="result"></output></p>
</form>

<script type="module">
const RATES = { domestic: 4, eu: 9, world: 18 };

function estimate({ weight_kg, zone, speed }) {
  const w = Number(weight_kg);
  if (!Number.isFinite(w) || w < 0.1 || w > 30) {
    return { error: 'invalid_weight', message: 'weight_kg must be between 0.1 and 30' };
  }
  if (!Object.hasOwn(RATES, zone)) {
    return { error: 'invalid_zone', message: 'zone must be domestic, eu or world' };
  }
  const base = RATES[zone] + w * 1.5;
  const price = speed === 'express' ? base * 1.8 : base;
  return { price_eur: Math.round(price * 100) / 100, zone, speed: speed || 'standard' };
}

const form = document.getElementById('ship');
form.addEventListener('submit', (event) => {
  event.preventDefault();
  const result = estimate(Object.fromEntries(new FormData(form)));
  document.getElementById('result').value =
    result.error ? result.message : `€${result.price_eur}`;
});
</script>

Submit it by hand. You get a price, and the URL doesn't change. This is the
same order as the companion's Step 2: the logic is a plain function before
anything calls it.

Step 2 — add three attributes, and it's a tool

<form id="ship"
      toolname="estimate_shipping"
      tooldescription="Estimate the shipping price for one parcel. Returns price_eur. Does not place an order."
      toolautosubmit>
  <label>Weight (kg)
    <input name="weight_kg" type="number" min="0.1" max="30" step="0.1" required
           toolparamdescription="Parcel weight in kilograms, 0.1 to 30">
  </label>
  <label>Destination
    <select name="zone" required toolparamdescription="Destination zone: domestic, eu or world">
      <option value="domestic">Domestic</option>
      <option value="eu">EU</option>
      <option value="world">Rest of world</option>
    </select>
  </label>
  <label>Speed
    <select name="speed" toolparamdescription="standard or express">
      <option value="standard">Standard</option>
      <option value="express">Express</option>
    </select>
  </label>
  <button type="submit">Estimate</button>
  <p>Result: <output id="result"></output></p>
</form>

toolname names the tool.
tooldescription tells the agent what it does. Say what it doesn't do too ("does not place an order"), so the agent doesn't have to guess.
toolparamdescription on each control becomes that parameter's description.

You don't write the schema. The browser builds the tool's input schema from
the form's named controls, and it reads more of the form than you might
expect. Here's what Chrome 153 generated from the form above:

{
  "type": "object",
  "properties": {
    "weight_kg": { "type": "number", "minimum": 0.1, "maximum": 30, "multipleOf": 0.1,
                   "description": "Parcel weight in kilograms, 0.1 to 30" },
    "zone":      { "type": "string", "enum": ["domestic", "eu", "world"],
                   "description": "Destination zone: domestic, eu or world" },
    "speed":     { "type": "string", "enum": ["standard", "express"],
                   "description": "standard or express" }
  },
  "required": ["weight_kg", "zone"]
}

min, max and step became minimum, maximum and multipleOf. Each
<select> became an enum (Chrome also adds each option's label as a
title, trimmed here). required became required. That's convenient, and
it's also the main thing to remember in Step 5.

Notice the <output> has an id and no name. That's deliberate: it shows
the result and isn't something the agent should fill in.

Step 3 — answer the agent, not just the screen

With toolautosubmit, the agent's call fills the fields and submits the form.
Your submit handler runs as usual. To hand the result back as the tool's
output, call respondWith() on the submit event:

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const result = estimate(Object.fromEntries(new FormData(form)));
  document.getElementById('result').value =
    result.error ? result.message : `€${result.price_eur}`;
  if (typeof event.respondWith === 'function') {
    event.respondWith(Promise.resolve(result));
  }
});

Three details:

preventDefault() first. Without it, the form navigates, and the page that registered the tool goes away mid-call.
The form's rules are the tool's rules. Because max and the <option> list are in the schema, Chrome checks them before your handler runs. An agent that asks for 99 kg gets Form validation failed: weight_kg: Value must be less than or equal to 30., and one that asks for zone "mars" gets Invalid value "mars" for parameter zone. The checks in estimate() are a second line of defense, for the day someone edits the form and forgets the function. Anything that gets past the form comes back as { error, message }, as in the companion's Step 3.
The typeof guard. In a browser without WebMCP, respondWith doesn't exist, the guard skips it, and the form is still a working form.

Chrome also sets event.agentInvoked to true when an agent submitted the form,
if you want to behave differently for agents. Here, the answer is the same for
anyone who asks.

Step 4 — decide who presses Submit

toolautosubmit is a decision, not a default.

With it: the agent fills the fields and the form submits. That's right for
this tool: it's read-only and nothing happens that someone would want to review.

Without it: the agent fills the fields, and a person has to click Submit.
That's right for anything with consequences, and it's the reason the attribute
is opt-in.

One thing to know before you remove it: from the caller's side, that call
stays pending until someone submits or cancels. A conventional MCP client
talking to the page can't tell "waiting for a human" from "stuck" (see
webmcp#307). If a
person needs to confirm, make the waiting visible on the page.

Chrome gives you hooks for that:

form:tool-form-active { outline: 2px solid #00D4D4; }
button:tool-submit-active { box-shadow: 0 0 0 3px #00D4D4; }

window.addEventListener('toolactivated', (event) => {
  if (event.toolName === 'estimate_shipping') {
    document.getElementById('result').value =
      'An agent filled this form. Check it, then press Estimate.';
  }
});

toolactivated fires when the agent has filled the fields. It fires on
window, not on the form (a listener on the form never hears it), so check
event.toolName if the page has more than one tool.

If the page resets the form while the agent waits, the call ends with an
error: Tool execution cancelled by a form reset. Chrome's docs also describe
a toolcancel event; in Chrome 153 I didn't see it fire on a reset, so don't
depend on it yet.

Step 5 — the fields that should never become parameters

Step 2's convenience has a cost. Every named control becomes something an
agent can fill in. For a shipping form, that's fine. For a checkout, login or
identity form, it means card numbers, CVVs, one-time codes and national ID
numbers become agent-fillable parameters, and they end up in a transcript.
A checkout form with name="cvv" becomes a tool with a cvv parameter.

The spec doesn't have guidance for this yet
(webmcp#316 is open).
Until it does, a simple rule:

Don't make a sensitive form a tool. Make a smaller form that is one: "estimate", "check availability", "find a slot". Let the person handle the part with their card or code themselves.
If a form must be a tool, leave sensitive controls out of it. A control without a name isn't submitted with the form. Do that on purpose, and say it in tooldescription ("payment details are entered by the user").
Read-only tools can auto-submit. Anything else shouldn't.

The whole page

Everything from Steps 1–4 in one file, for copying:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Shipping estimate</title>
  <style>
    form:tool-form-active { outline: 2px solid #00D4D4; }
    button:tool-submit-active { box-shadow: 0 0 0 3px #00D4D4; }
  </style>
</head>
<body>
<form id="ship"
      toolname="estimate_shipping"
      tooldescription="Estimate the shipping price for one parcel. Returns price_eur. Does not place an order."
      toolautosubmit>
  <label>Weight (kg)
    <input name="weight_kg" type="number" min="0.1" max="30" step="0.1" required
           toolparamdescription="Parcel weight in kilograms, 0.1 to 30">
  </label>
  <label>Destination
    <select name="zone" required toolparamdescription="Destination zone: domestic, eu or world">
      <option value="domestic">Domestic</option>
      <option value="eu">EU</option>
      <option value="world">Rest of world</option>
    </select>
  </label>
  <label>Speed
    <select name="speed" toolparamdescription="standard or express">
      <option value="standard">Standard</option>
      <option value="express">Express</option>
    </select>
  </label>
  <button type="submit">Estimate</button>
  <p>Result: <output id="result"></output></p>
</form>

<script type="module">
const RATES = { domestic: 4, eu: 9, world: 18 };

function estimate({ weight_kg, zone, speed }) {
  const w = Number(weight_kg);
  if (!Number.isFinite(w) || w < 0.1 || w > 30) {
    return { error: 'invalid_weight', message: 'weight_kg must be between 0.1 and 30' };
  }
  if (!Object.hasOwn(RATES, zone)) {
    return { error: 'invalid_zone', message: 'zone must be domestic, eu or world' };
  }
  const base = RATES[zone] + w * 1.5;
  const price = speed === 'express' ? base * 1.8 : base;
  return { price_eur: Math.round(price * 100) / 100, zone, speed: speed || 'standard' };
}

const form = document.getElementById('ship');
const out = document.getElementById('result');

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const result = estimate(Object.fromEntries(new FormData(form)));
  out.value = result.error ? result.message : `€${result.price_eur}`;
  if (typeof event.respondWith === 'function') {
    event.respondWith(Promise.resolve(result));
  }
});

window.addEventListener('toolactivated', (event) => {
  if (event.toolName === 'estimate_shipping') {
    out.value = 'An agent filled this form. Check it, then press Estimate.';
  }
});
</script>
</body>
</html>

Step 6 — verify it before you add anything else

In Chrome with the WebMCP flag on, document.modelContext also has
getTools() and executeTool(), so you can play the agent from the console.
Run these in order:

The tool is there, with the schema from Step 2.

   const [tool] = await document.modelContext.getTools();
   JSON.parse(tool.inputSchema);

tool.name is estimate_shipping, and the schema has minimum, maximum, the two enums and required: ["weight_kg", "zone"].

A valid call returns a value, and the page stays put.

   await document.modelContext.executeTool(tool,
     JSON.stringify({ weight_kg: 2, zone: 'eu', speed: 'standard' }));

It returns '{"price_eur":12,"zone":"eu","speed":"standard"}', the page shows €12, and the URL doesn't change. Two things to note: executeTool takes the tool object from getTools(), not its name, and the result comes back as a JSON string.

Invalid calls are rejected by the form. Try { weight_kg: 99, zone: 'eu' } and then { weight_kg: 1, zone: 'mars' }. Both reject, with Form validation failed: weight_kg: Value must be less than or equal to 30. and Invalid value "mars" for parameter zone. Your handler never runs.
Without autosubmit, the call waits for a person.

   document.getElementById('ship').removeAttribute('toolautosubmit');
   const pending = document.modelContext.executeTool(tool,
     JSON.stringify({ weight_kg: 5, zone: 'world', speed: 'express' }));

The fields fill, the outline appears, the result line says an agent filled the form, and pending doesn't settle. Press Estimate: it resolves with '{"price_eur":45.9,"zone":"world","speed":"express"}' and the outline goes away.

Nothing leaves the tab. Open DevTools → Network and repeat step 2. No requests.

(Checked in Chrome 153 with #enable-webmcp-testing on, 25 September 2026.)

The same shape, in production

fill_6ws on faf.one/webmcp is this pattern: a plain
form with toolname, tooldescription, toolautosubmit and a
toolparamdescription on each of its six fields. It calls
preventDefault(), answers with respondWith({ yaml }), and doesn't navigate.
It auto-submits for the same reason Step 4 gives: it builds text and changes nothing.

Pick by what the page already has. If it already has a form that does the
job, the form is the tool. If it doesn't, registerTool() is there.

Series: Part I — Invisible AGENTS.md? · Part II — Publishing to the Registry · Part III — Horses for Courses · Part IV — No Working Directory At All · Build a WebMCP Tool From Scratch.

"Pack of Cards: five agent-card specs, drawn as one map"

wolfejam.dev — Tue, 22 Sep 2026 15:59:18 +0000

TL;DR: Machines find an agent or a server through cards — small files they read. Five seem prominent. Every spec lives in public git, so we read every version and drew them as one map, after Harry Beck's Underground diagram.

In Plain English

Five cards. Five specs, all in public git.
Eight choices. Every card picks a name field, an identity, a discovery path, a media type, an encoding, an extension point, a trust model and a versioning rule.
One centre. The centre line is what most cards share. Distance is what only one card does.

First, the one that is not a card

We followed the MCP Registry closely, so start there. server.json is the Registry entry — how a server gets published, rather than a card a server serves at its own door. It is not on the map, and it is the piece faf-cli writes today:

faf cards --target registry

32,237 latest-version entries, counted page by page from the Registry API on 2026-09-15. Server Card Rev 1 borrowed its shape, which is where that line branches from.

Then the cards

Five. A2A Agent Card, MCP Server Card, AI Catalog, ARD and .fafa.

A2A reached Released v1.0 and joined AAIF at Growth Stage on 2026-08-27 — the one other specs point at when they need to describe an agent and would rather not invent a card. AI Catalog is moving fastest: MCP's own MCP Catalog is evolving into it, and the spec turned over #37 and #77 five weeks apart. ARD says Proposal. .fafa is ours.

They overlap, they disagree, and they are all in public git. So we read every version.

How to read it

Beck's 1933 diagram dropped geography and kept order. We did the same with time.

Time runs west to east. Each card is a line. Each station is a spec change, spaced by order, not by calendar. A ring marks the day two cards start or stop sharing a choice.

Two views. Protocol ↔ Envelope (the default): cards defined by one protocol sit above the centre, protocol-neutral envelopes below. Strict ↔ Loose: each card's required fields against the median.

The map as a band. The live version is interactive — hover a station, follow a tick to the spec at that commit, switch the view.

What it shows

A2A opens alone. The map starts with A2A v0.2.0 in May 2025. Nothing to compare it with until MCP Server Card's first draft, SEP-2127, on January 21, 2026.
Twins. On June 25, 2026, AI Catalog merged #37 and #36. With ARD v0.9 already on urn:air, the two met on the centre line.
A step in. On July 20, MCP Server Card moved discovery to /.well-known/ai-catalog.json.
The split. On August 26, ARD v0.91 took its own ard.json, JSON-LD and a trust manifest. The twins parted. AI Catalog moved that day with no spec change of its own. Distance is relative.
Furthest out: .fafa. The only card with an IANA-registered media type, and the only one written in YAML. Registering moved it one step further out. Different, not wrong.

How it's built

30 spec versions. 269 quotes, each checked against its line at its commit. Every station links to the spec at that commit, and every value links to the line it was quoted from — the register is public, so any figure here can be checked.

We make .fafa. So the rules came first, and .fafa landed where the rules put it.

The choice list is a judgement. A different list draws a different map. The quotes are public, so anyone can check it, or redraw it.

Some interesting facts

A2A was alone for 245 days. The first card landed on 2025-05-21. There was nothing to compare it with until 2026-01-21.
Five cards, five different extension points. Of the eight choices we track, extension is the only one where no two cards agree.
A2A asks for eight required fields. AI Catalog asks for three.
AI Catalog shipped eight versions in 141 days. A2A shipped six in 479.

Three ways to name a card

A media type is the label a machine reads before it opens the file.

None of these five specs requires one. They landed on three different answers.

A2A Agent Card and ARD name no media type.

AI Catalog uses application/ai-catalog+json. MCP Server Card uses application/mcp-server-card+json. Neither is registered.

.fafa uses application/vnd.fafa+yaml, registered with IANA on 2026-06-26.

Every value above links to the line it was quoted from.

What it cost us to keep up

The map carries our own lane too, because keeping up is the hard part and we have not always managed it.

AI Catalog merged #37 on June 25. We conformed on June 26 — one day.

AI Catalog merged #77 on July 30, moving extensions to a map. We answered in three days and used an array. It stayed wrong for forty-five, and working group parsers rejected the document the whole time.

Speed is not currency on its own. The check is.

Five, out of thirty-six

Five cards are drawn. We checked thirty-one more against one test: a public spec with git history, describing an agent or a server so machines can find it. Eight pass, seven are borderline, sixteen are out — each listed with the reason, on the page.

A card that does not make the map is not a lesser card. It is a card that answers a different question.

Get your pack

Seven answers describe an agent or a server: name, short name, domain, what it does, version, where it runs, what it can do. From those, faf-cli writes the .fafa and projects every card that has a place for it — correct to each spec, checked by each spec's own validator.

npx faf-cli@latest cards --target catalog,ard

The map · the register · how the cards work

Context Over MCP: Build a WebMCP Tool From Scratch

wolfejam.dev — Tue, 15 Sep 2026 12:30:00 +0000

Part IV showed three tools already registered, already working, on someone
else's page. This is the version where you register one on yours — a real
tool, with the same failure modes any WebMCP tool has, fixed the same way.

No build step, no bundler, no dependency you haven't chosen yourself. Save a
blank index.html, serve it with python3 -m http.server, open
http://localhost:8000, and follow along. Opened straight from disk, the page
has no origin and the tools won't run.

Step 1 — detect WebMCP, don't assume it

document.modelContext exists natively in Chrome behind a flag
(chrome://flags/#enable-webmcp-testing). Everywhere else, a polyfill can
provide the same surface. Check for the real thing first, fall back
explicitly, and know which one you got — don't silently assume either:

<script type="module">
async function getModelContext() {
  if (document.modelContext?.registerTool) {
    return { context: document.modelContext, source: 'native' };
  }
  try {
    const { initializeWebMCPPolyfill } =
      await import('https://esm.sh/@mcp-b/webmcp-polyfill');
    initializeWebMCPPolyfill();
  } catch {
    return { context: null, source: 'none' };
  }
  return document.modelContext?.registerTool
    ? { context: document.modelContext, source: 'polyfill' }
    : { context: null, source: 'none' };
}
</script>

If source comes back 'none', stop here and fix that before writing a
single tool — everything below assumes a real context object.

Every block below goes inside the same <script type="module">.

Step 2 — write the tool as a plain function first

Don't reach for a real YAML parser or a scoring library yet. Prove the shape
works with something you can read in five seconds:

function scoreFacts(yaml) {
  const required = ['name', 'goal', 'who', 'what', 'why'];
  const present = required.filter((key) => new RegExp(`^\\s*${key}:`, 'm').test(yaml));
  return {
    score: Math.round((present.length / required.length) * 100),
    populated: present.length,
    total: required.length,
    missing: required.filter((k) => !present.includes(k))
  };
}

Five required keys, a regex check per key, a percentage. That's the whole
scorer. It's not what a real implementation should ship — it's what lets you
verify the registration works before you go anywhere near real parsing.
(The \s* matters: a real project's facts are usually nested — who:
sitting indented under a human_context: block, not at column zero. Test
this against a flat file only and it'll look like it works; test it against
a realistically nested one and a too-strict regex reports fields "missing"
that are right there, just indented.)

Step 3 — register it the way errors don't crash the caller

This is the part that's easy to get wrong: a WebMCP tool that throws is a
tool an agent can't recover from cleanly. Return errors as data, and validate
input before it reaches your function:

async function registerScoreTool(context) {
  await context.registerTool({
    name: 'score_facts',
    description: 'Score a structured facts document 0-100 by which required fields are present.',
    inputSchema: {
      type: 'object',
      properties: { yaml: { type: 'string', description: 'YAML text to score' } },
      required: ['yaml']
    },
    annotations: { readOnlyHint: true },
    execute: async (input) => {
      const yaml = typeof input?.yaml === 'string' ? input.yaml : '';
      if (!yaml.trim()) {
        return { error: 'invalid_input', message: 'yaml is required' };
      }
      try {
        return scoreFacts(yaml);
      } catch (err) {
        return { error: 'score_failed', message: err instanceof Error ? err.message : String(err) };
      }
    }
  });
}

Three things doing real work here, none of them optional:

annotations: { readOnlyHint: true } — tells the caller up front this can't change anything, before it ever calls the tool.
The empty-input check runs before scoreFacts — a missing field is a normal case, not an exception.
The try/catch around your own function means a bug in scoreFacts comes back as { error, message }, not a stack trace the caller has to parse to understand what happened.

Wire the two together and open the page:

getModelContext().then(async ({ context, source }) => {
  if (!context) return console.warn('WebMCP not available:', source);
  await registerScoreTool(context);
  console.log('score_facts registered via', source);
});

Step 4 — verify it before you add anything else

Install the Model Context Tool
Inspector,
open it on your page (the localhost URL, not the file), and check:

[ ] Inspector lists score_facts
[ ] Calling it with valid YAML (containing name:/goal:/who:/what:/why:) returns a score
[ ] Calling it with { yaml: "" } returns { error: "invalid_input", ... } — not a crash
[ ] The console logs which source registered it (native or polyfill)

If any of those fail, stop here. Everything past this point assumes a
working, verified tool.

Step 5 — the part most tutorials skip: don't trust a URL parameter

The moment a tool accepts a URL instead of pasted text — "fetch the YAML
from here" — it's fetching something the caller named, not something you
chose. That's a real risk, not a hypothetical one, and it needs the same
kind of explicit check execute got in Step 3:

const ALLOWED_HOSTS = new Set(['raw.githubusercontent.com']); // your trusted hosts only

function assertAllowedUrl(urlString) {
  const url = new URL(urlString); // throws on garbage input — let it
  if (url.protocol !== 'https:') {
    throw new Error('url must use https');
  }
  if (!ALLOWED_HOSTS.has(url.hostname)) {
    throw new Error(`host not allowlisted: ${url.hostname}`);
  }
  if (url.pathname.split('/').includes('mcp')) {
    throw new Error('mcp endpoints are not allowed');
  }
  return url;
}

Three checks, each closing a different door:

Exact hostname match, not a substring check — evil-raw.githubusercontent.com.attacker.net doesn't pass just because it contains the right string.
HTTPS only — a tool that fetches over plain HTTP hands a man-in-the-middle the exact document it's about to trust.
No mcp segment in the path — a page tool has no business talking to an MCP server; naming the block explicitly makes it a decision, not an accident.

Call it inside execute's try, before the fetch, so a rejected URL comes
back as { error, message }. Then fetch with redirect: 'error': a redirect
is a new request to a host your check never saw, and the browser sends it
before your code can read response.url.

Step 6 — the same shape, in production

This whole pattern — detect the context, register with readOnlyHint,
validate before executing, return errors as data, allowlist any fetch — is
the shape faf.one/webmcp uses for score_faf and emit_agents_md, with a
WASM scoring kernel where yours has a regex. Its third tool,
fill_6ws, takes the other route: a plain HTML form with toolname
attributes, registered by the browser. That page is one real,
production instance of it. It's not the only way to build one — it's what
happens when you take Steps 1 through 5 and keep going.

Companion to Context Over MCP, Part IV: No Working Directory At
All — the explainer that describes an already-built WebMCP page. This
is the version where you build one.

Context Over MCP, Part IV: No Working Directory At All

wolfejam.dev — Mon, 14 Sep 2026 16:26:34 +0000

Part I: an MCP client has no working directory, so it never sees your AGENTS.md.

Part II: publish the server so a client can find it.

Part III: keep facts as data and instructions as prose, so what it finds is worth seeing.

Now take the working directory away completely. WebMCP's client is a browser
tab, and a tab doesn't fail to find a working directory. It doesn't have the
concept.

So what does "expose your context" mean when there's no repo, no process, and
no server — just a page?

The API is not FAF's

document.modelContext.registerTool() is Chrome's own experimental API
(chrome://flags/#enable-webmcp-testing). A page registers a tool, an agent
inspecting that page calls it, done — no separate MCP process, no transport,
no working directory to have or lack. Where the native API isn't available,
@mcp-b/webmcp-polyfill — a real, independent package, not FAF's — provides
the same registerTool surface as a fallback:

const native = getDocumentContext();
if (native && typeof native.registerTool === 'function') {
  return { context: native, source: 'native' };
}
try {
  const { initializeWebMCPPolyfill } = await import('@mcp-b/webmcp-polyfill');
  initializeWebMCPPolyfill();
} catch {
  return { context: null, source: 'none' };
}
const polyfilled = getDocumentContext();
if (polyfilled && typeof polyfilled.registerTool === 'function') {
  return { context: polyfilled, source: 'polyfill' };
}
return { context: null, source: 'none' };

WebMCP doesn't care what you register. This is the part that matters more
than any specific tool: the platform capability is generic, open, and not
owned by anyone's product. What follows is one demonstration of it, not the
only shape it can take.

Three tools, two ways to register them

faf.one/webmcp registers three:

Tool	Returns
`score_faf`	`{ score, tier, populated, active, gaps }` — 0–100, in-browser
`fill_6ws`	a `human_context:` YAML fragment from a form
`emit_agents_md`	`{ markdown }` — a minimal AGENTS.md render

Those are Part III's three moves, in a tab: fill in the six W's, score what's
still blank, and write the AGENTS.md from the facts.

score_faf and emit_agents_md are registered in script with
registerTool(), and both carry annotations: { readOnlyHint: true }. That's
not a comment. It's part of the registration, and an agent can read it before
calling anything: the same trust signal MCP tool annotations give a client, now
on a web page instead of a server.

fill_6ws is a plain HTML form with toolname, tooldescription and
toolautosubmit attributes: the browser turns the form into the tool. If the
form isn't picked up, the page registers fill_6ws in script instead.

score_faf runs entirely client-side. The scoring kernel is WASM
(faf_wasm_sdk), compiled once from the same Rust source the CLI and the
edge workers use — no server round-trip, no MCP process to spin up:

export function scoreYaml(yaml: string): string {
  if (!ready) throw new ToolError('kernel_not_ready', 'WASM scoring kernel is not initialized');
  return score_faf(yaml);
}

And the result mapper refuses to pad the picture. Ignored slots — fields that
don't apply to this project — aren't counted as missing:

/** Score is populated/active. Ignored slots are not missing — 13/13, not 13/21. */

gapsFromSlots only reports what's genuinely empty. A tool that's willing to
inflate its own denominator to look better is exactly the kind of thing a
"structured facts" argument falls apart without.

The part that's honest about its own limits

emit_agents_md renders a real AGENTS.md — Setup & build, Run the tests,
Stack, 6Ws — from the same .faf fields the CLI reads. But the file's own
comment says what it isn't:

// Minimal renderer — not the full faf-cli AGENTS.md compiler.

It doesn't do Guardrails tiers, branch-aware Commit & PR, or any of the
richer sections the real compiler produces — because a browser tab is a
different environment with a different budget than a CLI process, and a
renderer that pretended otherwise would be lying about what ran. The output
says so too — a plain, one-line stamp at the foot: compiled from application/vnd.faf+yaml. Not "compiled with faf-cli." A different tool
made this.

The fetch surface is an allowlist, not a promise

score_faf and emit_agents_md can take a URL instead of pasted YAML. That
means the page fetches something the agent asked for — and a page that
fetches whatever a caller names is a real risk, not a hypothetical one. The
check is explicit, and it runs before anything is requested:

export function assertAllowedUrl(urlString: string): URL {
  const url = new URL(urlString);
  if (url.protocol !== 'https:') {
    throw new ToolError('invalid_url', 'url must use https');
  }
  if (!ALLOWED_HOSTS.has(url.hostname)) {
    throw new ToolError('invalid_url', `host not allowlisted: ${url.hostname}`);
  }
  if (url.pathname.split('/').includes('mcp')) {
    throw new ToolError('invalid_url', 'mcp endpoints are not allowed');
  }
  return url;
}

Two hosts only — faf.one, raw.githubusercontent.com — exact match, not a
suffix (their own comment: "ide.faf.one is not faf.one"). HTTPS only,
256KB cap. And a URL with an mcp segment in its path is rejected outright, by
name — the tool doesn't just happen to avoid talking to an MCP server, it
refuses to. A github.com/owner/repo link gets rewritten to the raw file
host before any of this runs, and fetchAllowedYaml refuses redirects
(redirect: 'error'), so the only URL the browser ever requests is the one
this check approved.

Updated 15 Sep: the page now refuses redirects. It used to re-check the final
URL after following them, which guards the response but not the request.
Thanks to @joinwell52 for the catch.

Try it

chrome://flags/#enable-webmcp-testing → enable → relaunch Chrome.
Open https://faf.one/webmcp (production needs HTTPS; localhost over plain HTTP works fine for local testing).
Install the Model Context Tool Inspector and open it on that tab.

Five things should be true:

[ ] Inspector lists score_faf, fill_6ws, emit_agents_md
[ ] score_faf on the loaded fixture returns a numeric score
[ ] Bad YAML returns { error, message } — not a thrown exception
[ ] The 6Ws form returns YAML and does not navigate the page
[ ] Network tab shows no call to any MCP server or /mcp URL —
    the only network activity is the one allowlisted YAML fetch

That last one is the actual claim of this piece, made checkable: nothing here
talks to a server. The tab did it.

What Part I asked, answered somewhere Part I didn't expect

Part I's problem was a client that can't see your AGENTS.md because it has
no way to walk to it. WebMCP's problem is stricter: there's no walking to
anything, ever — so the only way to expose context is to hand it over
directly, as tool calls, from wherever the process already lives. score_faf,
fill_6ws, emit_agents_md are one answer to that, running in the browser
because the browser is where this particular client already is.

The API that makes it possible isn't FAF's, and doesn't have to be. Register
whatever a page's own good judgment says an agent visiting it should be able
to call.

Series: Part I — Invisible AGENTS.md? · Part II — Publishing to the Registry · Part III — Horses for Courses · mcp-context-card.