# Tools

> Reference for defineTool, httpTool, tool and the options a tool takes.

Source: https://docs.vlayers.ai/developers/sdks/reference/tools

Kind: Reference

A tool is a function the model can call. `defineTool` runs your code in your worker, `httpTool` declares an endpoint the platform calls, and `tool` accepts the AI SDK's shape. Put the result in `tools`.

Import from `@voicelayer/sdk`.

### defineTool

function · `import { defineTool } from '@voicelayer/sdk'`

```ts
defineTool<S extends ToolInputShape>(spec: { name, description, input, run, capability?, sendRealValues?, timeoutMs?, idempotent?, sequential? }): Record<string, ToolDefinition<S>>
```

Define a tool whose code runs in your worker. It returns `{ [name]: tool }`, so spread it into `tools`. The model sees `description` and `input`; `run` is your handler.

##### Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `spec` | `object` | yes |  | The tool's name, description, input and `run` function, plus optional settings. |
| `spec.name` | `string` | yes |  | The tool's name, used as its key in `tools` and shown to the model. |
| `spec.description` | `string` | yes |  | What the tool does and when to use it. The model reads this to decide whether to call it. |
| `spec.input` | `S` | yes |  | The arguments the model passes: an object of field names to `'string'`, `'number'` or `'boolean'`, or a zod schema. |
| `spec.run` | `(input: InferToolInput<S>, ctx: HandlerContext) => unknown \| Promise<unknown>` | yes |  | Your function, called with the validated input and the handler context. What it returns goes back to the model; a thrown error's message goes back too, so throw messages that are safe to say aloud. |
| `spec.capability` | `string` | no | `'tool.<name>'` | The capability the action checks require. |
| `spec.sendRealValues` | `boolean` | no | `false` | Give `run` the caller's real values instead of placeholders; each release is recorded. |
| `spec.timeoutMs` | `number` | no | `10000` | How long `run` may take, between 100 ms and 30 s. |
| `spec.idempotent` | `boolean` | no | `false` | Mark the tool safe to repeat: after a lost or late reply the platform may run it once more. |
| `spec.sequential` | `boolean` | no | `false` | Run this tool after the rest of a parallel batch of tool calls has finished. |

##### Returns

`Record<string, ToolDefinition<S>>`: An object keyed by the tool's name.

##### Example

```ts
tools: {
  ...defineTool({
    name: 'lookup_order',
    description: 'Find an order by its number.',
    input: { orderId: 'string' },
    run: async ({ orderId }, ctx) => {
      await ctx.say('One moment.');
      return { orderId, status: 'shipped' };
    },
  }),
}
```

### httpTool

function · `import { httpTool } from '@voicelayer/sdk'`

```ts
httpTool(spec: { name, description, input, url, method?, headers?, capability?, sendRealValues?, timeoutMs?, idempotent? }): Record<string, HttpToolDeclaration>
```

Declare a tool that calls an HTTP endpoint fixed in the agent's definition. It is a declaration, not code: the platform makes the request. A `{field}` in the URL fills from the model's arguments. Headers are fixed text, and one that looks like a credential is refused at upload, so keep secrets in a vault connection. For a request body built by a function, write a `defineTool` that calls your endpoint instead.

##### Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `spec` | `object` | yes |  | The tool's name, description, input, URL and optional method, headers and settings. |
| `spec.name` | `string` | yes |  | The tool's name, used as its key in `tools` and shown to the model. |
| `spec.description` | `string` | yes |  | What the tool does and when to use it. |
| `spec.input` | `ToolInputShape` | yes |  | The arguments the model passes. |
| `spec.url` | `string` | yes |  | The endpoint to call. A `{field}` in the URL fills from the model's arguments. |
| `spec.method` | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'` | no | `'POST'` | The HTTP method. |
| `spec.headers` | `Readonly<Record<string, string>>` | no |  | Fixed headers. One that looks like a credential is refused at upload. |
| `spec.capability` | `string` | no | `'tool.<name>'` | The capability the action checks require. |
| `spec.sendRealValues` | `boolean` | no | `false` | Send the caller's real values instead of placeholders; each release is recorded. |
| `spec.timeoutMs` | `number` | no |  | How long to wait for the endpoint, in milliseconds. |
| `spec.idempotent` | `boolean` | no | `false` | Mark the call safe to repeat after a lost or late reply. |

##### Returns

`Record<string, HttpToolDeclaration>`: An object keyed by the tool's name, to spread into `tools`.

##### Throws

- TypeError when `spec.body` is a function or `spec.allowPrivateNetwork` is set; neither is supported.

##### Example

```ts
tools: {
  ...httpTool({
    name: 'get_status',
    description: 'Look up an order status.',
    input: { orderId: 'string' },
    url: 'https://api.acme.com/orders/{orderId}/status',
    method: 'GET',
  }),
}
```

### tool

function · `import { tool } from '@voicelayer/sdk'`

```ts
tool<S extends { readonly _output: unknown; }>(spec: ToolSpec<S>): AiSdkTool<InputOf<S>>
tool<S extends JsonSchemaOf>(spec: ToolSpec<S>): AiSdkTool<InputOf<S>>
```

