> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# defineTool

> Imperatively register a tool with this skill.

[ref-gettools]: /docs/server-sdks/reference/typescript/agents/skill-base/get-tools

Imperatively register a SWAIG tool with this skill. The tool definition is
merged with the skill's `swaigFields` (explicit fields on `toolDef` take
precedence) and then appended to the internal dynamic tool list. The default
[`getTools()`][ref-gettools] implementation returns these dynamic tools at
SWML render time.

> **Tip**
>
> Use `defineTool()` from `setup()` when the tool shape depends on config
> evaluated at setup time (e.g., an API key that changes the available
> actions). Skills with a static tool list should override `getTools()`
> directly instead.

## **Parameters**

**`toolDef`** `SkillToolDefinition` — required

The tool definition. Must include at minimum `name`, `description`,
`parameters`, and `handler`.

---

**`toolDef.name`** `string` — required

Tool name exposed to the AI.

---

**`toolDef.description`** `string` — required

One-sentence summary the AI sees when choosing whether to call the tool.

---

**`toolDef.parameters`** `Record<string, unknown>` — required

JSON-Schema-style parameter description.

---

**`toolDef.handler`** `(args, raw) => Promise<FunctionResult>` — required

Async function invoked when the AI calls the tool.

---

**`toolDef.secure`** `boolean` — default: true

Whether to require token validation on tool calls. Tools are secure by
default: the rendered webhook URL carries a per-tool token. Pass `false`
only to expose the tool on the shared, unauthenticated webhook URL.

---

## **Returns**

`void`

## **Example**

```typescript {9-17}
import { SkillBase, FunctionResult } from '@signalwire/sdk';

export class TimeSkill extends SkillBase {
  static SKILL_NAME = 'time';
  static SKILL_DESCRIPTION = 'Tells the current time.';

  async setup(): Promise<boolean> {
    const timezone = this.getConfig<string>('timezone', 'UTC');
    this.defineTool({
      name: 'get_time',
      description: `Get the current time in ${timezone}.`,
      parameters: { type: 'object', properties: {} },
      handler: async () => {
        const now = new Date().toLocaleString('en-US', { timeZone: timezone });
        return new FunctionResult().setResponse(`It's ${now}`);
      },
    });
    return true;
  }
}
```

> Imperatively register a tool with this skill.