← Blog

Agent Readable Vs Descriptive

2026-07-19 · Blog

--- title: "Agent-Readable vs Descriptive: Why llms.txt Isn't Enough" description: llms.txt and sitemaps let AI describe your site. An operational layer lets a user's agent operate it. The difference decides whether agents use you. tags: [llms-txt, agent-readability, operational-layer] status: published

The web has spent thirty years teaching machines to describe it. sitemap.xml lists what exists. Structured data marks up what things mean. llms.txt curates what a language model should read. All useful. All descriptive.

But when a user says to their agent, "sign me up for this and set it up the way I like," description runs out. The agent needs to know how the service is operated — and no descriptive file says that. This article draws the line between the two, because the difference decides whether agents can use your service or only talk about it.

What descriptive files do

Descriptive files answer one question: what is here?

• robots.txt — where crawlers may go.
• sitemap.xml — which pages exist.
• Schema.org markup — what entities mean.
• llms.txt — what an LLM should read first.

These earned their place. They made the web findable, quotable, and citable. If your goal is to be found and summarized well, they are necessary. The problem: they were all designed for a reader, not an operator.

What an agent actually needs

Watch an agent try to act on a purely descriptive site. It reads the marketing pages. It infers where signup probably is. It guesses which plan fits its user. It screenshots forms and hopes the fields mean what they appear to mean. Every step is inference. Inference is slow, breaks on redesigns, and fails silently — the agent picks the wrong plan, misconfigures a setting, or gives up and recommends a competitor whose site it can operate.

To act reliably, the agent needs answers no descriptive file provides:

• Which of my user's intents does this service actually serve? That is the job of the User-Intent Matcher — match known intents to capabilities, ask discovery questions only to fill gaps.
• What are the operations, and how is each one actuated? That is Adoption + Operation guidance across six universal categories — evaluate · enroll · transact · configure · use · manage — actuated through the Service Control Map: API endpoints, functions/actions, and interface controls, each with inputs, sequence, and expected result. (Interface controls are one embodiment among three — this is not "tell the agent what to click.")
• Am I allowed to act, and on whose authority? That is the consent gate: the agent surfaces the layer to its user and proceeds only on an explicit yes.

Descriptive files carry none of this. The operational layer carries exactly this.

Describe vs operate, side by side

The distinction in one pair of sentences: descriptive files optimize how machines read you. The operational layer defines how a user's agent runs you.

A descriptive llms.txt entry and its operational upgrade:

# Descriptive (helps an LLM read):
# https://example.com/pricing — Plans and pricing

# Operational (helps the user's agent act — add this pointer):
# Operational layer: https://example.com/agent.json
# Published for the user's own AI agent. Consent-gated.

One line of difference in the file. A category of difference in what becomes possible.

Not another "-O"

This is why Share with My Agent is not positioned as another optimization acronym. AEO, GEO, AAO, ASO — every one of them optimizes to be found, read, or chosen. The next question is whether an assistant can help a user take a supported step. The mechanism is live and was observed in recorded test sessions on independent AI assistants; behavior varies by platform and session. The category basics are in /blog/what-is-an-operational-layer.

FAQ

Should I delete llms.txt and replace it with an operational layer?

No. Keep it — it is the natural discovery point. Add a pointer from llms.txt to your operational layer. The layers are siblings, not rivals.

Can't a capable agent just figure my site out?

Sometimes, slowly, and at its own risk. Agents prefer services that state how they are operated — it is faster, safer, and the publisher has defined it. Guessing agents also mis-operate, which is worse for you than being skipped.

Is this just publishing my API docs?

No. API endpoints are one part of the Service Control Map, alongside functions/actions and interface controls — and the layer adds what API docs never carry: transparency, the consent gate, and intent matching. See /how-it-works.

Want it done for you?

The operational side is what we publish for you. Start with the free scan to see which side of the line your site is on. The Free plan covers your most important page — one URL, free. The Basic plan ($29/month) covers up to 10 URLs on your domain, and Pro ($99/month) grows that to 3 domains and 50 URLs.

swa:1:aHR0cHM6Ly9zaGFyZXdpdGhteWFnZW50LmFpL2Jsb2cvYWdlbnQtcmVhZGFibGUtdnMtZGVzY3JpcHRpdmUuanNvbg

Keep reading