Comprehension

Can agents understand what your API does and how to use it correctly?

An agent that has found your API still needs to understand it deeply enough to use it correctly. Comprehension covers how agents learn what your API does, what its boundaries are, and how to accomplish specific tasks. This goes beyond having documentation. It requires that your API's behavior is specified precisely enough for a machine to reason about.

Key principles

  • Provide clear, complete OpenAPI specifications with precise schemas and types
  • Write tool definitions that map tasks to capabilities unambiguously
  • Prefer shared standards over private abstractions and custom DSLs
  • Provide task-oriented guidance, not just reference documentation
  • Design information architecture that exposes capabilities clearly and progressively

Tool definitions

When an agent has multiple tools available, it must decide which one to use for a given task. Tool definitions are the primary mechanism for this.

What a good tool definition includes

  • A clear, descriptive name
  • A description of what the tool does and does not do
  • An unambiguous mapping from task intent to tool invocation
  • Capability descriptions that focus on problems solved, not just parameters accepted

An agent choosing between ten tools is reasoning about intent, not about schemas.

Make your tools easy to select correctly. Focus descriptions on what problems they solve.

Machine-readable discovery surfaces like llms.txt, sitemap.xml, and robots.txt help agents find and navigate your capabilities without human assistance.

Specifications

OpenAPI specifications are the lingua franca of API comprehension for agents. A well-written spec provides the type information, endpoint structure, and behavioral contracts that agents need to construct valid requests and interpret responses correctly.

Go beyond the minimum

  • Include detailed descriptions on every endpoint and parameter
  • Document response shapes for both success and error cases
  • Use precise types and schemas rather than permissive ones
  • Generate SDK and API references from the spec to ensure consistency
Why precision matters

An agent working with a string type has much less to work with than one working with a string constrained to a known enum or pattern. The more precise your schemas, the fewer invalid requests agents will construct.

Conventions

Agents perform better when APIs follow conventions they have encountered before. When your API follows patterns that appear across many APIs, agents can transfer knowledge rather than learning from scratch.

  • Prefer shared standards over private ontologies
  • Use widely understood formats - JSON over custom serialization, ISO 8601 for dates, standard HTTP status codes
  • Maintain internal consistency - if pagination works one way in one endpoint, it should work the same way everywhere

Consistency reduces the reasoning burden on agents and reduces the likelihood of errors in unfamiliar corners of your API.

Playbooks

Reference documentation tells an agent what each endpoint does in isolation. Playbooks tell it how to accomplish real tasks that span multiple endpoints.

  • Code samples - concrete examples of common operations
  • Recipes - multi-step workflows like Arazzo workflow specifications
  • Tutorials - narrative walkthroughs of end-to-end tasks
  • Best practices - guidance on sequencing and common pitfalls

The more task-oriented guidance you provide, the less an agent must rely on trial and error to figure out the right sequence of operations.