Agent-accessible product

Designing products for agents as a first-class user class — the discipline Jeff Bailey systematizes in Fundamentals of Agent Accessibility (clippings/jeffbailey-us-blog-2026-04-11-fundamentals-of-agent-accessibility.md, 55 KB, 8 sections). The core move: the accessibility analogy — agents are the new assistive technology users. A screen reader doesn’t care about your CSS; an agent doesn’t care about your dev portal’s visual design. Both need structure, explicit descriptions, predictable behavior, and standards (WCAG :: MCP/A2A).

The four-step workflow (his TL;DR):

1. Discoverability — agents find you: machine-readable capability descriptions (well-known endpoints, OpenAPI, MCP), not marketing pages
2. Machine-readable interfaces — schema-validated responses; “schemas are your interface contract”; content negotiation; input constraints published, not implied
3. Predictable behavior — behave as documented; idempotency (idempotency keys so agent retries can’t double-charge); consistent pagination, ordering, filtering
4. Agent-aware error handling — structured errors that say whether to retry, when, and what to change; rate limits and cost signals in machine-readable form

Where agents diverge from human accessibility (the checklist that generalizes): agents don’t need sensory accommodations but do need rate/cost awareness, retry semantics, composability (agents chain dozens of calls — “can operations be meaningfully combined?” matters more than any single endpoint’s UX), and explicit permission boundaries — “without them, agents will attempt anything the API technically allows.” The shared-investment point: semantic HTML, good schemas, and good error messages pay twice — human and agent accessibility.

The vault already runs on this

• Tuist’s thesis (clippings/tuist-dev-blog-2026-10-02-the-languages-agents-speak.md): “give agents every layer; choose the languages wisely” — human-convenient abstractions (PaaS, PR-centric flow) become agent hindrances; org interfaces = agent API surface. Same argument from the infrastructure side.
• Agent Client Protocol / omnigent (OSS) — the standardized boundaries (client↔agent, operator↔harnesses) this note’s products plug into.
• basal’s agent-first README — “written for agents (codex, claude code) on purpose” (seeds/Decision models.md): documentation as the agent interface.
• Agent Reach (OSS/Agent-Reach (OSS).md) — the read side of agent accessibility for the whole web: one CLI, platform backends health-checked.
• AI engineering stretch goals / Do-nothing scripting — arg-driven cores (“the core never knows whether a human or a cron job filled in its arguments”) are idempotent, composable agent surfaces.
• The KISS/full split: the KISS variant is often the more agent-accessible one — fewer knobs, explicit contract.

Case study: Cloudflare’s cf CLI (the reference implementation)

The launch post (clippings/blog-cloudflare-com-cloudflare-cf-cli-launch.md) + @DanielMiessler: “a perfect example of not only having awesome products, but also having them be fully agent-accessible.” The numbers that forced it: agent share of Wrangler use went from single digits to 25% (Mar 2026) to 48% in a year; agents run ~2× the distinct commands and are 4× as likely to use six or more. But Wrangler exposed only ~280 operations of thousands — “agents love CLIs” met the hand-built-per-team command sprawl (inconsistent verbs: d1 info vs hyperdrive get vs workflows describe).

The fix is the thesis above, productized: Forge generates the CLI directly from the OpenAPI schemas that already power docs/SDKs → cf covers 3,000+ operations, the entire Cloudflare API — discoverability and machine-readable interface solved by making the schema be the CLI. Predictable behavior via one consistent grammar; agent-aware output via JSON as the default interface (“pretty printed for humans and condensed for agents for maximum context savings” — killing the unicode-table-for-agents token tax); cloudflare.config.ts = typed config for LSPs (agents and humans get the same completions); bespoke command search and steering for findability. One tool: “set up a worker, deploy it, monitor and observe it, protect it with Access, buy a domain, front it with WAF.”

The product question in one line: when your API’s biggest user is a program with a budget and a retry loop, “developer experience” means machine-readable truth — schema, idempotency, structured errors, permission boundaries — not a prettier portal.

Related: Agent Client Protocol · Agent skills · AI engineering · Do-nothing scripting (arg-driven cores) · Reverse proxies (the HTTP-side contract layer)

WebMCP: the accessibility analogy becomes a browser standard

The four-step workflow above, shipped as web-platform machinery (Chrome docs captured; via @DailyDoseOfDS_ — the newsletter’s framing: “the web spent thirty years describing itself to people through layout, and it has no equivalent for programs. WebMCP is one attempt at that missing description, written by the site that already knows the answer”). Chrome + Edge teams, origin trial now:

