platypus-tools

Platypus Tools

Two things make a tool reachable by an Agent: the tool itself, and the contribution that grants it. A tool nobody contributes is dead code.

1. Write the tool

An AI SDK tool() with three parts — description (how the model decides to call it), inputSchema (a Zod object, every field .describe()d), and execute (sync or async, returning a structured object).

export const convertTemperature = tool({
  description:
    "Convert temperature between Fahrenheit, Celsius, and Kelvin. Specify the value and the units to convert from and to.",
  inputSchema: z.object({
    value: z.number().describe("The temperature value to convert"),
    from: z.enum(["fahrenheit", "celsius", "kelvin"]).describe("Convert from"),
    to: z.enum(["fahrenheit", "celsius", "kelvin"]).describe("Convert to"),
  }),
  execute: ({ value, from, to }) => ({ result, unit: to }),
});

Note the shape: enums over a tool per unit pair. Widen a tool's parameters before you multiply tools — every extra name is another choice the model can get wrong.

Return { error: "..." } from a caught failure rather than throwing; the model reads the result and can recover.

Tool implementations live in the backend's tools directory, one file per subject area, tests co-located beside them.

2. Contribute the tool set

Tool sets are plugin contributions. Do not reach for registerToolSet — it is core-internal, and its one remaining caller is the Sandbox set, which is a Sandbox-backend extension point rather than a native tool set.

Add yours to the contributes.toolSets array of a PlatypusPlugin. Core plugins live under the backend's plugins directory, split by cohesion: pure utilities in one, the domain tool sets in another.

export const plugin: PlatypusPlugin = {
  name: "@platypus/tools-basic",
  version: "0.1.0",
  apiVersion: PLUGIN_API_VERSION,
  contributes: {
    toolSets: [
      {
        id: "time",
        name: "Time",
        category: "Utilities",
        description: "Tools for getting current time and converting timezones",
        tools: { getCurrentTime, convertTimezone },
      },
    ],
  },
};