Tools for an agent

A tool is something the model can call during submit. Make it with defineTool, then pass it in tools.

import { defineTool, Type } from "@loops/sdk";
 
export const bookAppointment = defineTool({
  name: "book_appointment",
  description: "Book a follow-up appointment at the practice",
  parameters: Type.Object({
    patientId: Type.String(),
    date: Type.String({ description: "The day they asked for, as YYYY-MM-DD" }),
  }),
  execute: async (input) => {
    const response = await fetch(
      "https://api.practice.example.com/v1/appointments",
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(input),
      },
    );
 
    if (!response.ok) {
      throw new Error(`Booking failed: ${response.status}`);
    }
 
    return response.json();
  },
});

The parts

• name — what the model calls. Keep it unique in the project.
• description — tells the model when to call it. Write it for the model.
• parameters — a TypeBox schema built with Type, which @loops/sdk re-exports. The model’s arguments are checked against it before execute runs.
• execute(input) — runs with the checked arguments, typed from parameters. What it returns goes back to the model: a string as it is, anything else as JSON.

What a tool can reach

A tool’s execute gets its input, nothing else. It can:

• Call your own systems with fetch, to hosts the loop allows. See Calling an external system.
• Start a workflow with trigger. The built-in tools and bindings live on a workflow’s ctx, so this is how an agent sends a text, checks a symptom, or creates a scan. See Calling a workflow.

import { defineTool, Type } from "@loops/sdk";
 
import { symptomCheck } from "./symptom-check";
 
export const checkSymptom = defineTool({
  name: "check_symptom",
  description:
    "Check a physical symptom against a red-flag list. Runs in the background and saves the result on the patient.",
  parameters: Type.Object({
    userId: Type.String(),
    symptom: Type.String(),
    patientWords: Type.String(),
  }),
  execute: (input) => symptomCheck.trigger(input),
});

Where tools live

Put tools in the agent’s file, or in a helper file that the agent imports. If two files in the project define a tool with the same name, the agent uses the one its own file exports. Otherwise the call fails and asks you to rename one.

A turn that is recovered after a crash can call a tool again, so make tools safe to repeat where you can.