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.

Data access follows origin. A core plugin may import backend internals — the database, the backend's tool modules. A third-party plugin uses only what @platypuschat/plugin-sdk hands it; when it needs a value core already has, add an optional field to the SDK context rather than reaching past it (ADR-0013).

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 },
      },
    ],
  },
};

• id — kebab-case, and a stable identifier: Agents persist granted ids, so renaming a shipped id silently strips the set from every Agent holding it. Core ids stay unprefixed.
• category — groups the set in the Agent form. Take an existing category unless the set genuinely sits outside all of them.

Done when the set appears in the Agent form under its category and its tools run in a chat.

Adding a new plugin

A capability earns its own plugin when an Operator would plausibly want to deny it in isolation — that is why egress and infra are separate plugins while utilities share one. Cohesion, not subject matter, is the test.

A new plugin needs an entry in the built-in loader map, which is the core allowlist — membership there is what makes a plugin core. Then decide its gating: the always-on list for essentials no Operator would deny, otherwise it waits behind the plugins env var. A name in both is rejected fail-loud, since listing an always-on plugin as an enable switch is a misconfiguration.

3. Give it a chat icon

Unmapped tools fall back to a wrench. The icon resolver checks three maps in order, so pick the rung that fits:

1. Per-tool overrides — checked first. For a set whose tools are visually distinct, or tools belonging to no set at all. Keep it sparse.
2. Tool name → set id — every tool needs an entry here unless it has an override. A tool in several sets maps to whichever fits best; the icon is correct regardless of which set supplied it at runtime.
3. Set id → Lucide icon — one per set, matching the workspace home page.

Done when every tool name your contribution exports resolves to something other than the wrench.

Scoping tools to a workspace

Set tools to a factory instead of an object and it resolves per chat turn against a ToolSetContext — workspace, agent, org, user, and frontend URL:

tools: ({ workspaceId, agentId, orgId, frontendUrl }) =>
  createKanbanTools(workspaceId, agentId, orgId, frontendUrl),

Keep the factory in the tool's own file, returning Record<string, Tool>.

The context also carries registerCloser for anything needing teardown at end of turn. Call it unguarded — ctx.registerCloser(close). It is required from plugin API v2, and every core that accepts the current apiVersion supplies it.

Sharing one tool across sets

Extract it into a standalone exported factory returning a single Tool. The owning set calls that factory internally; other sets import and call it too.

Use the same key name in every set, and wrap the tool in shareTool(key, tool). Tools claim names into one map as each set resolves; a name already held by the same shared tool is skipped — a deliberate dedup, not a collision. Without shareTool the later set's copy wins and a collision is logged. Differing keys give the Agent the same tool twice under two names.

When two different tools claim one name the later claim wins and the shadowed one is logged with both owners, so check the logs before assuming a tool is missing. Turn precedence runs session tools, then search, then sub-agent tools — each layer beating the one before it.

Custom chat UI

Tools render their input and output as JSON by default. For a bespoke card — interactive elements, images, structured results, or progress during execution — read CUSTOM-UI.md, which carries the renderer contract and the double-render trap.

When a tool doesn't appear

Tool resolution is strict at boot, forgiving at runtime: a duplicate set id throws on startup, but at turn time an unresolvable id, a factory that throws or outruns the resolve deadline, or an unreachable or unanswering MCP server each costs only its own tools, logging a warning. A chat turn is not where you discover a plugin is broken — so a silently toolless Agent is a log question, not a UI question.

Work down the chain: is the set in a plugin's contributes.toolSets; is a new plugin in the loader map and either always-on or named in the env var; does the Agent actually hold the set's id; does the backend log a resolution warning for this turn.

Resources

• ADR-0013 (plugin contributions), ADR-0014 (web-search backends)
• AI SDK tool calling, Zod