Declare tools from an OpenAPI description

[haruotsu]

Based on #33 (PUT/PATCH on ConnectionClient) — merge that first.

What

A new openapi: tool kind: a service that publishes an OpenAPI description but runs no MCP server can be declared without writing Python.

tools:
  - openapi:
      spec: ./specs/helpdesk.yaml
      connection: helpdesk
      operations: [ListSearchResults, ShowTicket, ListTicketComments]
      effect: read
      does_not: Results are the caller's own view; not found is not proof of absence.
      params:
        ListSearchResults:
          query: {prefix: "type:ticket "}
          per_page: {value: 25}
      describe:
        ListSearchResults: Search tickets. The kind is fixed to tickets.

ADK's spec parser produces the Gemini function declarations; execution stays in gete's ConnectionClient, so the destination check, the caller's token, redaction, and the never-resend rule hold exactly as for every other tool.

The decisions, and why

operations is required, never defaulted. Measured against a real published description (1.7 MB): the toolset builder happily turns all 443 paths into 640 tools in 0.4 s without failing, so nothing would ever alert an author who forgot to narrow. Forgetting to choose must not mean offering everything — same reasoning as mcp.allow refusing an empty list. Operations are picked by operationId, which also becomes the tool name (one vocabulary for declarations, policies, and logs).

Request URLs come from the connection's base_url; the description's servers are never read. Published servers entries carry variables and stale defaults (e.g. https://{subdomain}.example.com with a default subdomain nobody owns) — following them would connect nowhere, or to someone else's tenant. validate refuses a connection without a root; the client's host check still guards every request.

params keeps what replaced code used to enforce. The Python tools this replaces pinned things like a search-type prefix and a page size; a declaration that lost those pins would open a hole the code had closed:

• value fixes a parameter and removes it from what the model sees — its value is declared, so there is nothing left for the model to say. (The draft's separate hidden: flag is folded into this: a fixed-but-visible parameter would just invite arguments that get silently overridden.)
• prefix / suffix wrap what the model writes, declared text first — a type: qualifier written by the model cannot displace the declared one.

describe replaces vendor text; does_not rides along. Vendor descriptions are written for developers next to the docs and cite relative links a model cannot follow — leaving them in manufactures fake grounding.

The description is fixed at packing time. gete archive carries the file into the archive and the runtime reads it from there; a vendor editing the published file changes nothing until someone re-archives deliberately. Remote spec: URLs are not supported in this PR.

Read/write split. PUT, PATCH, and DELETE operations must sit in an effect: write block (validate refuses them under effect: read), ride the same confirmation policies, and are never resent. A DELETE with a request body is refused: the client sends none (RFC 9110 gives one no meaning), and the operation would lose arguments silently.

Legibility of published files. Real published descriptions fail yaml.safe_load on YAML 1.1 leftovers (a bare = key typed as tag:yaml.org,2002:value); the spec loader accepts that tag, and anything else unparsable is reported as "this description cannot be read" with the file named.

What validate checks

Connection declared by the agent and rooted (base_url); the spec file exists, parses, and actually holds every selected operationId (duplicated ids are refused as ambiguous); methods are GET/POST/PUT/PATCH/DELETE; params/describe keys name selected operations; a fix names a real parameter (with the real names listed when it does not); prefix/suffix only on string parameters; required header parameters, non-JSON bodies, and GET-with-body are refused.

At run time: nothing is offered without a usable token (as with MCP), the connection joins the shared reauthorization tool, path parameters are URL-escaped so a value cannot climb out of its segment, and results flow through the policies' redaction.

Not declared on purpose

Response shaping — count annotations, turning "not found" into a soft answer — stays out of the declaration. The raw response carries what the model needs, and anything more involved is what python: tools are for.