Brave is Needs Work to agents.
Discry independently scored how well an AI agent can discover and understand the Brave 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 · 38/100Comprehension
55% of score · 91/100What we found
- An agent trying to consume Brave's docs programmatically hits a wall at discovery: there is no llms.txt, no llms-full.txt, and no .well-known/mcp.json on either brave.com or the api-dashboard docs host — so an agent cannot self-orient without crawling HTML pages.
- Once inside the docs, comprehension is near-best-in-class (91/100): the quickstart ships copy-pasteable curl, Python, and JavaScript examples with realistic queries, and the rate-limiting guide gives agents actual retry-with-backoff code for 429s — the single most valuable error case.
- Brave publishes an official AGENTS.md in its brave/brave-search-skills repo ('Official skills for using Brave Search API with AI coding agents') plus an official MCP server listed across Glama, Smithery, and PulseMCP — strong signals that agent consumption is a first-class use case.
- No publicly downloadable OpenAPI/Swagger spec was found. The API is fully documented via a hosted interactive reference, but an agent that wants a machine-readable contract to generate a client has nothing to fetch — the heaviest-weighted discovery check fails.
- Naming and capability boundaries are consistent and explicit: uniform snake_case parameters (extra_snippets, search_lang, more_results_available), documented hard limits (max 20 results, offset max 9, POI ids expire in ~8 hours), giving an agent predictable, self-correcting behavior.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish a downloadable OpenAPI 3.x spec at a stable public URL (e.g. api-dashboard.search.brave.com/openapi.json). This is the highest-impact fix — it's the single largest discovery weight and would let agents auto-generate clients instead of scraping the reference.
- 02Add an llms.txt at both brave.com and api-dashboard.search.brave.com that links the quickstart, per-service endpoints (web, local, news, images, video, summarizer, LLM Context), rate-limiting, and auth pages — a low-effort, high-signal win that currently scores three zeros (llmsTxt, llmsTxtQuality, llmsFullTxt).
- 03Add an llms-full.txt containing the concatenated core docs as clean markdown so an agent can ingest the full API surface in one fetch and improve token efficiency (currently core capabilities are spread across multiple pages).
- 04Publish a .well-known/mcp.json advertising the official Brave Search MCP server and its tool declarations, closing the loop between the existing MCP registry listings and machine discovery.
- 05Add a consolidated errors reference covering non-429 failures (400/401/403/422) with the JSON error body shape and explicit recovery steps, to lift error-recovery guidance from partial to a full pass.
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 unusually well documented for a scan: API-key auth via the X-Subscription-Token header, a full rate-limit spec (1s sliding window, 429 responses, and X-RateLimit-Limit/Policy/Remaining/Reset headers with worked examples), and clear pagination (count max 20, offset max 9, plus a more_results_available flag). Idempotency is not discussed, which is expected for read-only GET search endpoints.