# registerTool()

Register a model-callable tool implemented by a sandbox extension.

```js
pi.registerTool({
  name,
  label,
  description,
  parameters,
  execute,
});
```

## Definition

| Field         | Type           | Requirement                                    |
| ------------- | -------------- | ---------------------------------------------- |
| `name`        | string         | Required; matches `[a-zA-Z0-9_-]{1,64}`        |
| `label`       | string         | Optional display label                         |
| `description` | string         | Required and non-empty                         |
| `parameters`  | object         | Required JSON-Schema-like parameter definition |
| `execute`     | async function | Required at hosted execution time              |

Manifest discovery records `name`, `label`, `description`, and `parameters`. The function body executes only in the hosted extension host.

## Execute signature

```js
async execute(toolCallId, params, signal, onUpdate, ctx) {
  return {
    content: [{ type: 'text', text: 'result' }],
    details: { optional: 'metadata' },
  };
}
```

`signal` and `onUpdate` are reserved arguments and may currently be undefined. `ctx.external` contains bounded integration metadata or `null`.

## Limits

* Up to 64 extension entrypoints per manifest.
* Up to 256 declared tools per extension.
* Tool names must be unique in the compiled tool surface.
* Tool execution has a 60-second hosted timeout.

See [tool result format](/docs/reference/extensions/tool-results) and the [custom tool tutorial](/docs/agent-development/custom-tools).