defineTool

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

1 import { SkillBase, FunctionResult } from '@signalwire/sdk';
2 
3 export 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 }

1	import { SkillBase, FunctionResult } from '@signalwire/sdk';
2
3	export 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	}