defineTool | SignalWire

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

booleanDefaults to 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

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;
  }
}