# HostTool

A tool that the host defines and runs, offered to the model with a JSON Schema.

Each `HostTool` in `config.tools` becomes the SDK's `FunctionTool` with parallel calls. The model sees it directly and inside Code Mode, on both backends. `RuntimeOptions.tools.call` runs each call, and the SDK keeps the call's receipt like any other tool's.

```ts title="host.ts"
import type {
  AgentConfiguration,
  HostTool,
  RuntimeOptions,
} from 'nanocode-wasm'

// 1. Declare the tool with a JSON Schema for its input
const lookup: HostTool = {
  description: 'Look up the value stored under a key.',
  name: 'lookup',
  parameters: {
    properties: { key: { type: 'string' } },
    required: ['key'],
    type: 'object',
  },
}
const config: Pick<AgentConfiguration, 'tools'> = { tools: [lookup] }

// 2. Run its calls. The result becomes the tool output.
const tools: RuntimeOptions['tools'] = {
  call: async (name, input) => ({
    name,
    value: (input as { key: string }).key.toUpperCase(),
  }),
}
```

## Signature

```ts
type HostTool = {
  name: string
  description: string
  parameters: Record<string, unknown>
}
```

## Properties

### name

* **Type:** `string`

The tool name that the model calls and that `tools.call` receives.

```ts
// Called as lookup
const name = 'lookup'
```

### description

* **Type:** `string`

The description that the model reads to decide when to call the tool.

```ts
// States what the tool returns
const description = 'Look up the value stored under a key.'
```

### parameters

* **Type:** `Record<string, unknown>`

The JSON Schema of the tool's input.

```ts
// An object with one required string
const parameters = {
  properties: { key: { type: 'string' } },
  required: ['key'],
  type: 'object',
}
```

## options.tools.call

```ts
// Runs one host tool call
call(
  name: string,
  input: unknown,
  signal: AbortSignal,
): Promise<unknown>
```

The runtime calls `RuntimeOptions.tools.call` for each host tool call. `input` is the model's arguments, and `signal` aborts when the SDK cancels the call. The resolved value becomes the tool output, and `undefined` becomes `null`.

```ts
import type { RuntimeOptions } from 'nanocode-wasm'

// Passes the abort signal to the request
const tools: RuntimeOptions['tools'] = {
  call: (name, input, signal) =>
    fetch(`https://tools.example.com/${name}`, {
      body: JSON.stringify(input),
      method: 'POST',
      signal,
    }).then((response) => response.json()),
}
```

## Errors

A thrown error or rejected promise from `call` becomes a tool error that the model reads. If `config.tools` is set without `options.tools`, each call fails with `host tools are not configured`. If the SDK refuses the tool set, `open` throws a `HostFailure` of kind `configuration`.

```ts
import type { RuntimeOptions } from 'nanocode-wasm'

// The model reads this message as the tool error
const tools: RuntimeOptions['tools'] = {
  call: async (name) => {
    throw new Error(`${name} is not available`)
  },
}
```