Tools and the catalog for agents

​

The two-file surface

1. vendo/registry.tsx: the component registry. One object keyed by component name; each entry holds the real component reference, a description the model reads, and an optional zod props schema. The same object serves both sides: createVendo reads it as catalog (data fields only) and <VendoRoot components={registry}> reads the component references. There is no second map to keep in sync.
2. The composition: one createVendo({...}) call. On Next.js it lives in the catch-all route app/api/vendo/[...vendo]/route.ts; on Express in vendo/server.ts (server.mjs when the host has no TypeScript), mounted with app.use("/api/vendo", mountVendo()).

​

Tools come from extraction, not from you

• Never hand-edit .vendo/tools.json. It is regenerated. Durable corrections go in .vendo/overrides.json, which wins field by field and is never touched by sync.
• Never invent a tool. If an endpoint was not extracted, fix the source it is extracted from (or its OpenAPI spec) and re-run npx vendo sync; do not add entries by hand.
• Unclassifiable routes are extracted disabled with a note. Enable them deliberately in overrides.json after review, never blanket-enable.

​

What makes a good tool

• A task-oriented description, written for the model: what the tool does for the user, when to reach for it, not a restatement of the route path.
• An honest risk label. read auto-runs, write and destructive are policy-gated (default policy: destructive asks first). Risk can be raised in overrides, never lowered.
• critical: true on irreversible actions (delete, send, cancel) so policy always asks before running them.

npx vendo extract --apply draft.json

​

The catalog contract (anti-prop-invention)

• Copy prop names from the component’s source, never from convention. If SpendingDonut takes slices, the schema says slices, not data.
• Give it a zod props schema. A schema-less entry is legal (the model infers props), but a schema is what makes prop invention impossible; prefer it whenever the component has typed props.
• Schema only what the model should control. Data-shaped props belong in the schema; internal callbacks and render props do not.
• Write the description for selection: what the component shows and when to use it, e.g. “Spending by category. Use for where-did-my-money-go requests.”

import type { ComponentRegistry } from "@vendoai/core";
import { z } from "zod";
import { SpendingDonut } from "@/components/charts/spending-donut";

export const registry = {
  SpendingDonut: {
    component: SpendingDonut,
    description: "Spending by category. Use for where-did-my-money-go requests.",
    props: z.object({
      slices: z.array(z.object({ category: z.string(), amount: z.number() })),
    }),
    examples: ['{"slices":[{"category":"dining","amount":342.18}]}'],
  },
} satisfies ComponentRegistry;