Skip to navigation
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
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.

toolDef.gates
ReadonlyArray<SemanticGate | Record<string, unknown>>

1 to 8 semantic gates that must pass before the tool runs. They take precedence over gates in the skill’s swaigFields. Checked when the skill is added to an agent.

toolDef.gate_fillers
FillerPhrases

What the AI says while the gates are checked, shaped like fillers.

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