Tools from your API

One command reads your API and hands the agent a guarded set of tools.

The pipeline

Four extractors read what you already wrote. One file is the result.

Only tools in that file exist. Nothing else reaches your API.

Fails closed. A route the extractor cannot classify is written disabled, with a note saying why. Enable it deliberately after you read it.

Extraction runs in a fixed order: OpenAPI, tRPC, Next.js server actions, then the route scan. Each one skips itself when your app has nothing for it.

Declare your schemas: openapi.json

The single highest-leverage file you can add is an openapi.json at your app root (public/openapi.json and docs/openapi.json — or .yaml — are read too). Without a spec, a plain route scan finds your endpoints but not their shapes: each tool arrives as a method and a path with no parameters and no output schema, and the report says so —

tool schemas: inputs 0/18 · outputs 0/18 — blind: host_customers_get, host_orders_list …

A blind tool is one the agent cannot really use: GET /api/orders may support status, customer_id, and limit, and the model has no way to know any of them exist. Add the spec and re-run npx vendo init (or vendo sync) and the same routes come back with every parameter name, type, and output shape declared:

tool schemas: inputs 18/18 · outputs 18/18

Most frameworks can generate the file from your existing routes or validators — anything that emits standard OpenAPI 3.x works, and the spec never needs to be served: a file on disk is enough.

One tool, honestly

Every entry carries the same five fields. Here is one, whole.

.vendo/tools.json

{
  "name": "host_deleteTask",
  "description": "Permanently delete a Relay task",
  "inputSchema": {
    "type": "object",
    "properties": { "id": { "type": "string" } },
    "required": ["id"]
  },
  "risk": "destructive",
  "binding": {
    "kind": "openapi",
    "operationId": "deleteTask",
    "method": "DELETE",
    "path": "/api/tasks/{id}"
  }
}

• description is written for the model: what the tool does for the user, not a restatement of the path.
• risk is what the guard reads before the call. destructive asks first.
• binding is where the call lands. The runtime executes from it without re-reading your spec.

Where the grade comes from

Extraction grades from protocol facts only. DELETE is destructive and a tRPC mutation is at least write; a name decides nothing.

Everything else lands ungraded, which the guard asks about on every call. The grading pass reads the handler behind each tool and writes what it finds to .vendo/judgments.json.

The grading pass runs on your Vendo Cloud key.

Never hand-edit .vendo/tools.json. The next sync regenerates it wholesale.

Keeping it current

The tool surface is a build artifact, so it moves when your API moves.

1. Edit your API

   Add the route, the procedure, or the action. Nothing about it is Vendo-shaped.

2. Run npx vendo sync

   The extractors re-read your source. No server starts.

3. Read the diff in git

   .vendo/tools.json is a tracked file, so a new capability arrives as a reviewable change.

vendo init hooks sync into predev and prebuild in your package.json, so step 2 also runs on its own.

Overrides

Corrections live in their own file, which sync never touches.

.vendo/overrides.json

{
  "format": "vendo/overrides@3",
  "tools": {
    "host_invoices_delete": { "risk": "destructive", "confirmEach": true },
    "host_internal_debug": { "disabled": true }
  }
}

Overrides win field by field: re-grade a tool, make it confirm every run, or hide it entirely. They are the last word, applied after both extraction and the grading pass.

Raising risk lapses old grants. The next call parks a fresh approval that names the invalidated grant, and audits one grant-invalidated decision.

Compound tools

The same file’s compounds array bundles a short sequence of existing tools into one capability the agent calls by name.

.vendo/overrides.json

{
  "format": "vendo/overrides@3",
  "tools": {},
  "compounds": [
    {
      "name": "host_invoice_send_flow",
      "description": "Create an invoice and email it",
      "inputSchema": { "type": "object" },
      "risk": "write",
      "binding": {
        "kind": "compound",
        "steps": [
          { "id": "create", "tool": "host_invoices_create", "args": { "amount": "args.amount" } },
          { "id": "send", "tool": "host_invoices_send", "if": "args.email != null", "args": { "id": "steps.create.id" } }
        ]
      }
    }
  ]
}

Keep tools even when it is empty — it is a required key. Each args value is a JSONata expression evaluated against { args, steps, item }, not a literal, which is how steps.create.id hands one step’s output to the next.

Two rules the loader enforces after the file parses: risk must equal the highest risk among the steps, and a step may only name an enabled primitive tool — never another compound. An entry that breaks either is quarantined with a console warning rather than failing the boot, so read the log once after adding one.

Each step still crosses the guard on its own descriptor, so approvals, grants, and audit apply per step. A compound entry inside tools.json is rejected.

Where to go next

Your API is one source of tools. Two more sit beside it.

Connected accounts

Each user connects their own Gmail, Slack, or GitHub once.

Connected accounts →

Automations

The same tools, fired on a schedule or by an event.

Automations →

Guard

Risk grade, approval, and an audit line on every call.

How Vendo works →