Skip to main content
Gecko’s whole reason to exist is discoverability for agents. 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.

​
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:
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.

​
Honest scope

Discoverability is real today on an ingested OpenAPI 3.x surface. Gecko does not crawl arbitrary human-only docs yet, does not auto-discover APIs across the internet, and does not verify the data an API returns. It makes a known API surface agent-usable. See Status.