> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# defineTypedTool

> Register a SWAIG tool with a typed handler that receives named parameters.

[define-tool]: /docs/server-sdks/reference/typescript/agents/agent-base/define-tool

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

[ref-agentbase]: /docs/server-sdks/reference/typescript/agents/agent-base

Register a SWAIG tool with a typed handler that receives named parameters instead of
the standard `(args, rawData)` convention. The SDK wraps the handler to unpack the
args object into positional params.

If no `parameters` schema is provided, one is inferred from the handler's source
code (parameter names and default values).

> **Tip**
>
> Use `defineTypedTool()` when you want cleaner handler signatures with named
> parameters. Use [`defineTool()`][define-tool] when you need full control over
> the args object.

## **Parameters**

**`opts`** `object` — required

Tool definition object.

---

**`opts.name`** `string` — required

Tool name. Must be unique within the agent.

---

**`opts.description`** `string` — required

Human-readable description. The AI reads this to decide when to call the tool.

---

**`opts.parameters`** `Record<string, unknown>`

JSON Schema describing the tool's parameters. If omitted, the schema is
inferred from the handler's parameter names and default values.

---

**`opts.handler`** `Function` — required

Typed handler that receives named parameters extracted from the args
object. Parameter names must match the JSON Schema property names.

---

**`opts.secure`** `boolean` — default: 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.

---

**`opts.fillers`** `Record<string, string[]>`

Language-specific filler phrases spoken while the tool executes.

---

**`opts.waitFile`** `string`

URL of an audio file to play while the tool executes.

---

**`opts.waitFileLoops`** `number`

Number of times to loop the wait file.

---

**`opts.required`** `string[]`

List of required parameter names from the JSON Schema.

---

## **Returns**

[`AgentBase`][ref-agentbase] -- Returns `this` for method chaining.

## **Example**

```typescript {6}
import { AgentBase, FunctionResult } from '@signalwire/sdk';

const agent = new AgentBase({ name: 'weather-agent', route: '/weather' });
agent.setPromptText('You are a helpful weather assistant.');

agent.defineTypedTool({
  name: 'get_weather',
  description: 'Get the current weather for a city',
  handler: (city: string, unit: string = 'fahrenheit') => {
    const temp = unit === 'celsius' ? '22C' : '72F';
    return new FunctionResult(`The weather in ${city} is ${temp} and sunny.`);
  },
  required: ['city'],
});

await agent.serve();
```

> Register a SWAIG tool with a typed handler that receives named parameters.