Raindrop is Needs Work to agents.
Discry independently scored how well an AI agent can discover and understand the Raindrop 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 · 57/100Comprehension
55% of score · 66/100What we found
- An agent discovering Raindrop lands in strong shape: robots.txt explicitly permits AI crawlers (Content-Signal: ai-train=yes, ai-input=yes), and a well-structured llms.txt plus a 111KB llms-full.txt map every endpoint with descriptions — rare completeness for a mid-size API.
- Every documentation page is available as clean Markdown by appending .md to the URL, and GitBook injects agent instructions plus a live '?ask=<question>' query endpoint on each page — an agent can retrieve exactly the doc it needs without HTML parsing.
- The biggest discovery gap is the absence of any machine-readable contract: no OpenAPI/Swagger spec (the heaviest-weighted check) and no AGENTS.md in the official raindropio repo, so an agent must infer request/response shapes from prose tables rather than a schema.
- Raindrop is already well-represented in the agent ecosystem — an official MCP server plus multiple community servers are listed across Glama, Smithery, and PulseMCP — so agents can act on bookmarks today even without an OpenAPI spec.
- Response examples are realistic (real IDs, real quotes, ISO timestamps), but request examples are thin (field tables and one-line JSON, no multi-language or curl snippets), and workflows beyond auth are documented per-endpoint rather than as end-to-end guides.
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 URL (e.g. developer.raindrop.io/openapi.json). This is the single highest-impact fix — it is the heaviest discovery weight and would let agents generate typed clients instead of scraping parameter tables.
- 02Add an AGENTS.md to the official raindropio/developer-site repo summarizing auth flow, base URL, rate limits, and the MCP endpoint — a cheap win on a rising discovery standard.
- 03Add copy-pasteable request examples in at least curl + one language for core endpoints (create raindrop, search, add highlight); current pages lean on field tables and show only response JSON.
- 04Write 2-3 end-to-end workflow guides (e.g. 'authenticate → create collection → bulk-import raindrops → tag → export') so agents can chain operations instead of assembling them from isolated endpoint pages.
- 05Serve a .well-known/mcp.json (currently 404) advertising the official MCP endpoint and auth so MCP-aware agents can auto-discover the server without visiting a registry.
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 well documented for a bookmark API: OAuth 2.0 with test tokens, standard HTTP status-code semantics (4xx = do not retry, 5xx = safe to retry), explicit rate limits (120 req/min with X-RateLimit-Limit/Remaining/Reset headers and a 429 example), and page/perpage pagination. Idempotency keys are not mentioned.