PublishedDocs / Reference
defineTool
Define a typed model-callable function with validation and optional authorization requirements.
Shape
defineTool({
name: "save_lead",
description: "Save a lead for creator follow-up.",
category: "business",
input: z.object({
email: z.string().email(),
need: z.string(),
}),
execute: async (input) => JSON.stringify({ lead: await saveLead(input) }),
});Options
| Option | Use |
|---|---|
| name | Tool identifier the model calls; imperative or domain terms work best. |
| description | What the tool does and when to use it; the model selects tools from this. |
| category | Grouping label such as business or commerce. |
| input | Zod schema that validates model-provided input before execute runs. |
| execute | Async function receiving validated input; returns a string, usually JSON. |
| requires | Optional advanced preview delegated authorization rule: { action, resource: { input } }. |
Guidance
- Use names that describe the operation in imperative or domain terms.
- Keep descriptions specific enough for tool selection.
- Keep input schemas narrow and explicit.
- Use skills for workflow teaching that does not fit in the tool description.
- Use the preview requires surface only when app-owned delegated authorization should gate execution.
Related
Add toolsExpose typed actions the model can select during a turn and your code executes.SkillsTeach the model when and how to use an augment without loading every instruction into context on every turn.defineAugmentDefine a runtime capability that contributes tools, context, memory, transports, lifecycle, or policy to an agent.