honcho is Good to agents.
Discry independently scored how well an AI agent can discover and understand the honcho 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 · 81/100Comprehension
55% of score · 96/100What we found
- An agent crawling honcho.dev finds a best-in-class robots.txt that explicitly allow-lists every major AI crawler (GPTBot, ClaudeBot, PerplexityBot, CCBot, Google-Extended, plus Cohere/Mistral/xAI) and declares Content-Signals — near-zero friction for discovery.
- The documentation is genuinely agent-native: a well-structured llms.txt (~4K tokens) enumerates every endpoint with a task-oriented description, a 640KB llms-full.txt carries the complete docs as markdown, and each page is available as a .md file — an agent can ingest the whole API without HTML parsing.
- Endpoint descriptions are written for outcomes, not interfaces (e.g. Chat: 'Query a Peer's representation using natural language... performs agentic search and reasoning'), and code examples are abundant across bash (201), Python (158) and TypeScript (113) with realistic keys and IDs.
- A valid .well-known/mcp.json is served and an official, no-auth Honcho MCP server is published and listed in MCP registries — an agent can connect to Honcho as a live tool, not just read about it.
- The one real gap is machine-discoverable execution contracts: no publicly reachable OpenAPI spec (api.honcho.dev/openapi.json is auth-gated, 401), no AGENTS.md (a substantive CLAUDE.md exists instead), and no documented idempotency or structured error-format — an agent must lean on the SDKs rather than the raw contract.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish the OpenAPI spec at a public, unauthenticated path (e.g. honcho.dev/docs/openapi.json). The Mintlify API reference is already generated from a spec — exposing it would move openApiSpec from partial to pass and is the single highest-weight discovery win.
- 02Add an AGENTS.md to the plastic-labs/honcho repo root (the substantive CLAUDE.md can be near-verbatim source). This is a rising standard for coding agents and a quick, high-signal fix.
- 03Document the structured error-response format and idempotency behavior in the API reference: show the JSON error body/fields, map the top 429/4xx/5xx scenarios to explicit recovery steps (e.g. Retry-After handling), and state whether write endpoints accept idempotency keys.
- 04Serve an llms.txt (and mcp.json) at the root honcho.dev origin, not only at the docs host — the root currently 404s for llms.txt, so agents that probe the marketing domain first miss the well-built docs artifacts.
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 JWT/Bearer API keys (hch-* keys) scoped to workspace/peer/session hierarchy, clearly documented. Pagination is consistently documented across list endpoints (default 10, max 100, limit param). Rate limits are referenced in the changelog/guides. Structured error-response format is not spelled out (SDKs are recommended for error handling) and idempotency keys are not documented.