Skip to main content
Comprehension is the product. It is the path from a raw API surface to tools an agent calls correctly the first time. Three stages, each a small focused module. The same comprehension runs on-chain: The Program Surface recovers the PDA seeds a Solana IDL drops and derives the accounts first-plan-correct. Gecko turns a raw OpenAPI operation into a question-shaped tool with a JSON schema — auth header removed

​
1. Ingest the surface

Gecko parses an OpenAPI 3.x document (YAML or JSON) into a normalized list of operations. It resolves local $refs with cycle and depth guards — on a cycle or when the depth cap is hit, the $ref is left in place rather than expanded, so callers still get a usable (if shallow) schema. Path-level parameters are merged into each operation’s own parameters. Each Operation carries: method, path, operation_id, summary, description, tags, parameters, request body, responses, and security. Each Param carries: name, location, required, schema, description.
Ingest reads the surface only — method, path, params, request/response schemas. It never reads or stores response data. The ingestor is stdlib + PyYAML by design, so it runs anywhere with zero heavy dependencies.
Ingested spec content is treated as untrusted input, and any URL fetched to load a remote spec is validated first.

​
2. Catalog — intent to endpoint

The catalog lets an agent go from a natural-language goal to the right endpoint. It scores each operation by lexical overlap between the query and the operation’s surface text — summary, description, path, tags, and id — with summary matches weighted double (it’s the most intent-bearing field). Results are ranked and returned.
It can also group capabilities by tag and emit a human/agent-readable capability map. This is lexical, not vector search, and that is a design choice rather than a milestone: the graph never approximately remembers. BM25 and semantic tiers both sit behind evidence gates that flip only on measured lexical recall failure — fed by a misrank-aware evaluation (a golden set plus a closed miss-cause vocabulary). One measured negative result on embeddings is already on record. See find_start for the on-chain twin of this router and the honesty floor it enforces.

​
3. Comprehend — the question-shaped tool

Each operation becomes an MCP-compatible tool definition: a name, a question-shaped description, and a JSON-Schema input. Two decisions make this more than a raw OpenAPI dump: Hide the plumbing. Auth headers (Authorization, X-Api-Token, and similar) are stripped from the agent-facing input. The agent reasons only about decision-relevant inputs; the access layer injects credentials at call time. Carry invocation metadata. The tool keeps an internal _invoke block — method, path, and the location of each parameter — so the caller can build the real HTTP request without re-parsing the spec. A generated tool looks like:
requires_auth is true only when every way to call the operation needs auth (an OpenAPI security requirement of {} means “no-auth is also acceptable”, which keeps it optional). The client uses requires_auth + the session to hide operations a no-auth session could never satisfy, so the agent never wastes a call on them.

​
4. Build the correct request

When the agent calls a tool, the caller places each argument by its location, injects the hidden auth headers, and assembles the request. Crucially, it catches the silent first-call failure — for example a missing required path parameter raises a typed CallError instead of firing a malformed request the agent can’t diagnose.

​
Measuring first-call-correct

Gecko ships a falsifiable scorecard. Given a client and a list of {goal, expect_op, args} tasks, it measures whether the comprehension layer retrieves the right operation (top-1 / top-5) and builds a well-formed request for it — recorded and offline, recording only outcome metadata (tool, rank, ok/reason), never payloads.
This is the same harness used to score a second public API end-to-end (see the scripts/pegana_eval.py worked example in the repo, which ingests a public peg-state API with a no-auth session and scores first-call-correctness, including correctly refusing to fire an auth-gated operation on a public read). It’s evidence the engine is API-agnostic, not a claim that Gecko one-shots every API.