> 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.

# tool / FunctionTool

> Factory function and interface for creating agent tools.

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

[runcontext]: /docs/server-sdks/reference/typescript/agents/livewire/run-context

## **tool**

```typescript {1}
function tool<P = any>(options: {
  description: string;
  parameters?: any;
  execute: (params: P, context: { ctx: RunContext }) => any;
}): FunctionTool
```

Creates a `FunctionTool` definition that can be passed into an `Agent`'s `tools` map.
The `tool()` function mirrors `llm.tool()` from `@livekit/agents-js`.

When the underlying SignalWire agent is built, each tool is registered as a SWAIG
function via [`defineTool()`][define-tool].

### Parameters

**`description`** `string` — required

A description of what the tool does. This is sent to the LLM so it knows when
to invoke the tool.

---

**`parameters`** `any`

JSON Schema describing the tool's parameters, or a Zod schema object. If omitted,
the tool accepts no parameters.

---

**`execute`** `(params: P, context: { ctx: RunContext }) => any` — required

The function to run when the tool is invoked. Receives the parsed parameters and
a context object containing the [`RunContext`][runcontext]. Can return a string,
an object (serialized to JSON), or a `FunctionResult`.

---

### Returns

[`FunctionTool`](#functiontool-interface) -- A tool definition object. The `name` field is empty and
gets filled in when the tool is assigned to a key in `Agent.tools`.

### Examples

#### Basic tool

```typescript {3}
import { tool } from '@signalwire/sdk/livewire';

const getWeather = tool({
  description: 'Get the current weather for a city.',
  parameters: {
    city: { type: 'string', description: 'The city name' },
  },
  execute: (params) => {
    return `It is sunny in ${params.city}.`;
  },
});
```

#### Tool with RunContext

```typescript {3}
import { tool, RunContext } from '@signalwire/sdk/livewire';

const savePreference = tool<{ key: string; value: string }>({
  description: 'Save a user preference.',
  parameters: {
    key: { type: 'string' },
    value: { type: 'string' },
  },
  execute: (params, { ctx }) => {
    const data = ctx.userData as Record<string, string>;
    data[params.key] = params.value;
    return `Saved ${params.key} = ${params.value}.`;
  },
});
```

#### Tool returning an object

```typescript {3}
import { tool } from '@signalwire/sdk/livewire';

const lookupOrder = tool<{ orderId: string }>({
  description: 'Look up an order by ID.',
  parameters: {
    orderId: { type: 'string', description: 'The order ID' },
  },
  execute: (params) => {
    return {
      orderId: params.orderId,
      status: 'shipped',
      estimatedDelivery: '2025-01-15',
    };
  },
});
```

---

## **FunctionTool Interface**

The `FunctionTool` interface represents a tool definition that can be registered on
an `Agent`.

```typescript {1}
interface FunctionTool {
  name: string;
  description: string;
  parameters?: Record<string, unknown>;
  execute: (params: any, context: { ctx: RunContext }) => any;
}
```

**`name`** `string`

The tool name. When created via `tool()`, this is initially empty and is set
automatically when the tool is added to an `Agent`'s `tools` map (the map key
becomes the name).

---

**`description`** `string`

A description of what the tool does.

---

**`parameters`** `Record<string, unknown> | undefined`

JSON Schema or Zod schema describing the tool's accepted parameters.

---

**`execute`** `(params: any, context: { ctx: RunContext }) => any`

The handler function invoked when the LLM calls this tool.

---

> Factory function and interface for creating agent tools.