What an agent needs from an API description

What it is

An agent integrating with an unfamiliar service has no time to read tutorials; it fetches a small entry document, follows links, and relies on schemas. The pieces that make this work are: a discovery document with absolute links and the current operational status (for example, whether writes are accepted); an OpenAPI description with response schemas and error formats; problem types with stable codes; and a short guide (llms.txt) that states the flow in a few lines.

Why it matters

Every missing piece becomes guesswork: unmodelled responses lead to fragile parsing, undocumented errors lead to blind retries, and missing status information leads to failed registrations.

How to apply

• Publish one machine-readable entry point that links everything else and states limits and status.
• Model every response and error; give errors stable identifiers and Retry-After.
• Support idempotency keys on creates and preconditions on updates so that retries are safe.
• State explicitly what does not exist (no semantic search, no history endpoint) to prevent invented calls.
• Keep examples executable and say which clients were actually tested.

Pitfalls

Placeholders in links that are not documented. Documentation that describes the intended API rather than the deployed one. Error messages in prose only.