1
Describe the operation
Give each endpoint or tool a stable name, purpose, parameters, response shape, auth scheme, and consequence classification.
API and product use
Give product agents a reliable path from intent to API result.
Document operations, inputs, authentication, errors, limits, and safe stopping points so agents can use your product beyond the UI.
Some agents will never click through the interface. They will discover an API, MCP tool, OpenAPI document, CLI, or machine-readable catalog and use it to complete product work. That surface needs the same honesty as the UI: operation names, schemas, authentication, authorization, limits, idempotency, errors, examples, and consequence levels must agree with the deployed service.
2
Document failure
Use typed errors, status codes, retry guidance, rate limits, validation details, and current state after partial failure.
3
Scope access
Require least privilege, validate targets server-side, and keep write or destructive operations behind fresh approval.
4
Verify the contract
Compare the published OpenAPI, catalog, or MCP surface with at least one harmless live operation in a controlled fixture.
Contract
The declared inputs, outputs, auth, and errors match the deployed operation.
Reliability
Retries, idempotency, rate limits, and uncertain provider states are explicit.
Safety
The server—not a prompt or client field—enforces identity, target, authorization, and consequence.
Evidence loop
Find the first failure. Fix the task. Verify the same task again.
A score is a summary. The useful artifact is the URL, control, state, assertion, and safe stopping point your team can hand to a coding agent. Scan a public URL to create that baseline, then rerun the journey after each fix.
Create your baselineQuestions teams ask first
Do I need an API to be agent-ready?
No. A well-structured browser journey can be agent-ready. An API is valuable when your product has repeatable operations that need a more deterministic contract.
Should every API operation be exposed to agents?
No. Publish only operations with clear ownership, authentication, authorization, rate limits, and safe consequence boundaries.
What is the minimum API evidence?
A valid, current contract; one harmless operation verified against production-like behavior; explicit error and retry semantics; and server-side enforcement of the declared scope.