Mapbox is Good to agents.
Discry independently scored how well an AI agent can discover and understand the Mapbox 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 · 67/100Comprehension
55% of score · 96/100What we found
- An agent landing on docs.mapbox.com finds a well-structured llms.txt that fans out to per-product llms.txt and clean .md versions of every API reference — Mapbox even exposes 'Copy as Markdown' / 'View as Markdown' controls, making the docs near-ideal for LLM consumption.
- Comprehension is outstanding (96/A): endpoint pages lead with task-oriented summaries ('The Directions API will show you how to get where you're going'), realistic multi-parameter cURL examples with real coordinates, and SDKs in 7+ languages.
- Capability boundaries are explicit — per-API rate-limit tables, max coordinates/distances, URL-length limits, and 'not supported' constraints (inter-continental routing, water bodies) — so an agent learns limits from docs rather than by failing.
- Mapbox is unusually agent-forward: it ships official MCP servers (MCP, DevKit, Docs) listed on Glama and PulseMCP, a dedicated mapbox-agent-skills repo, and AGENTS.md files in primary repos (mapbox-gl-js, mcp-server).
- The one real gap is discovery (67/C): there is no publicly downloadable OpenAPI/Swagger spec, so an agent cannot auto-generate a typed client — it must parse the .md reference pages instead. llms-full.txt and .well-known/mcp.json are also absent.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish a machine-readable OpenAPI 3.x spec at a stable public URL (e.g. docs.mapbox.com/openapi.json) — this is the single highest-impact fix (weight 5) and would let agents auto-generate typed clients instead of scraping reference pages.
- 02Add an llms-full.txt that concatenates the core API reference markdown into one file, giving agents a single-fetch corpus of the full platform.
- 03Add a dedicated errors/troubleshooting page mapping the top 5–10 error scenarios to explicit recovery steps (e.g. 429 → back off using X-Rate-Limit-Reset; 422 → which parameter was invalid and its valid range).
- 04Publish a .well-known/mcp.json declaring the official Mapbox MCP server(s) so agents can auto-discover tool endpoints and auth from the docs domain.
- 05Surface the existing multi-step tutorials (verify domain → create scoped token → first request → handle limits) directly inside the API reference so end-to-end workflows aren't only reachable via the separate Tutorials/Help section.
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 characteristics are documented thoroughly: token-scope auth, per-API rate-limit tables plus X-Rate-Limit-* response headers, RFC 5988 Link-header pagination, and JSON error bodies with code/message fields. Idempotency keys are not mentioned.