Agent discovery

Most sites are built for humans and search engines. Very few are optimized for AI agents — the audience that's increasingly the first, and often only, reader.

This site is a small working example of what good agent discovery looks like: what an agent can actually do here, the protocols and tools behind it, and the research that shaped the decisions.

Live agent stats → every crawler visit and MCP tool call, logged in real time.

Capabilities

Things you (or your agent) can ask this site to do, via the MCP server below.

Search my Field Notes
Keyword search over every post, with snippets showing the match.
search_notes
Answer questions about my projects
Browse the agent, developer-experience, and product work in my portfolio.
get_portfolio
Get my resume
As structured JSON, plain markdown, or a link to the PDF download.
get_resume, download_resume
List or fetch a specific post
Metadata for every post, or the full raw markdown of one by slug.
list_notes, get_post
Get a quick summary of this site
Who I am and what tools are available, in one call.
about

Protocols

llms.txt

Should implement

A short markdown index of the site written for language models. Points at every page and every machine-readable file. Now a de facto standard for LLM-readable site maps — cheap to publish, obvious upside.

/llms.txt /llms-full.txt llmstxt.org ↗

Markdown mirrors

Should implement

Every page has a plain-markdown twin. Append .md to any URL, or send Accept: text/markdown. Agents can consume the site without parsing HTML or running JavaScript. Trivial to add, big win.

/resume.md /sitemap.md /AGENTS.md

Model Context Protocol

Should implement

A Streamable HTTP MCP server exposing typed tools. Any MCP client (Claude Desktop, Cursor, VS Code) can connect and query the site as a live data source. The spec still moves, but the client ecosystem has already converged — shipping now is right.

/api/mcp server card modelcontextprotocol.io ↗

agents.json

Too soon

Root manifest describing what an agent can do on the site — endpoints, tools, content-negotiation rules. Overlaps with the MCP server card. Spec is still emerging with no clear consensus. Publish it if it's cheap, but don't count on it yet.

/agents.json /AGENTS.md

Schema.org JSON-LD

Should implement

Structured data embedded on every content page. Person on /resume with full work history, Blog + BlogPosting on notes, WebSite on the home page, CollectionPage on /projects. Not new, but table stakes for knowledge graphs, rich results, and any agent that reads structured data.

/resume ai-catalog.json schema.org ↗

Agent-to-Agent (A2A)

Too soon

A protocol for agents to discover and delegate tasks to other agents via an Agent Card. Interesting fit for a site whose whole premise is agent discovery, but the spec and client ecosystem are still early — watching, not building yet.

a2a-protocol.org ↗

OpenAPI

Not necessary

A REST API spec would give tool-callers a schema without MCP. This site's only real API surface is the MCP server itself, so a parallel OpenAPI description would duplicate it for no real gain right now.

Tools

The MCP server at /api/mcp exposes these tools directly:

about() — Quick summary of the site and available tools.
get_resume() — Full JSON Resume of Ben McAdams.
download_resume() — Get links to download Ben's resume as a PDF or markdown file.
list_notes() — List blog posts (metadata only).
get_post() — Get the full markdown of a post by slug.
search_notes() — Keyword search over post bodies.
get_portfolio() — Portfolio of agent, DX, and product work.
trivia() — Play a short trivia game about Ben.

Research

Field notes on the protocols and decisions behind this page.

Two kinds of AI crawler
The split between training-style crawlers and user-side fetchers changes how I read a traffic spike.
Two agent auth specs, at once
Two proposals for agent auth landed the same week — same name, same problem, different mechanisms.
MCP is a toolbox. A2A is a coworker.
MCP and A2A get lumped together, but they solve different problems.
AI agents fetch pages differently
A 308 redirect broke ChatGPT's retrieval but not Claude's. Same URL, different behavior.
Markdown mirrors
Serving .md alongside HTML is cheap, and it makes agents parse your pages far more efficiently.

API

Every machine-readable file this site publishes.

Path	Purpose
/llms.txt	Index for language models
/llms-full.txt	Full content bundle (all pages + posts)
/AGENTS.md	Agent-facing guide (endpoints, tools, mirrors)
/agents.json	Root agent manifest
/robots.txt	Crawler directives
/sitemap.xml	Sitemap (XML)
/sitemap.md	Sitemap (markdown)
/feed.xml	RSS feed of notes
/.well-known/ai-catalog.json	Agent capability catalog (ARD)
/.well-known/mcp.json	MCP server card
/api/mcp	MCP server (Streamable HTTP) — resume, notes, portfolio tools
/*.md	Markdown mirror of any page (also via Accept: text/markdown)