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

AWS is Good to agents.

Discry independently scored how well an AI agent can discover and understand the AWS 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 · 74/100
OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Partial
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.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.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 · 87/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.Partial
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.Fail

What we found

  • An agent looking for AWS finds it effortlessly: docs.aws.amazon.com serves a valid llms.txt (HTTP 200) indexing every service, and every documentation page is available as clean .md — near-ideal machine ingestion.
  • Endpoint docs are strongly task-oriented and answer-first: RunInstances opens with 'Launches the specified number of instances...' and PutObject leads with method/URL, each parameter carrying Type, Required, Default, and Constraints.
  • No single OpenAPI/Swagger spec is served; instead AWS publishes complete Smithy models for all services (github.com/aws/api-models-aws), which an agent must convert rather than consume directly.
  • Token efficiency is the weak point — the root llms.txt alone is 293KB (~73K tokens) and a single service's llms.txt (EC2) is 310KB; there is no concise capability overview an agent can read in one budget.
  • Agent-native signals are strong beyond the basics: official AWS MCP servers are listed on PulseMCP/Smithery, and awslabs/agent-plugins ships a real AGENTS.md (CLAUDE.md symlinks to it) with useful coding-agent context.

What to change

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

  1. 01Publish a concise, right-sized llms.txt (<50KB) that summarizes the top services and links out, keeping the current 293KB index as a separate llms-full.txt — this fixes both the missing llms-full.txt and the token-efficiency failure.
  2. 02Offer an OpenAPI/Swagger export alongside the Smithy models (Smithy already converts to OpenAPI) so agents can consume a standard machine-readable contract without a conversion step.
  3. 03Add per-error recovery guidance to the CommonErrors and service error pages (e.g., 'On ThrottlingException, retry with exponential backoff'; 'On RequestExpired, re-sign within 15 minutes') so agents can self-correct from the reference alone.
  4. 04Serve a /.well-known/mcp.json declaring the official AWS MCP servers and their auth so agents can auto-discover tool access instead of searching third-party registries.
  5. 05Expose a service-level capability summary page (per service) that fits under ~5K tokens, giving agents an efficient overview before they drill into full action references.

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.

AWS Signature Version 4 (SigV4)IAM access keysTemporary credentials (STS)Session-based tokens (S3 directory buckets CreateSession)✓ Error format documented✓ Rate limits documented✓ Pagination documented✓ Idempotency documented

Execution characteristics are documented to an exceptional standard: SigV4 signing, structured error codes with HTTP status, request/resource throttling plus Service Quotas, NextToken/MaxResults pagination, and ClientToken idempotency (with a dedicated idempotency guide). Details are consistent per-service but spread across separate reference and developer-guide pages.

See your own Discry Score.

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

Discry your API — free