Agent-Ready Documentation

Documentation used to be for humans. In the agent era, your documentation is also runtime context for agents calling your APIs — schemas, error semantics, idempotency contracts, and the docs themselves become load-bearing parts of the product surface.

The shift

Two things change about documentation when agents become first-class consumers.

First, timing. Human developers read documentation once, at integration time, and rarely return. Agents may consult documentation on every call — querying for schemas, expected error formats, idempotency contracts, and example payloads. Documentation that lived in a static portal moves into a runtime-queryable surface.

Second, audience. Human developers tolerate prose-heavy docs with implicit assumptions ("you probably want to use the v2 endpoint"). Agents do not. They need schemas, examples, error catalogs, and side-effect declarations in machine-readable form. Marketing copy in the docs becomes noise; precision becomes load-bearing.

For a B2B SaaS aiming at AI-native product strategy, documentation has to be redesigned for both audiences simultaneously — and the agent-readable layer is now part of the product surface, not a separate developer-experience initiative.

What load-bearing means

Five properties of documentation become load-bearing when agents consume it.

1. Schema precision

Every endpoint, tool, and resource must have a machine-readable schema for inputs and outputs. JSON Schema (via OpenAPI for REST APIs, via MCP's inputSchema/outputSchema for MCP tools) is the de facto standard. Schemas are not optional documentation; they are the contract the agent compiles against.

For MCP tools specifically: the outputSchema plus structuredContent field gives agents a parseable response alongside the LLM-readable content array. The combination matters — LLMs use content, deterministic post-processors use structuredContent, and the same call serves both.

2. Error semantics

The MCP specification draws a critical distinction between protocol errors (JSON-RPC error object, codes like -32602 for unknown tool) and tool execution errors (successful response with isError: true and the failure described in content). The distinction tells the agent what to do next: protocol errors are usually retryable (transient infrastructure), tool execution errors are usually surface-to-user (business-rule failures).

Document this distinction explicitly per tool. An agent reading your docs needs to know: "if I get error code 4001, is that 'try again in 30 seconds' or 'tell the human this won't work'?"

3. Idempotency contracts

For any tool that mutates state, declare its idempotency semantics. Stripe inherits Idempotency-Key from its REST API — agents passing the same key get the same result without duplicate side effects. This is foundational for agent loops, which retry liberally.

Three categories per tool:

Idempotent by design — repeated calls produce the same result. Safe to retry.
Idempotent with key — repeated calls with the same Idempotency-Key are deduplicated.
Non-idempotent — repeated calls cause repeated effects. Document this loudly.

Tool annotations in MCP can carry hints (idempotent: true), but the spec is explicit: clients MUST treat annotations as untrusted unless from trusted servers. Your docs are the trusted source, not annotations.

4. Side-effect declarations

What state does the tool change? What other systems does it touch? An agent deciding whether to call delete_customer needs to know it also cascades to subscriptions, payment methods, and webhooks fired downstream. Side effects belong in the schema-adjacent documentation, not in a separate "concepts" page.

5. Realistic example payloads

Synthetic examples ("name": "Test User") are not enough. Agents pattern-match on examples to infer constraints — they need real-shaped examples that show the actual semantics of edge cases. If your amount field accepts negative numbers for refunds, the example must show that. If your date field requires ISO 8601 with timezone, the example must use it.

llms.txt — the discovery signal

ActiveCampaign ships an llms.txt at their developer-docs root. The convention (proposed by llmstxt.org) is to expose a machine-readable index of your documentation specifically for LLM and agent consumers — flat, structured, no marketing copy.

This is a small signal that the team treats documentation as machine-consumable. It's also cheap to ship: an llms.txt is a single Markdown file with a list of canonical URLs and one-line descriptions. The absence of one signals that documentation is still human-only in the team's mental model.

Documentation as a tool — Stripe's pattern

The strongest pattern is to expose documentation as a tool inside your MCP server. Stripe ships search_stripe_documentation as a first-class MCP tool — agents query it at runtime when they encounter a capability they don't understand. The agent doesn't need to be trained on Stripe's API; it queries the docs as part of its execution loop.

This collapses two things that used to be separate: integration time (read docs, write code) and runtime (call API). For agent consumers, both happen inside the same loop.

Implementation considerations:

The search tool should return canonical URLs, not just text snippets. Agents may want to follow up with fetch of a specific page.
Index by intent ("how do I refund a payment") and by capability ("refund_payment tool documentation").
Return short, structured results — agents are reading hundreds of these per task.
Include error catalog and idempotency notes inline with capability docs, not in separate pages.

Annotations are untrusted

The MCP specification supports tool annotations (readOnlyHint, destructiveHint, idempotentHint). These look like documentation but are explicitly defined as untrusted from untrusted servers. A server can claim a tool is read-only when it isn't.

The implication for your product:

As a server: ship accurate annotations, because well-behaved clients use them for UI affordances (showing extra warnings for destructive tools, for example).
As a designer of agent integrations: rely on your contracts and the protocol-level confirmation flow, not on the annotation. The annotation is hint, not enforcement.

What agent-ready docs look like in practice

A capability page for a single tool — the unit of documentation an agent actually consumes — should contain, in this order:

One-line description that accurately tells the user what the tool does. This is the consent affordance.
Input schema in JSON Schema, with every field annotated for required/optional, format constraints, and example values.
Output schema with the same precision.
Side effects — what changes, what events fire, what cascades happen.
Idempotency contract — by design, with key, or not idempotent.
Error catalog — every error code the tool can return, with semantic meaning (retry / surface / abort).
Realistic example — request + response pair using values that show actual constraints.
Related tools — if the agent wanted to do X, what tool should it use?

Most existing API documentation has 1, 2, 3, and 7. The agent-era difference is that 4, 5, 6, and 8 stop being optional.

A documentation diagnostic

For each capability your product exposes:

Is there a machine-readable schema for inputs and outputs?
Is the error catalog enumerated and documented per code, with retry semantics?
Is the idempotency contract explicit (by design / with key / not idempotent)?
Are side effects declared in or adjacent to the schema?
Are examples realistic enough for an agent to pattern-match correctly?
Is your documentation queryable at runtime (search tool, llms.txt index, structured retrieval API)?

If more than one is "no," the documentation surface is still human-only, and your agent capabilities are leaning on assumptions you haven't documented.

← Back to AI-Native Product Strategy · Agent Governance · Agent Operational Discipline