MailboxValidator is Needs Work to agents.
Discry independently scored how well an AI agent can discover and understand the MailboxValidator 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 · 52/100Comprehension
55% of score · 72/100What we found
- An agent CAN discover and consume this API programmatically: an official OpenAPI specification is published on GitHub (mailboxvalidator-openapi) and SwaggerHub, and the service is listed across the major MCP registries (mcp.so, Glama, Smithery) with an official MailboxValidator MCP server — a rare double-win for a small vendor.
- MailboxValidator deliberately courts AI agents: a dedicated /ai-information page provides structured, LLM-targeted facts and 'AI Assistant Guidelines', and robots.txt blocks no AI crawlers. The intent to be agent-readable is clear and ahead of most peers.
- Despite that intent, there is no llms.txt or llms-full.txt — an agent gets the /ai-information page only if it already knows to look, since there is no machine-discoverable entry point pointing to it.
- Endpoint reference is genuinely agent-friendly: task-oriented descriptions, answer-first layout (method + URL + purpose up top), consistent snake_case fields, full parameter and error tables, and copy-pasteable samples in five languages.
- An agent hitting an error would understand WHAT failed (codes + messages + HTTP statuses) but not what to DO about it — there are no recovery steps, and no AGENTS.md exists in the GitHub org to guide a coding agent integrating the SDKs.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Add an llms.txt at the domain root linking to the three API references (single, disposable, free), the SDK pages, and the existing /ai-information page. This is the single biggest discovery gap — the agent-friendly content already exists but is not machine-discoverable.
- 02Link the official OpenAPI spec (GitHub / SwaggerHub) directly from the API reference pages and serve it from a stable api.mailboxvalidator.com path, so agents find it without a web search. Confirm the spec covers all three endpoints and current fields.
- 03Add recovery guidance to the error tables — e.g. '10004 Insufficient credits → top up at /plans#api', '10001 API key not found → retrieve key from dashboard' — so agents can self-correct instead of failing silently.
- 04Replace placeholder sample values ('Enter_Email', 'Enter_License_Key') with a realistic example email and show a sample JSON success response, so agents can pattern-match expected output, not just request shape.
- 05Publish an AGENTS.md in the primary SDK and MCP repos, and document explicit rate limits / concurrency expectations alongside the credit model so agents can plan request pacing.
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.
Auth is a single API key passed as a query parameter. Error format is well documented as machine-parseable JSON (error.error_code, error.error_message) with a full numeric error-code table mapped to HTTP statuses. No rate limits, pagination, or idempotency guarantees are documented — usage is governed by a credit quota rather than per-second limits.