Agent-Friendly Documentation: How to Design Docs for Autonomous Agents

TL;DR

Write docs that survive agent automation: deterministic anchors, one canonical heading per concept, explicit tool-contract blocks, structured pre/post-conditions, and unambiguous error states. Humans still benefit; agents stop failing silently.

What is agent-friendly documentation?

Agent-friendly documentation is content authored under a contract: any autonomous agent that follows the docs should reach the same outcome a careful human would. Where traditional docs optimize for prose readability, agent-friendly docs optimize for parseable determinism — the property that the same instruction yields the same agent behavior on every run.

The specification covers four layers:

1. Structural layer — heading hierarchy, anchors, page topology.
2. Affordance layer — what an agent can do on the page (run a snippet, click a button, file a request).
3. Contract layer — input/output shapes, pre- and post-conditions, error semantics for tools.
4. Discoverability layer — how an agent finds the right page in the first place.

Why this matters

• Agent reliability. Tool-using agents (Model Context Protocol clients, OpenAI function-callers, Claude tool-use) fail when instructions are ambiguous or anchors drift.
• Citation readiness. Pages that are machine-actionable also tend to be machine-extractable, which raises citation odds.
• Cost. Each agent retry costs tokens; deterministic docs reduce retries.
• Trust. When an agent confidently completes a task using your docs, users return.

Structural layer

Heading hierarchy

• Exactly one H1 per page.
• H2 introduces top-level sections; H3 introduces subsections; H4 only when strictly needed.
• Never reuse the same heading text within a page; agents disambiguate by anchor.
• Headings encode the canonical concept name, not marketing language.

Deterministic anchors

Anchors are the single most important agent affordance. The contract:

• Generated from heading text via a documented slug rule (lowercase, kebab-case, ASCII).
• Stable across releases. Renaming a heading without updating redirects breaks every agent that hard-coded the anchor.
• Listed in a per-page anchor manifest (/_anchors.json or equivalent) when feasible.
• No collisions; if two sections must share text, append a disambiguator (#install-cli, #install-sdk).

Page topology

• One concept per page. Agents struggle when a page bundles unrelated affordances.
• Predictable section order: overview → requirements → procedure → validation → troubleshooting.
• A Status block near the top declares maturity (stable, beta, deprecated) — agents can refuse risky tasks against unstable docs.

Affordance layer

Code blocks as machine actions

• Tag every executable block with a language identifier the agent can detect.
• Mark blocks the agent should run with a run="true" attribute or sibling annotation.
• Provide expected output blocks with the output language for verification.
• Never embed credentials, paths, or environment-specific values in shipped blocks; use placeholders the agent must resolve.

Step lists

• Use ordered lists (1., 2., 3.) for any procedure an agent must execute in sequence.
• One action per step.
• Steps include a verification clause ("the response should contain 200 OK").

Forms and controls

• For interactive controls, document selector strategies an agent can use: stable data-testid, ARIA role + accessible name, or unique text. Avoid relying on visual position.
• Document the agent-safe path even when the human path uses drag-and-drop or keyboard shortcuts.

Contract layer

Tool contracts

Every API or tool reference must publish a tool-contract block:

name: createInvoice
description: Creates an invoice for a customer.
inputs:
customer_id: { type: string, required: true }
amount_cents: { type: integer, required: true, minimum: 1 }
currency: { type: string, required: true, enum: [USD, EUR, GBP] }
outputs:
invoice_id: { type: string }
status: { type: string, enum: [draft, open, paid] }
side_effects:
- sends_email: false
- emits_webhook: invoice.created
errors:
- code: customer_not_found
retryable: false
- code: rate_limited
retryable: true
backoff_seconds: 60
idempotency:
key_header: Idempotency-Key
ttl_hours: 24

The contract is binding: any change in shape, side effect, or error code is a breaking change and must bump version + ship a redirect for hard-coded clients.

Pre- and post-conditions

• Preconditions: state the world must be in before the action (auth, account state, rate-limit budget).
• Postconditions: what the agent can rely on after success.
• Invariants: properties that hold throughout the interaction.

Error semantics

• Every documented error has a stable code, a human description, and a retryable: true|false flag.
• Recoverable errors document the exact retry shape (delay, jitter, max attempts).
• Non-retryable errors document the next correct action (escalate, pivot, abort).

Discoverability layer

• Each page lists its canonical_concept_id in metadata.
• Each page links to its parent hub and at least two sibling concepts.
• The site publishes llms.txt listing all agent-relevant pages.
• The site publishes a sitemap and a /_meta/agent-index.json enumerating tool contracts and stable anchors.

Anti-patterns that break agents

• Floating anchors. Heading text changes silently; agents pointing at #install 404 a week later.
• Mixed-modal procedures. "Click the gear icon and run this command" — agents that can do one path can rarely do both.
• Implicit auth. Steps that assume the agent is already signed in without saying so.
• Embedded screenshots as load-bearing instructions. Screenshots are opaque to most agents; the action belongs in text.
• Ambiguous outcomes. "You should see something like this" — agents need explicit success markers.
• Versionless examples. Snippets without an SDK version pin become hostile when the SDK changes.
• Marketing prose inside reference. Agents skim aggressively; flowery introductions push the actual contract below the agent's first viewport.
• Stale lastmod. Agents weight freshness; missing dateModified reduces confidence.

QA rubric (score 0-10)

A page scoring 8+ is shippable for agent automation; 5-7 is risky; below 5 should be rewritten before agent integrations rely on it.

How to apply this spec

1. Audit existing docs against the rubric.
2. Mint stable anchors and add the manifest.
3. Author tool-contract blocks for every public API or tool.
4. Refactor procedures into one-action steps with verification clauses.
5. Publish llms.txt and an agent-index manifest.
6. Wire doc CI to fail on missing anchors, missing contracts, or unresolved redirects.
7. Monitor agent telemetry (retries, failed tool calls, hard-coded selector miss rate) and feed it back into doc updates.

Validation checklist

• [ ] One H1, no duplicate headings.
• [ ] All anchors documented in a manifest.
• [ ] All renames ship redirects.
• [ ] Every tool reference includes a complete tool-contract block.
• [ ] Every procedure step has a verification clause.
• [ ] Status block declares maturity.
• [ ] llms.txt and _meta/agent-index.json exist and are current.
• [ ] No screenshot-only instructions remain in load-bearing steps.

FAQ

Q: Do I need to maintain a separate set of docs for agents?

No. Agent-friendly docs serve humans equally well; the discipline mostly removes ambiguity. Maintain one source of truth and apply the spec to all reference and procedural pages.

Q: Are screenshots banned?

They are demoted, not banned. Use them to illustrate context, but never as the sole carrier of an instruction. The textual step must stand alone.

Q: How do I version tool contracts without breaking agents?

Treat the contract as an API surface. Additive changes are minor versions. Anything that removes or renames a field is a major version that ships alongside the prior one for a deprecation window.

Q: What if my docs platform auto-generates anchors?

That is fine if the slug rule is documented and stable. Add a manifest that the build emits, and add a CI check that fails the build when an anchor disappears without a redirect.

Q: Does this spec apply to internal-only docs?

Yes — perhaps even more so. Internal agents tend to have higher action authority than public ones, so deterministic instructions are essential to avoid expensive misfires.