◎ Discry Score
commercetools.com
commerce · API
C
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 95 (A)
Discry your API →
COMMERCE · RANK #8 OF 21

commercetools is Needs Work to agents.

Discry independently scored how well an AI agent can discover and understand the commercetools 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 · 48/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.Fail
llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Fail
llms-full.txtA full-text bundle agents can load in one request.Fail
AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Pass
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Fail
MCP registryThe API is listed in a public MCP registry.Fail
robots.txt AI directivesrobots.txt allows (or explicitly guides) AI crawlers.Fail
SitemapA sitemap so agents can enumerate the docs surface.Pass

Comprehension

55% of score · 96/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Pass
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.Pass
Answer-first formatThe answer leads; preamble does not bury it.Pass
Capability boundariesClear limits — what the API can and cannot do.Pass
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 that already knows commercetools exists comprehends it exceptionally well: task-oriented endpoint descriptions, realistic copy-pasteable cURL/JSON examples (real UUIDs, currency codes, cent amounts, SKUs), consistent camelCase, and a dedicated Limits page push comprehension to 96/100 (A).
  • An agent discovering commercetools cold hits the standard signals it checks first and finds nothing: llms.txt, llms-full.txt, and even robots.txt all 404 at docs.commercetools.com, so there is no machine-readable entry point or crawl policy.
  • commercetools is visibly building for agents — AGENTS.md files in its GitHub org, official Commerce MCP and Knowledge MCP servers, an mcp-essentials package, and a 'Prepare for agentic commerce' learning path — yet none of its MCP servers appear in the major registries (Glama, Smithery, and PulseMCP all returned zero results), so agents browsing registries will not discover them.
  • Machine-readable API contracts are first-class: OpenAPI (OAS), RAML, the GraphQL schema, and UML diagrams are all published openly on GitHub and kept in sync, so an agent can generate a typed client without scraping HTML.
  • Multi-step workflows are well covered through self-paced learning paths (checkout, carts & shopping lists, integration, developer essentials) plus tutorials and study guides — an agent can learn to chain operations rather than reverse-engineer them from isolated endpoint pages.

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 at the docs root linking the HTTP API reference, authorization, errors, limits, and the learning paths — the single highest-impact discovery fix (the missing file fails both the llmsTxt and llmsTxtQuality checks).
  2. 02Add a robots.txt that explicitly allows AI crawlers (GPTBot, ClaudeBot, Google-Extended, CCBot, Amazonbot); its current absence scores as a fail and leaves crawl policy ambiguous for agents.
  3. 03List the official Commerce MCP, Knowledge MCP, and mcp-essentials server in Glama, Smithery, and PulseMCP so agents browsing MCP registries can find commercetools — the servers already exist, they are just not registered.
  4. 04Generate an llms-full.txt: commercetools already exposes 'View as Markdown' and 'Copy for LLM' on every page, so concatenating the core reference into a single markdown bundle is low effort and high value for agent ingestion.
  5. 05Round out the otherwise excellent examples by offering multi-language request snippets (beyond cURL) on endpoint reference pages, mirroring the SDK languages commercetools already maintains.

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.

OAuth 2.0 client credentialsOAuth 2.0 password flowOAuth 2.0 refresh tokenExternal OAuth server✓ Error format documented✓ Rate limits documented✓ Pagination documented✕ Idempotency documented

OAuth 2.0 authorization is thoroughly documented (client credentials, password, refresh token, and external OAuth flows with scopes). Errors return machine-parseable JSON (statusCode, message, and an errors[] array of code+message objects). Resource and query limits are extensively documented and a project's live limits are queryable via the GraphQL `limits` field; a blanket public requests-per-second rate limit is not published (it is project/SLA-specific), though an explicit 429 Too Many Requests with a Retry-After header is documented for the Audit Log API. Pagination is documented for both offset/limit and cursor-style (sort-by-id) iteration. commercetools uses optimistic concurrency control (resource versioning + ConcurrentModification error) rather than idempotency keys.

See your own Discry Score.

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

Discry your API — free