Hygraph is Good to agents.
Discry independently scored how well an AI agent can discover and understand the Hygraph API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.
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 · 69/100Comprehension
55% of score · 96/100What we found
- An agent discovering Hygraph would land softly: a well-structured llms.txt indexes the docs and links per-section full-markdown files, backed by a 2.9MB llms-full.txt — so the entire documentation set is consumable as clean markdown without scraping JS-rendered pages.
- Hygraph documents the exact behaviors agents need to self-correct: an errors page with HTTP codes and recovery steps, explicit naming conventions (PascalCase models, camelCase fields, UPPER_SNAKE_CASE enum values), reserved field names, pagination/concurrency limits, and 429 backoff guidance — an agent can recover from most failures from docs alone.
- Hygraph ships an official, first-party MCP server (Early Access, documented at /docs/hygraph-ai/mcp-server) that is permission-aware and blocks destructive actions — a strong native agent-integration signal beyond passive documentation.
- The biggest discovery gap is the absence of an OpenAPI/Swagger spec — Hygraph is GraphQL-native, so its machine-readable contract is GraphQL introspection rather than OpenAPI. Agents expecting a conventional REST spec will not find one, though introspection provides the equivalent.
- Two cheap discovery wins are missing: no AGENTS.md in any primary GitHub repo (the management-sdk README carries agent-relevant naming/operation rules that belong in AGENTS.md), and no /.well-known/mcp.json despite an official MCP server existing.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Add an AGENTS.md to the primary repos (management-sdk, hygraph-examples): the management-sdk README already contains agent-grade content — naming conventions, supported operations, data-loss warnings — that an AGENTS.md would surface to coding agents directly (+3 weight, highest-value discovery fix).
- 02Publish a /.well-known/mcp.json pointing at the existing Hygraph MCP server with tool declarations and auth info, so agents can auto-discover the MCP integration rather than only finding it via the docs site.
- 03Expose a machine-readable API contract at a predictable path — e.g. publish the introspected GraphQL SDL (or a generated OpenAPI translation) at a stable URL and link it from llms.txt — so agents that probe for /openapi.json find a spec instead of a 404.
- 04Trim or split llms.txt so core capabilities are graspable in under ~5K tokens: the current index plus product/marketing links pushes it to ~31KB; a tighter API-only entry section would improve token efficiency for agents scoping the API quickly.
- 05Claim the Hygraph MCP server listing across Glama, Smithery and PulseMCP (not just Pipedream) so agents searching the major registries reliably surface the official server.
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.
Execution documentation is excellent. A dedicated errors page maps conventional HTTP codes (400/401/402/403/404/413) to causes and fixes, GraphQL errors return a structured messages array plus a requestId, and a thorough API-limits section documents RPS, concurrent-operations, request-size and pagination limits (default 10 / max 100) with 429 backoff-and-retry guidance. Idempotency keys are not documented, though upsert mutations provide create-or-update semantics.