Tools you write by hand

​

defineTool

import { createVendo } from "@vendoai/vendo/server";
import { defineTool } from "@vendoai/vendo";
import { z } from "zod/v4";

const refundOrder = defineTool({
  name: "host_refundOrder",
  description: "Refund a paid order back to the original card",
  input: z.object({ orderId: z.string(), reason: z.string() }),
  risk: "destructive",
  execute: async ({ orderId, reason }, context) => {
    return await payments.refund(orderId, { reason, actor: context.principal.subject });
  },
});

export const vendo = createVendo({ tools: [refundOrder] });

• input is the single statement of the arguments. It becomes the JSON Schema the model is shown and the parse that runs before execute, so the two can never drift apart. A call that does not match is refused before your function runs.
• risk is required, and it is a grade: read, write, or destructive. You wrote the tool, so you know. Only extraction is allowed to answer ungraded.
• context is the run context — context.principal is whose authority the call carries.
• execute returns the output, or throws. The denial outcomes belong to the guard: nothing you write can fake an approval.

​

The fields it does not ask for

const refundOrder = {
  ...defineTool({ /* … */ }),
  confirmEach: true,
  title: "Refund an order",
};

​

Where to go next