ClickHouse is Good to agents.
Discry independently scored how well an AI agent can discover and understand the ClickHouse 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 · 86/100Comprehension
55% of score · 91/100What we found
- An agent that wants to manage ClickHouse Cloud programmatically finds a complete, publicly accessible OpenAPI spec at api.clickhouse.cloud/v1 with task-oriented operation names ("Create new service", "Update service auto scaling settings") and explicit parameter constraints (multiple-of-4 memory, [1..20] replicas, mutually-exclusive fields) — it can generate a correct client without guessing.
- ClickHouse meets agents where they live: an official AGENTS.md in the ClickHouse/agent-skills repo, an official mcp-clickhouse server listed across Glama, Smithery, and PulseMCP, and a dedicated 'Agentic Data Stack' page. An agent has first-class, vendor-sanctioned entry points rather than community guesswork.
- robots.txt allows all crawlers with no AI-bot blocks, and SQL/knowledgebase docs render as clean Docusaurus markdown with GitHub .md sources linked on every page, so an agent can ingest documentation losslessly.
- Error recovery is a standout: the knowledgebase ships cause→solution articles with exact config and commands (e.g., SSL code 210 CERTIFICATE_VERIFY_FAILED with platform-specific fixes), so an agent that hits an error can self-correct rather than fail blindly.
- The llms.txt exists but is a 92KB site-wide marketing dump (legal pages, blog newsletters, campaign pages) rather than an API/docs-focused index — an agent scanning it burns ~23K tokens on non-technical links before reaching documentation, and llms-full.txt and .well-known/mcp.json both return 404.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Add llms-full.txt (currently 404) consolidating the core SQL reference and Cloud API reference as clean markdown — the single highest-impact discovery fix for token-efficient agent ingestion.
- 02Slim llms.txt to an API/docs-focused index (linking /docs sections, the SQL reference, and the Cloud API) under ~50KB, instead of the current site-wide page dump that wastes agent context.
- 03Publish .well-known/mcp.json (currently 404) pointing at the official remote MCP server so agents can auto-discover ClickHouse's MCP tools without a registry search.
- 04Reconcile Cloud API field naming — camelCase fields (maxReplicas, numReplicas) coexist with snake_case passthrough settings (clickhouse_max_threads) in the same objects — or document the boundary explicitly so agents don't mis-case parameters.
- 05Document Retry-After / rate-limit response headers and idempotency-key support for the Cloud API so agents can back off correctly and safely retry write operations.
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.
The Cloud REST API is documented via a public OpenAPI spec (api.clickhouse.cloud/v1) that specifies basic-auth API keys, explicit rate limits (10 requests / 10s, 100 keys per org), and per-response error codes (400/500) with actionable messages. Pagination and idempotency keys are not prominently documented. Live behavior requires a full Discry Audit to verify.