---
title: "Make the API easy for agents to find · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/contracts-and-docs/agent-discovery
updated: 2026-10-20
licence: "All rights reserved"
---

# Make the API easy for agents to find

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Contracts and docs](https://agentwranglers.se/playbook/api-design/contracts-and-docs)
- Rule: Link the contract from a well-known place, so AI agents and tools can find and use the API without a human.
- How: List the API and its OpenAPI file in an [API catalog](https://agentwranglers.se/playbook/website/standard-addresses/api-catalog), and point to it with [link headers](https://agentwranglers.se/playbook/website/ready-for-ai-agents/link-headers). Give each operation a unique `operationId` and a `description` of one or more sentences, since agents use them as tool names.
- Check: Fetch `/.well-known/api-catalog`. It links to the OpenAPI file, which loads and validates. A linter rule finds no operation without an `operationId` and a `description`.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/contracts-and-docs/agent-discovery`.

- Previous: [Generate docs and clients from the contract](https://agentwranglers.se/playbook/api-design/contracts-and-docs/generated-docs)
- [Contracts and docs](https://agentwranglers.se/playbook/api-design/contracts-and-docs)