Pull your entry logs for final week and ask a query most groups by no means assume to ask: how a lot of that visitors was learn by an individual?
Cloudflare began publishing a solution in July 2025. Throughout its total buyer base within the first week of that August, Anthropic’s crawlers made practically 50,000 requests for HTML pages for each one web page request its platform referred again to a web site. OpenAI’s ratio was 887 to 1. Slim it to the pc and electronics vertical — the general public studying this — and Anthropic’s was nonetheless 8,800 to 1. These are content material requests, not API calls, and I do know of no equal public quantity for APIs. However I doubt anybody who has checked out their very own logs recently is shocked.
The reflex is to file this below scraping and transfer on. That’s a mistake. It isn’t a visitors story, it’s a design story, and the issue is just not that the brand new reader is a machine. We’ve been serving machines since SOAP. The issue is that this machine exhibits up with amnesia after which improvises.
An individual learns your product as soon as. They skim the getting-started web page in March, get burned by a price restrict and bear in mind it eternally, and by June they’re carrying a mannequin of your system of their head that you just by no means needed to write down. Every part you ignored of the response, they bought some other place.
An agent has none of that. It rebuilds its mannequin of your system from scratch on each run, out of no matter you occurred to return. All the reason that used to reside outdoors your interface now has to reside inside it, or it doesn’t exist.
Your error messages
Begin with the least glamorous floor you personal: your error messages. For a human person, an error is a lifeless finish that will get resolved some other place: a ticket, a colleague, or giving up. For an agent, that error string is all the enter to the subsequent determination. “One thing went improper. Please attempt once more” is just not an apology to an agent. It’s an instruction, and will probably be adopted.
This has stopped being a matter of style. The Mannequin Context Protocol spec, which is the closest factor we now have to a written contract between software program and brokers, makes the excellence normative. Protocol errors are for issues “that fashions are much less seemingly to have the ability to repair.” Device execution errors, against this, “include actionable suggestions that language fashions can use to self-correct and retry with adjusted parameters,” and shoppers ought to hand these to the mannequin. Its personal instance: “Invalid departure date: should be sooner or later. Present date is 08/08/2025.” Which area, what rule, what would repair it. That isn’t a nicer error message. That’s your retry logic, and also you at the moment are writing it in English.
Second: what your interface refuses beats what your documentation says, and it isn’t shut. In 2021 I used to be producing monetary projections on a language mannequin, again when hallucination wasn’t a danger to mitigate however a certainty to design round. The mannequin by no means produced a quantity in any respect; it emitted a labeled situation, and a deterministic guidelines engine ran each calculation and enforced each constraint. What that engine rejected most frequently was the mannequin implying a development price its business tier didn’t permit. It wished 40% month over month for a providers enterprise. The engine clamped it to the tier ceiling and the person by no means noticed the unique. That constraint held for one cause, and it wasn’t that we’d defined it nicely. It was the one one the mannequin couldn’t route round. Two years later I filed a multi-agent analysis system, patent pending, whose parts served different brokers quite than individuals. Identical lesson, one layer up.
Third, and that is the one which surprises individuals: your documentation is now a runtime dependency with a efficiency price range. Below MCP, a server providing instruments should reply a `instruments/record’ request with the set at present obtainable . That functionality is found at name time, not learn prematurely. The outline you write for every device goes straight right into a context window, and the protocol’s personal steering warns that loading each definition up entrance “wastes tokens, will increase latency, and degrades mannequin efficiency,” to the purpose that with sufficient servers linked, these definitions “devour the vast majority of the context window earlier than the mannequin has even learn the person’s message.” Your API reference and your API are collapsing into one artifact. Jeremy Howard’s llms.txt proposal, from September 2024, is identical admission arriving from the content material aspect: ship a model of the positioning written for the reader that may’t skim.
Write in your agent
Now the strongest objection, and it’s truthful: none of that is new. Semantic errors, machine-readable schemas, discoverable functionality, trustworthy contracts — that’s REST because it was really specified, plus 20 years of API design recommendation most of us quietly skipped.
Responsible, and that’s the argument. The explanation we bought away with skipping it’s that there was at all times an individual on the finish of the chain absorbing the anomaly. The developer who learn between the traces of your 400. The help engineer who knew the endpoint lies about pagination. That human was your error-handling layer, they usually labored free of charge. Take them out and the load doesn’t disappear. It lands on the one factor left: the literal textual content of your interface.
What ought to fear you is how the failure mode adjustments. A confused developer recordsdata a ticket. A confused agent doesn’t. It produces one thing believable, on time, in the proper form, and strikes on. The primary individual to note is a buyer.
For 30 years your interface has been the second-best rationalization of your system. One of the best one lived in individuals , those who onboarded new hires and answered questions in Slack. These readers are being changed by one that may’t ask a follow-up query and gained’t admit it’s misplaced. Write for that reader. It’s already in your logs.
Q&A
What’s the MCP instruments/record request and the way does it have an effect on API documentation?
Below the Mannequin Context Protocol (MCP), a server should reply to a `instruments/record` request with the set of instruments at present obtainable, found at name time quite than learn prematurely. The outline written for every device is injected immediately into the mannequin’s context window. MCP’s personal steering warns that loading each device definition up entrance wastes tokens, will increase latency, and degrades mannequin efficiency — that means API documentation and the API itself are successfully collapsing right into a single runtime artifact.
What’s Jeremy Howard’s llms.txt proposal and what drawback does it clear up?
llms.txt, proposed by Jeremy Howard in September 2024, is a conference for transport a simplified, plain-text model of an internet site or documentation particularly formatted for language mannequin consumption. It addresses the truth that LLMs can not skim, scroll, or resolve ambiguity the best way human readers do, so normal HTML documentation is usually too noisy or token-heavy to be reliably parsed by an agent at runtime.
How does designing APIs for AI brokers differ from normal REST API design finest practices?
The core rules — semantic error responses, machine-readable schemas, discoverable capabilities, and trustworthy contracts — are the identical ones laid out in REST from the start. The sensible distinction is enforcement: beforehand, human builders on the finish of the chain might take up ambiguity and fill in gaps via documentation, tickets, or tribal data. With AI brokers as customers, there isn’t a human error-handling layer, so imprecise contracts and implicit habits produce silent, plausible-looking failures quite than filed bug studies.