• The page declares its own actions — each tool gets a name, a description written for a model to read, and JSON-schema typed inputs; execution happens visibly in the user’s live browser session (trust + brand/design stay intact — actuation, not background scraping).
• HTML-form annotation as progressive enhancement: two attributes on a <form> and the browser derives the schema itself — the cheapest possible starting point for any site owner.
• The newsletter’s six-way comparison (pixels → DOM automation → API keys → crawlers’ llms.txt → WebMCP → site’s own assistant) positions WebMCP as the only option keeping all three of: your own agent, nothing to configure, named actions instead of guesswork.
• Status honesty: one browser family shipped, standard not final, only the browser’s own agent calls the tools today.

Why it belongs on this note: it is Bailey’s fundamentals (discoverability → machine-readable interface → predictable behavior) as markup — semantic HTML for agents, the WCAG analogy made literal by the browser vendor. The agent-accessibility thesis now has three tiers: product (this note), CLI/API (cf’s schema-generated surface, CLIs for agents), and web page (WebMCP). The one-liner survives translation: the site that tells an agent what it can do beats the site that makes the agent guess from pixels.

Observability gets the treatment: Maple

maple (OSS) (1.8k★, TS; OpenTelemetry-native traces/logs/metrics on ClickHouse) — the first capture in this note’s family where the product’s core differentiator is agent access: “Built for agents — a hosted MCP server lets Claude Code, Cursor and other clients query your telemetry, and investigations run an agent over it for you” (“ask why a service is erroring; the agent reads traces, logs and code to answer”). Runs the full spectrum of this note’s patterns: hosted MCP surface, local single-binary mode (OTLP :4318 + embedded ClickHouse — maple start), service maps with rate/error/latency per edge, error triage lifecycle, session replay. For Homelabs/monitoring kin: the self-hosted answer to “what does agent-accessible observability look like” — OTLP in (no proprietary agent), MCP out.

DX → AX: supermemory re-architected agent-first (2026-10-06)

DhravyaShah (2-tweet + X article, all in the clipping): supermemory’s v5 API rewrite, stated plainly — “DX to AX: humans are completely out of the loop. Agents are writing the code now. Humans architect it, state properties they want, and go off into the sunset.” What broke by v4 (41 operations across /v3+/v4, deprecated fields, 23-field document responses with tombstonedAt) and the v5 moves: one filter shape everywhere (booleans-that-interact → a single enum); hybrid search as the default (“that’s what an agent asking a question usually wants”); every returned field earns its context-window place (GET /document 23→7 fields); “boring is good… easier and composable so we can rely on this for years.” The validation: internal/external SDK migration tests — agents adopted it “every single time, no questions asked… the details embedded in the structure of the API directly.” And the migration artifact is itself the pattern: a single paste-able prompt (“Fetch supermemory.ai/docs/migration/api-v5.md and follow it. First write a checklist of every legacy call site…”) — the migration guide as agent food. This is this note’s thesis executed at product scale: type-safe shapes + good defaults + response minimalism = the API reads as instructions.

good-css.com: the reference site scored for agents (2026-10-08)

joelhooks (497❤/58k views) quoting vojta_holik: the usage pattern IS the product demo — “prompt: read https://good-css.com and give me the most valuable improvements we can make right now.” The site “scores 100/100 on is-agentic, so you can just point your agent at it. No install, no setup. Read good-css.com before you write CSS.” The site itself (117 KB captured): 47 entries, each a live specimen (iframe-rendered, plain CSS, zero packages to adopt), 8 categories with one reference file each — structured as agent-legible reference documentation with runnable examples. For this note: the is-agentic score is the agent-accessibility equivalent of a Lighthouse badge — a quantified discoverability/structure signal — and good-css.com is the pattern done fully: reference docs that are simultaneously the human site, the agent context, and the runnable example.

Google’s Developer Knowledge API: “stop going to the docs site” (2026-10-08)

rseroter — Richard Seroter, lead of Google Cloud’s docs team: “Stop going to the GoogleCloudTech documentation site. I’m saying that as the person who leads our docs team.” The Developer Knowledge API (GA; blog + tweet captured) is docs as an agent-accessible product: official programmatic source of truth for Google Cloud/Firebase/Android — structured, Markdown-formatted, frequently indexed (“minimal lag between upstream updates and agent access”), with semantic + keyword search, intelligent chunking, and grounded Q&A. Surfaces: REST, MCP server, GA in gcloud CLI (gcloud developer-knowledge answer-query / documents search-chunks / documents describe; pre-installed in Cloud Shell), official agent skill, API Explorer, client libraries. The pitch explicitly retires both failure modes: “brittle web-scraping” and “stale LLM training cutoffs.” For this note: the strongest incumbent endorsement yet of the docs-as-API thesis — the docs team lead telling users not to visit the site is the CLIs for agents/docs convergence said out loud by the owner of the site. Kin: good-css.com (the 100/100 is-agentic reference site), Tuist’s agent-languages thesis, basal’s agent-first README — and the counterweight stays true: the site still exists because humans browse; the API exists because agents don’t.