PublishedDocs / Runtime

Add tools

Expose typed actions the model can select during a turn and your code executes.

When to add a tool

The agent needs to retrieve, create, update, or send something during conversation.
The operation needs typed input and code-enforced execution.
The model can decide when the operation is useful, but should not hand-write the side effect.
A route alone would force the visitor into a rigid form before intent is clear.

Tool shape

Tool with Zod inputTypeScript

import { defineTool } from "auggy";
import { z } from "zod";

export const lookupOrder = defineTool({
  name: "lookup_order",
  description: "Look up an order after the visitor is verified.",
  category: "commerce",
  input: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => {
    const order = await getOrder(orderId);
    return JSON.stringify({ order });
  },
});

Tool policy

Put narrow, explicit descriptions on tools; the model uses them to decide whether to call.
Use Zod input schemas to constrain model-provided input before execution.
Use delegated requires rules for protected tools when app-owned authorization matters.
Return structured strings, usually JSON, so the next model step can reason from exact output.
Move business logic into domain functions so routes and tools can share it.

Related

Build an augmentBuild one project-specific typed tool inside a custom augment.SkillsTeach the model when and how to use an augment without loading every instruction into context on every turn.defineToolDefine a typed model-callable function with validation and optional authorization requirements.