> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# defineTool

> Define a SWAIG tool on a SWMLService instance.

[swaig-function]: /docs/swml/reference/ai/swaig/functions

[swml-swaig-functions-reference]: /docs/swml/reference/ai/swaig/functions

[functionresult]: /docs/server-sdks/reference/typescript/agents/function-result

[ref-swmlservice]: /docs/server-sdks/reference/typescript/agents/swml-service

Programmatically define a SWAIG function (tool) on a
[`SWMLService`][ref-swmlservice]. The SWAIG tool registry was lifted from
`AgentBase` into `SWMLService`, so any service — including standalone SWAIG
hosts and sidecars that do not produce an AI block — can register and dispatch
tools.

Tool definitions map to SWML [SWAIG function][swaig-function] entries. See the
[SWML SWAIG functions reference][swml-swaig-functions-reference] for the full
specification.

## **Parameters**

Tool definition object.

Tool name. Must be unique within the service. The AI uses this name to invoke
the function.

Human-readable description of what the tool does.

JSON Schema describing the tool's parameters.

Callback invoked when the tool is called. Receives
`(args: Record<string, unknown>, rawData: Record<string, unknown>)` and should
return a [`FunctionResult`][functionresult].

Whether to require token validation on tool calls.

Language-specific filler phrases spoken while the tool executes.

## **Returns**

[`SWMLService`][ref-swmlservice] -- Returns `this` for method chaining.

## **Example**

```typescript {5}
import { SWMLService, FunctionResult } from '@signalwire/sdk';

const service = new SWMLService({ name: 'swaig-host', route: '/' });

service.defineTool({
  name: 'get_weather',
  description: 'Get the current weather for a city',
  parameters: {
    type: 'object',
    properties: { city: { type: 'string', description: 'City name' } },
  },
  handler: async (args) => {
    const city = (args.city as string) ?? 'unknown';
    return new FunctionResult(`The weather in ${city} is 72F and sunny.`);
  },
});
```