Finch is Good to agents.
Discry independently scored how well an AI agent can discover and understand the Finch 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 Finch's docs finds first-class machine-readable surfaces: a structured llms.txt indexing every endpoint as a .md file, a 358KB llms-full.txt, a 107-URL sitemap, and a robots.txt that explicitly green-lights AI (Content-Signal: ai-train=yes, ai-input=yes). Discovering and parsing the documentation is effectively frictionless.
- An agent seeking the OpenAPI spec at the conventional /api-reference/openapi.json path gets Mintlify's placeholder 'Plant Store' sample, not Finch's API. The real, complete 48-endpoint spec (server api.tryfinch.com) is public but only reachable via an obfuscated Stainless GCS hash URL referenced in the SDK repos — so most agents would either never find it or build against the wrong spec.
- Finch's docs are written for autonomous consumption: explicit per-error recovery (401 -> reauthenticate via Connect and discard the old token, 408 -> raise client timeout to 6 minutes, 429 -> backoff/retry, 202 -> retry async with backoff), structured finch_code error objects, and numbered end-to-end implementation guides. An agent that hits an error can self-correct without human intervention.
- Capability boundaries are unusually explicit. The docs distinguish automated vs assisted providers (read/write support differs), publish per-provider historical-data limits (Paychex Flex 14 months, Paycom 2 years of pay statements), and expose a provider field-support matrix — so an agent knows what it cannot do before it fails.
- Finch ships an official MCP server, but its .well-known/mcp.json points to a Mintlify branch-preview URL (finch.main-kill-isr.mintlify.me/mcp) rather than a production endpoint and lacks explicit tool declarations, and Finch is absent from Glama/Smithery/PulseMCP. An agent discovering tools via registries or the well-known file would miss or misroute to Finch's MCP.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Serve the real OpenAPI spec at a discoverable path (e.g. /api-reference/openapi.json, or link it from llms.txt) instead of Mintlify's placeholder plant-store sample. This is the single highest-impact fix — agents currently retrieve the wrong spec entirely.
- 02Fix .well-known/mcp.json to point at Finch's production MCP endpoint rather than the main-kill-isr.mintlify.me branch-preview URL, and add explicit tool and auth declarations so agents can route to it reliably.
- 03List Finch's MCP server in the major registries (Glama, Smithery, PulseMCP) so registry-browsing agents can discover it — currently only AWS Finch (an unrelated container tool) surfaces in those searches.
- 04Add an AGENTS.md to the primary SDK repos (finch-api-node, finch-api-python) with build/test/usage context for coding agents — a quick discovery win that's currently absent.
- 05Add a concise single-page capability overview so an agent can grasp the 7-product model and Connect flow in under ~5K tokens without traversing the full implementation guide set, improving token efficiency.
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 to an unusually high standard. Errors return a structured, machine-parseable JSON object (code, name, finch_code, message), with separate handling documented for batch (per-item) and HTTP-level errors. Rate limits are specified per-product with concrete numbers (20 req/min organization, 12 req/min pay) on a rolling 60-second window, plus retry/backoff code samples. Auth supports OAuth 2.0, API token, user credentials, and assisted methods; Connect sessions use Basic Auth (client_id:client_secret) and API calls use a Bearer access token. Pagination is covered in the API-Calls guide. Explicit idempotency keys are not documented, though some endpoints (e.g. Create Deduction) are idempotent by design and async 202 retry semantics are spelled out.