Oso is Agent-Ready to agents.

What we found

• —An agent landing on the docs is handed everything it needs up front: `/docs/llms.txt` is an API-focused index that links every page in clean `.md` form and points to a valid OpenAPI 3.1.0 spec, so an agent can enumerate the entire Check/Facts/Policy API without scraping rendered HTML.
• —Every endpoint reads as a task ('Determines whether an actor can take an action on a resource') and ships copy-pasteable examples in six languages (Node, Python, Go, Java, Ruby, C#) with realistic values like `User:alice` and `Repository:anvils` — an agent can generate a working authorize call on the first attempt.
• —Capability boundaries are unusually explicit: a dedicated Service Limits page enumerates concrete thresholds (e.g. 30,000 fact updates/min, 100 context facts/request, 10 MiB read size) each mapped to the exact HTTP status returned, so an agent learns the guardrails without hitting them.
• —Discovery is docked below Comprehension because two agent-native signals are missing or thin: there is no `/llms-full.txt` and no `/.well-known/mcp.json`, and `AGENTS.md` appears only in secondary org/demo repos (osohq/ash-demo) rather than a primary public repo — an agent's coding-agent handshake gets weaker guidance than its runtime API handshake.
• —Error handling is the one comprehension soft spot: errors are a uniform machine-parseable `ApiError { message }` and status codes are documented, but per-endpoint docs give no explicit 'when you see X, do Y' recovery steps, so an agent must infer corrective action from the message string alone.

What to change

Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.

1. 01Add a `/.well-known/mcp.json` manifest. Oso already ships and documents an official MCP server, so declaring it in the standard well-known location is a near-zero-effort discovery win that would convert an existing capability into a machine-discoverable one.
2. 02Publish an `AGENTS.md` in a primary public repo (e.g. a client SDK like go-oso-cloud or the docs repo), not just demo repos, so coding agents get authoritative build/test/convention context for integrating Oso.
3. 03Add explicit error-recovery guidance to the API reference: for each documented status (429, 413, 400) state the corrective action ('on 429, back off and retry after the sliding 1-minute write window clears'; 'on 413, split the batch below 1,000 entries'). This is the highest-leverage comprehension fix.
4. 04Generate a `/llms-full.txt` (or an llms.txt-linked concatenated corpus). The per-page `.md` files already exist, so bundling them gives token-budget-aware agents a single-fetch full-context option without changing the underlying docs.
5. 05Document idempotency semantics for write endpoints (facts/bulk/batch) — clarify whether retrying a failed insert is safe and whether an idempotency key is honored — so agents can safely auto-retry mutations.