# defineTool

Canonical: https://auggy.dev/docs/define-tool
Status: Published
Package: auggy 0.5.0

Define a typed model-callable function with validation and optional authorization requirements.

## Shape

**Tool definition**

```ts
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 tools](https://auggy.dev/docs/add-tools/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [defineAugment](https://auggy.dev/docs/define-augment/markdown)