A tool in the AI SDK's shape, for an author who does not install `ai`: an identity function typed from the schema. A tool made by `ai`'s own `tool()` is accepted in its place. `inputSchema` is a zod schema or the AI SDK's `jsonSchema<T>(...)`.

##### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `spec` | `ToolSpec<S>` | yes | The tool's description, input schema and `execute` function. |
| `spec.description` | `string` | yes | What the tool does and when to use it. |
| `spec.inputSchema` | `S` | yes | A zod schema or `jsonSchema(...)` wrapper describing the arguments. |
| `spec.execute` | `(input: InputOf<S>, options: AiSdkToolOptions) => unknown` | yes | Your function, called with the validated input and AI SDK options whose `experimental_context` is the handler context. |
| `spec.needsApproval` | `boolean \| ((input: InputOf<S>, options: AiSdkToolOptions) => boolean \| PromiseLike<boolean>)` | no | Ask the person before running: true, or a function that decides per call (read as "always ask"). |
| `spec.approval` | `boolean` | no | The same switch, under the name some AI SDK versions give it. |

##### Returns

`AiSdkTool<InputOf<S>>`: The same tool, typed.

##### Example

```ts
import { tool } from '@voicelayer/sdk';
import { z } from 'zod';

const lookup = tool({
  description: 'Find an order by its number.',
  inputSchema: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => ({ orderId, status: 'shipped' }),
});
```

### ToolDefinition

interface · `import { ToolDefinition } from '@voicelayer/sdk'`

```ts
interface ToolDefinition<S extends ToolInputShape = ToolInputShape>
```

A tool the model can call, whose code runs in your worker. Put it in `tools` by name, or build it with `defineTool`.

#### Fields

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `description` | `string` | yes |  | What the tool does and when to use it. The model reads this to decide whether to call it. |
| `input` | `S` | yes |  | The arguments the model passes, as a shorthand object or a zod schema. |
| `run` | `(input: InferToolInput<S>, ctx: HandlerContext) => unknown \| Promise<unknown>` | yes |  | Your function. The platform calls it after the action checks pass, within `timeoutMs`, and what it returns goes back to the model. A thrown error's message goes back too, as a failed tool result the model can apologise for, so throw messages that are safe to say aloud; the stack never leaves your worker. |
| `capability` | `string` | no | `'tool.<name>'` | The capability the action checks require. |
| `sendRealValues` | `boolean` | no | `false` | Give this handler the caller's real values instead of placeholders; each release is recorded. |
| `timeoutMs` | `number` | no | `10000` | How long `run` may take, between 100 ms and 30 s. |
| `idempotent` | `boolean` | no | `false` | Mark the tool safe to repeat: after a lost or late reply the platform may run it once more on another session. |
| `sequential` | `boolean` | no | `false` | Run this tool after the rest of a parallel batch of tool calls has finished. |
| `personApproves` | `PersonApprovesDeclaration` | no |  | Ask a person on the team before this runs, on every transport. See `PersonApprovesDeclaration`. |

### HttpToolDeclaration

interface · `import { HttpToolDeclaration } from '@voicelayer/sdk'`

```ts
interface HttpToolDeclaration
```

A tool that calls an HTTP endpoint fixed in the agent's definition. Build one with `httpTool`.

#### Fields

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | `string` | yes |  | The tool's name. |
| `description` | `string` | yes |  | What the tool does and when to use it. |
| `input` | `ToolInputShape` | yes |  | The arguments the model passes. |
| `url` | `string` | yes |  | The endpoint to call. A `{field}` in the URL fills from the model's arguments. |
| `method` | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'` | yes |  | The HTTP method. |
| `headers` | `Readonly<Record<string, string>>` | no |  | Fixed headers. A header that looks like a credential is refused at upload; use a vault connection. |
| `capability` | `string` | no | `'tool.<name>'` | The capability the action checks require. |
| `sendRealValues` | `boolean` | no | `false` | Send the caller's real values instead of placeholders; each release is recorded. |
| `timeoutMs` | `number` | no |  | How long to wait for the endpoint, in milliseconds. |
| `idempotent` | `boolean` | no | `false` | Mark the call safe to repeat after a lost or late reply. |

### ToolEntry

type · `import { ToolEntry } from '@voicelayer/sdk'`

```ts
type ToolEntry = ToolDefinition<ToolInputShape> | HttpToolDeclaration | AiSdkTool<never>
```

A tool the model can call: a `ToolDefinition`, an `httpTool` declaration, or a tool in the AI SDK's shape such as `tool({ inputSchema, execute })`.

### ToolInputShape

type · `import { ToolInputShape } from '@voicelayer/sdk'`

```ts
type ToolInputShape = Readonly<Record<string, ShorthandPrimitive>> | z.ZodTypeAny
```

A tool's input: either an object of field names to `'string'`, `'number'` or `'boolean'` (for example `{ reason: 'string' }`), or a zod schema. The runner validates the model's arguments against it before `run` and turns it into the JSON Schema the model sees.
