AgentsSkillBase

defineTool

View as MarkdownOpen in Claude

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() implementation returns these dynamic tools at SWML render time.

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
SkillToolDefinitionRequired

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

toolDef.name
stringRequired

Tool name exposed to the AI.

toolDef.description
stringRequired

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

When true, the tool requires signed tokens for invocation.

Returns

void

Example

1import { SkillBase, FunctionResult } from '@signalwire/sdk';
2
3export class TimeSkill extends SkillBase {
4  static SKILL_NAME = 'time';
5  static SKILL_DESCRIPTION = 'Tells the current time.';
6
7  async setup(): Promise<boolean> {
8    const timezone = this.getConfig<string>('timezone', 'UTC');
9    this.defineTool({
10      name: 'get_time',
11      description: `Get the current time in ${timezone}.`,
12      parameters: { type: 'object', properties: {} },
13      handler: async () => {
14        const now = new Date().toLocaleString('en-US', { timeZone: timezone });
15        return new FunctionResult().setResponse(`It's ${now}`);
16      },
17    });
18    return true;
19  }
20}