◎ Discry Score
octopus deploy.com
infrastructure · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 98 (A)
Discry your API →
INFRASTRUCTURE · RANK #30 OF 68

Octopus Deploy is Good to agents.

Discry independently scored how well an AI agent can discover and understand the Octopus Deploy API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.

Discry your API — freeView the docs ↗

SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.

Discovery

45% of score · 76/100
OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Pass
llms.txtAn llms.txt index that points agents to the docs that matter.Pass
llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Partial
llms-full.txtA full-text bundle agents can load in one request.Pass
AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Fail
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Fail
MCP registryThe API is listed in a public MCP registry.Pass
robots.txt AI directivesrobots.txt allows (or explicitly guides) AI crawlers.Pass
SitemapA sitemap so agents can enumerate the docs surface.Pass

Comprehension

55% of score · 79/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Partial
Realistic examplesRunnable, real-world request/response examples.Pass
Multi-step workflowsDocs that chain calls into complete jobs an agent can follow.Pass
Error-recovery guidanceDocumented failure modes and how to recover from them.Partial
Answer-first formatThe answer leads; preamble does not bury it.Pass
Capability boundariesClear limits — what the API can and cannot do.Partial
Naming consistencyConsistent, predictable naming across endpoints.Pass
Heading hierarchyClean heading structure agents can navigate.Pass
Markdown docsDocs available as clean markdown, not JS-rendered HTML only.Pass
Token efficiencyDocs are concise enough to fit an agent context window.Partial

What we found

  • An agent can consume Octopus docs natively: every doc page has a clean `.md` variant (Content-Type: text/markdown), a docs-scoped `llms-full.txt` (7.3MB of full docs as markdown) is published, and each page carries a 'Use Octopus docs with AI' affordance — this is genuinely AI-forward documentation.
  • Discovery is strong on the signals that matter: a valid public OpenAPI/Swagger 2.0 spec is reachable at demo.octopus.app/api/swagger.json, an official first-party MCP server (github.com/OctopusDeploy/mcp-server) is published and listed on Glama and PulseMCP, and robots.txt places no restrictions on AI crawlers.
  • The root `llms.txt` exists and is well-structured with descriptions, but at 457KB it is a ~9x-oversized site-wide dump (marketing pages + the entire docs tree) rather than an API-focused index — an agent would burn a large budget parsing it to find the API surface.
  • The website has no per-endpoint reference pages; the real endpoint reference lives in the per-instance Swagger UI. An agent gets excellent multi-language, task-oriented example scripts (PowerShell, C#, Python, Go, Java, TypeScript) but must reconstruct exact endpoint semantics from the raw spec.
  • Self-correction is the weak spot: no `AGENTS.md`, no `.well-known/mcp.json`, no documented rate limits, and no error-recovery guidance — an agent hitting a 4xx would discover what went wrong only by failing and inspecting the instance Swagger.

What to change

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

  1. 01Publish an API-focused `llms.txt` (or an `/docs/llms.txt`) that is right-sized (<50KB) and links only the REST API landing, getting-started, auth, examples, and Swagger — keep the current 457KB site-wide file as a separate resource so agents aren't forced to parse the whole site to find the API.
  2. 02Add an `AGENTS.md` to the primary public repos (mcp-server, docs, OctopusDeploy-Api) with build/run/test context for coding agents — it's a rising standard, currently absent, and a fast discovery win.
  3. 03Add a dedicated REST API errors + rate-limits page documenting the response envelope, common status codes, and actionable recovery steps (e.g. what to do on 401/403 for API-key vs OIDC, how permission scoping fails) so agents can self-correct without live probing.
  4. 04Serve a canonical, versioned OpenAPI spec from the docs domain (e.g. octopus.com/docs/openapi.json) instead of relying on the demo instance — a stable, discoverable spec is easier for agents and tooling to fetch reliably.
  5. 05Publish a `.well-known/mcp.json` advertising the official MCP server and its tools so MCP-aware agents can discover the integration directly from the domain.

Execution coverage · INFORMATIONAL, UNSCORED

Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.

API key (X-Octopus-ApiKey header)OpenID Connect (OIDC / OAuth2, short-lived access tokens)✕ Error format documented✕ Rate limits documented✓ Pagination documented✕ Idempotency documented

Octopus documents a hypermedia (HATEOAS) REST API with two auth methods (API key header and OIDC) and clear link-based pagination (Page.Next / Page.Current, skip/take, URI templates). Error response format, rate limits, and idempotency are not documented on the docs site — response codes and schemas are only exposed via the per-instance Swagger spec, so an agent gets no self-correction guidance from the public docs.

See your own Discry Score.

Drop your API docs URL. See what an agent sees — in 60 seconds, free.

Discry your API — free