225 Hacker News Votes Say Your Website Needs an Agent-Readable Copy

Two Hacker News threads, one message for your website

In the 48 hours before this was written, two projects hit the Hacker News front page with the same premise. "Serve Markdown to AI Agents with Accept Headers" (acceptmarkdown.com) drew 170 points and 102 comments. "WebMCP: Teaching Your Website to Talk to AI Agents" drew 55 points and 57 comments. In the same window, Perplexity's "Portable Computer for local-first AI" drew 20 points. As of August 2026, the direction is not subtle: developers are building the pipes that let AI agents read and act on websites, and almost no small-business site is ready to be read.

For 25 years your website has had one audience — a person with a browser. It now has a second: an agent fetching your page because someone asked an assistant a question. That agent ignores your layout, your hero video, and your cookie banner. It pulls raw HTML, tries to reduce it to text, and frequently gets it wrong.

Why this matters

Say a customer asks an assistant, "who does emergency HVAC repair near me in Orlando." The assistant dispatches an agent to read candidate sites. If your price range sits inside a JavaScript quote widget, your hours live in an image, and your service area is buried in the third paragraph, the agent extracts guesswork. The competitor whose site returns clean, labeled text gets named in the answer. You do not.

Content negotiation is not a new or exotic idea. The Accept header has been part of HTTP since the 1990s; browsers use it every time they ask for an image or a language. Serving text/markdown to a client that asks for it is the same mechanism pointed at a new kind of client. That is part of why the acceptmarkdown thread drew 102 comments in a day — the plumbing already exists, and people are arguing about conventions, not feasibility.

This is a visibility problem with a mechanical fix. You add a second, plain representation of what you already publish, and — only if you want agents to take actions like checking availability — a short list of defined operations. We covered the feed side of this in an earlier playbook on Markdown feeds; this one is the full sequence.

The playbook

Work top to bottom. Steps 1 through 3 are the ones every business should do. Steps 4 through 6 depend on whether you want agents to act on your site and how much upkeep you are willing to carry.

1. List the 10 pages an agent will actually fetch. Homepage, each core service page, pricing, service area, hours and contact, and your top three FAQ pages. Agents do not crawl your whole site for a "near me" query; they read the handful that answer it. Fix those first.
2. Serve a Markdown copy through content negotiation. The acceptmarkdown pattern: when a request carries Accept: text/markdown, return a clean Markdown version of the page with a 200 response; when it does not, serve your normal HTML. Same URL, two formats. Markdown strips the navigation, scripts, and styling that cause agents to misread you, and it costs a fraction of the tokens — so more of your actual content fits in the agent's working context.
3. Move the facts into structured data. Add JSON-LD using schema.org types: LocalBusiness for name, address, phone, hours, and service area; Service and Offer for what you do and what it costs; FAQPage for common questions. This is the layer both search crawlers and agents already know how to parse. If a fact matters in a sales call, it belongs here in a labeled field, not only in prose.
4. Expose actions with WebMCP — only if agents should transact. WebMCP lets your site declare a small set of callable operations: check_availability, request_quote, book_appointment. If your business runs on scheduling, this is how an agent completes a booking instead of just reading about one. Start with a single read-only operation before you let anything write.
5. Generate the plain copy from one source. The Markdown and the JSON-LD must be built from the same data that renders the page. If a person edits the price on the HTML page and the Markdown still shows last quarter's number, an agent will quote the stale one with full confidence. Automate the second representation; never hand-maintain it.
6. Test with a real agent every month. Once a month, ask ChatGPT, Claude, and Perplexity to describe your business and recommend someone in your category. Write down what they get wrong. That output is your punch list for the next round.

A pre-launch checklist

• Every core service page returns valid Markdown on Accept: text/markdown, confirmed with curl.
• Name, address, phone, and hours match exactly across the HTML, the Markdown, the JSON-LD, and your Google Business Profile.
• Prices appear as labeled fields, not only inside images or widgets.
• Service area is stated as a list of named cities or ZIP codes, not "the greater metro area."
• JSON-LD validates with zero errors in a schema testing tool.
• Any WebMCP operation that writes data requires a confirmation step.
• The second representation regenerates automatically on every content change.

Common pitfalls

Treating it as an SEO task and stopping at meta tags. Meta descriptions were written for a search results page. Agents need the body content in a form they can ingest whole, plus structured fields they can trust. A 155-character summary does not cover it.

Publishing a Markdown feed that drifts. A feed that was accurate at launch and wrong six weeks later is worse than none — it hands agents a confident, incorrect source. If you cannot automate the sync, do not ship the feed.

Opening write actions too early. An agent that can book appointments can also double-book, cancel, or take a deposit on a job you cannot staff. Ship read-only operations first, watch the logs for a month, then add one write action behind a confirmation gate.

Assuming the big assistants will "figure it out." The 170 points on acceptmarkdown.com are developers agreeing the current situation is bad enough to build around. Waiting for a standard to settle means missing the window where a clean site stands out because most do not have one.

Doing it once. Model versions change how agents read pages. The monthly test in step 6 is the running cost of staying legible.

Where to start

Before you touch a template, find out what the assistants say about you now. AlphaForge runs a free 24-hour report that shows how ChatGPT, Claude, and Perplexity currently describe your business, which competitors they name in your category, and where agents lose the thread on your site. It is the punch list for everything above. free AI Visibility Report