Cortex · API

defineTool

defineTool defines a tool: an execute function with an input schema for its arguments. When the model calls the tool by name, Cortex parses the arguments against the schema, runs execute, and passes the return value to the model as JSON text. The model’s two turns are scripted; no model is called.

Tool and agent

const book = defineTool({
  id: 'book',
  name: 'book',
  description: 'Book seats for the member on a night',
  riskLevel: 'medium',
  input: z.object({ night: z.string(), seats: z.number().int().min(1).max(6) }),
  execute: ({ night, seats }) => {
    made.bookings += 1;
    return { night, seats, left: seatsLeftOn(night) - seats };
  },
});

const desk = defineAgent({
  id: 'desk',
  instructions: 'Book what the member asks for.',
  tools: [book],
});

const result = await desk.run('Two seats for Sunday, please.', { llm }).result;

Scripted model turns

1  calls book {"night":"2026-10-25","seats":2}
2  writes {"response":"Two seats for Sunday are yours. 112 are left."}

Output

{
  observation: {
    kind: 'result',
    toolId: 'book',
    args: { night: '2026-10-25', seats: 2 },
    result: { night: '2026-10-25', seats: 2, left: 112 },
  },
  toolResult: '{"night":"2026-10-25","seats":2,"left":112}',
  bookingsMade: 1,
}

Output matches the expected value

Runs in this page on the installed package. The input and the expected output are defined by the example.