Agent discoverability

Discoverability is how comprehension pays off for agents. Once Gecko has comprehended an API, agents need to find and install that surface. A human can read docs, infer the right call, and guess at parameters. An agent shouldn’t have to. These are the mechanisms that make an ingested API discoverable. An API surface, or a Solana Program Surface, can be made discoverable the same way.

Intent, not endpoints

An agent describes what it wants, not which path to hit. The catalog turns that intent into a ranked list of candidate operations, and the search_capabilities tool on the MCP surface exposes it directly:

client.search("what fixtures are coming up?")
# → [{ "name": ..., "summary": ..., "path": ..., "method": ... }, ...]

Question-shaped descriptions

Every tool’s description is written as the question it answers, with required and optional inputs called out. The agent picks the right tool from the description alone, no API docs in front of it. See How comprehension works.

Auth is out of the way

Auth headers never appear in the agent-facing tool input, and operations the current session can’t authenticate are hidden entirely. The agent’s surface is exactly the set of calls it can actually make, nothing it would only fail at. See Access & auth.

Only the calls that will work

When a session can’t satisfy an operation’s auth, that operation is removed from list_tools() and search(). Discoverability means surfacing the usable surface, not the whole spec. An agent should never discover a call it can’t complete.

An llms.txt for the API

Gecko can emit an agent/human-readable capability map grouped by tag, the machine-facing equivalent of a table of contents for the API:

print(client.catalog.describe())
# ## fixtures
# - GET /api/fixtures/snapshot — upcoming fixtures
# ## odds
# - GET /api/odds/snapshot/{fixtureId} — live odds for a fixture

This docs site itself ships an llms.txt, a discoverability map for these docs, in the same spirit. If you’re an agent, start there.

The agent-native layer, and we dogfood it

Docs are a human handoff. An llms.txt or an MDX page is something an agent has to read and trust; the agent-native contract is a structured tool it calls. Gecko’s job is to turn the human-shaped surface into that tool, so an agent finds and uses the right call without reading prose. Gecko projects one comprehended surface three ways, for three moments:

llms.txt: a breadcrumb for an agent that lands on the docs: the capability map plus a pointer to the live MCP and search_capabilities. (These docs ship one; read it.)
OpenAPI + x-gecko: the spec an OpenAPI-native tool already ingests, enriched in place with question-shaped intents, prerequisites, and worked examples. Unknown x- keys degrade gracefully, so a non-Gecko consumer just ignores them.
/.well-known/gecko.json: the machine-precise manifest search_capabilities navigates: the capability graph (which call produces the id another call needs), worked examples, and first-call-correct stats.

All three cross-link, so an agent landing on any one reaches the callable tool. This docs site is the reference implementation: our own surface is exposed through the same layer we generate for any API.

Everything an agent can fetch

This docs site publishes the same agent-native surface Gecko generates for any API. Point your agent at any of these:

llms.txt: the curated index of these docs
llms-full.txt: the whole docs as one Markdown file
gecko.json: the machine-readable manifest for this site
/.well-known/gecko.json: the manifest at the discovery-convention path
Any page on this docs site as Markdown: append .md to its URL (e.g. /discoverability.md)
Agent runbook and client wiring: the canonical setup on the landing site
Flagship MCP surface: Streamable HTTP, 16 tools, no key
Served surfaces: the ten mounted surfaces, each described at catalog.md. The host root, /mcp, serves two tools: comprehend_api and list_surfaces
Product manifest (canonical): the source-of-truth manifest on the landing

Shipped today: the MCP surface, search_capabilities, hidden auth, a usable-only surface, and this site’s own agent-native artifacts: llms.txt, gecko.json, and /.well-known/gecko.json (discovery level). Rolling out (see Roadmap): the x-gecko OpenAPI enrichment and the richer /.well-known/gecko.json capability graph (which call produces the id another call needs), search_capabilities returning the full call recipe inline (prerequisites + a worked example), and access-quality measurement: did the agent find and correctly use the call. We build these against our own docs first.

Scope

Discoverability is live today on an ingested OpenAPI 3.x surface. Gecko makes a known API surface agent-usable. It doesn’t crawl arbitrary human-only docs, auto-discover APIs across the internet, or verify the data an API returns. See Status.

Get Started

How it works

Use cases

On-chain

For AI agents

For API providers

Reference

Agent discoverability

Intent, not endpoints

Question-shaped descriptions

Auth is out of the way

Only the calls that will work

An llms.txt for the API

The agent-native layer, and we dogfood it

Everything an agent can fetch

Scope

​Intent, not endpoints

​Question-shaped descriptions

​Auth is out of the way

​Only the calls that will work

​An llms.txt for the API

​The agent-native layer, and we dogfood it

​Everything an agent can fetch

​Scope

Intent, not endpoints

Question-shaped descriptions

Auth is out of the way

Only the calls that will work

An llms.txt for the API

The agent-native layer, and we dogfood it

Everything an agent can fetch

Scope