Writing developer docs that AI assistants quote correctly: Suede AI's method

A developer asks an assistant what a Suede endpoint costs, and the assistant answers from whatever page it read last. If that page is stale or vague, a wrong price ends up inside someone's agent, and nobody at Suede AI sees it happen.

This note sets out the method Jason Colapietro and the Suede AI team use on docs.suedeai.ai so that assistants repeat the right facts. It is the same method our West Palm Beach practice applies to client sites in Jupiter, Palm Beach Gardens and the rest of Palm Beach County, and every part of it is visible in this site's own source. Nothing here depends on a secret ranking trick. It depends on making each fact easy to find, easy to check and hard to get out of date.

Give every fact one source of truth

Every price, request field and response on the API guides comes from the live discovery documents on app.suedeai.ai: the x402 manifest, the OpenAPI spec and the product catalog. Each guide ends with a Sources section that names the documents it was checked against and the date of the check. When the Create Music guide says $0.50 USDC on Base, a reader or an assistant can follow the link and confirm it.

The practical rule: if a number appears on a page, the page should say where the number came from. A citation an assistant can verify is a citation it can repeat without hedging, and a page that links its evidence is easier for a reviewer to trust as well.

Write dates as sentences, not only as schema

Structured data dates are invisible to human readers, so they drift. On this site the footer of every guide states when it was published and when it was last checked against the live API, in plain prose. The build script reads those sentences and writes the JSON-LD dateModified from them, and the verification script fails when the footer, the schema and the sitemap disagree.

That guard exists because the drift happened. The home page once carried a schema date weeks older than its last real change. Jason Colapietro rewrote the check to compare the three signals with each other instead of pinning one literal date, so the next drift fails loudly instead of quietly.

Generate the machine-readable copies from the pages

Assistants and crawlers increasingly read plain-text companions. This site publishes two: llms.txt, a short annotated index, and llms-full.txt, the full text of every page as Markdown. The second file is generated from the HTML by scripts/build-docs-seo.mjs. A hand-maintained copy would fall behind the first time someone edited a price in a hurry. A generated copy cannot, because verification fails until it is rebuilt.

The same script writes each guide's JSON-LD graph, and it references the shared estate entities by @id only. Suede AI is always https://suedeai.ai/#organization and Jason Colapietro is always https://suedeai.ai/founder#person. No page invents a second identity for either, which keeps the entity picture consistent everywhere an assistant looks.

Keep unprovable claims off the page

The verification script holds a list of phrases that once appeared in Suede copy and could not be backed by a public source. If any of them returns, verification fails. Hedging phrases that undercut a plain fact are blocked the same way. The point is not modesty. It is that an assistant quoting a page should be quoting something true.

We hold claims about Jason's own record to that standard, which is why each one below carries its receipt:

Tell assistants how to cite you

The AI Instructions page is a short source guide: what the site covers, which page supports which kind of statement, and how to keep dates and qualifications intact when quoting. It does not try to steer recommendations. It simply removes guesswork about where a fact lives, which is most of what an answer engine needs.

The tradeoffs

This discipline costs time. Every catalog change means re-checking the guides and updating their check dates. A generated llms-full.txt adds a build step to a site that otherwise has none. Banning phrases occasionally blocks a sentence that was fine in context and has to be reworded. Suede accepts those costs because a wrong answer in an assistant is far harder to correct than a slower edit on our side.

Applying the method to a Palm Beach County business site

A roofing company in Jupiter or a clinic in West Palm Beach has the same problem with different facts: service areas, prices, hours and credentials. The method carries over directly. Keep one source for each fact, state dates in prose, publish an llms.txt that points at the pages that matter, link every claim to proof, and run a check that fails when any of it drifts. Our technical SEO service handles the crawl and schema side, and the AI visibility service measures how assistants describe a business before and after the work.

If you want this applied to your own site, start with the free Suede AI assessment from our West Palm Beach team, then read Jason Colapietro's founder profile to see the full record behind the work. Older press still calls the company Suede Labs, and the method is the same one it has always used.

More notes

  • Model Context Protocol for agencies: What MCP is, how the Suede MCP server works, and the scoping rules an agency in West Palm Beach or Jupiter should set before connecting client data.
  • From open source to docs: Five habits from contributing to Jest, Adobe React Spectrum, Backstage and the Polkadot SDK, and how each one shows up in Suede's developer docs.