---
title: "Execute tool (AI agents)"
description: "Execute AI agent tool calls against a Tiptap editor using the AI Toolkit."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/execute-tool"
---

# Execute tool (AI agents)

Execute AI agent tool calls against a Tiptap editor using the AI Toolkit.

Use `executeTool` to apply a tool call from your AI agent to the editor.

Once you've added [tool definitions](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/tools.md) to your AI agent, the AI agent will generate tool calls. Use the `executeTool` method to apply the tool calls to the editor.

## `executeTool`

Executes a supported tool by name and input.

### Parameters (`ExecuteToolOptions`)

- `toolName` (`string`): Tool to execute. Can be one of the [available tools](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/tools.md).
- `input` (`unknown`): A JSON object that matches the input schema of the tool parameters. If no parameters are required for this tool, pass an empty object (`{}`).
- `chunkSize?` (`number`): The maximum size of a string that can be passed as input to the AI model. Prevents the AI from reading too much content at once so that the context window of the AI model is not exceeded. Default: `32000`. This parameter is used by reading tools to control how the document is split into chunks.
- `reviewOptions?` ([`ReviewOptions`](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/review-options.md)): Control preview/review behavior. [See available options](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/review-options.md).
- `commentsOptions?` (`CommentsOptions`): Options for comment and thread operations. This allows passing custom data to comment and thread creation/update operations. The `data` property is used for thread data, while `commentData` is used for comment data.
  - `threadData?` (`Record<string, any>`): Extra metadata for the AI-generated threads that are created with the `editThreads` tool
  - `commentData?` (`Record<string, any>`): Extra metadata for the AI-generated comments that are created with the `editThreads` tool
- `tiptapEditHooks?` (`TiptapEditHooks`): Hooks for intercepting and modifying Tiptap Edit operations. See the [Tiptap Edit hooks guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/advanced-guides/tiptap-edit-hooks.md) for details.
  - `beforeOperation?` (`(context: BeforeOperationContext) => BeforeOperationResult`): Called before each operation is applied. Return `{ action: 'accept' }` to apply the operation (optionally with `fragment` or `operationType` overrides), or `{ action: 'reject', error }` to skip it.

### Returns (`ExecuteToolResult`)

- `output` (`object`): Response object from the tool execution, to be read by the AI agent. The object structure varies depending on the tool executed.
- `hasError` (`boolean`): Whether there was an error during execution
- `unknownTool` (`boolean`): Whether the `toolName` is not recognized by the AI Toolkit
- `docChanged` (`boolean`): Whether the tool call modifies the document.

### Example

```ts
// Handle the tiptapRead tool call
const result = toolkit.executeTool({
  toolName: 'tiptapRead',
  input: {
    from: 0,
  },
})
```

For a complete hands-on tutorial, see the [AI agent chatbot guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/ai-agent-chatbot.md).

## `streamTool`

Updates the document in real-time while a tool call is streaming.

This method has the same effect as calling the `executeTool` method, but it edits the document incrementally while the tool call is streaming, instead of editing the document all at once when the tool call has finished streaming.

### Parameters (`StreamToolOptions`)

- `toolCallId` (`unknown`): The id of the tool call
- `toolName` (`string`): Tool to execute. Can be one of the [available tools](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/tools.md).
- `input` (`unknown`): A JSON object that matches the input schema of the tool parameters. If no parameters are required for this tool, pass an empty object (`{}`). If the tool has not finished streaming, this parameter should be a partial object with part of the parameters, but still a valid JSON object.
- `hasFinished?` (`boolean`): Whether the tool has finished streaming. Default: `false`
- `chunkSize?` (`number`): The maximum size of a string that can be passed as input to the AI model. Prevents the AI from reading too much content at once so that the context window of the AI model is not exceeded. Default: `32000`. This parameter is used by reading tools to control how the document is split into chunks.
- `reviewOptions?` ([`ReviewOptions`](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/review-options.md)): Control preview/review behavior. [See available options](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/review-options.md).
- `commentsOptions?` (`CommentsOptions`): Options for comment and thread operations. This allows passing custom data to comment and thread creation/update operations. The `data` property is used for thread data, while `commentData` is used for comment data.
  - `threadData?` (`Record<string, any>`): Extra metadata for the AI-generated threads that are created with the `editThreads` tool
  - `commentData?` (`Record<string, any>`): Extra metadata for the AI-generated comments that are created with the `editThreads` tool
- `tiptapEditHooks?` (`TiptapEditHooks`): Hooks for intercepting and modifying Tiptap Edit operations. See the [Tiptap Edit hooks guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/advanced-guides/tiptap-edit-hooks.md) for details.
  - `beforeOperation?` (`(context: BeforeOperationContext) => BeforeOperationResult`): Called before each operation is applied. Return `{ action: 'accept' }` to apply the operation (optionally with `fragment` or `operationType` overrides), or `{ action: 'reject', error }` to skip it.

### Returns (`StreamToolResult`)

- `output` (`object`): Response object from the tool execution, to be read by the AI agent. The object structure varies depending on the tool executed.
- `hasError` (`boolean`): Whether there was an error during execution
- `unknownTool` (`boolean`): Whether the `toolName` is not recognized by the AI Toolkit
- `docChanged` (`boolean`): Whether the tool call modifies the document.

### Example

The `streamTool` method is called repeatedly while the tool call is streaming. When the tool call has finished streaming, the `streamTool` method is called again with `hasFinished: true` to indicate that the tool call has finished streaming.

```ts
// Stream a tool call while it's being generated.
// Call `streamTool` again every time a new streaming part is received.
const result = toolkit.streamTool({
  // Tool is still streaming, so tool streaming has not finished yet
  hasFinished: false,
  toolCallId: 'call_123',
  toolName: 'tiptapEdit',
  // Content is still streaming, so we pass a partial object.
  input,
})

// When the tool call is complete, call it again with hasFinished: true
const finalResult = toolkit.streamTool({
  // Tool streaming has finished
  hasFinished: true,
  toolCallId: 'call_123',
  toolName: 'tiptapEdit',
  // Streaming is complete, so we can pass the full object
  input,
})
```

For a complete hands-on tutorial on streaming, see the [streaming guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/streaming.md).

## `getActiveSelection`

Returns the value of the `activeSelection` variable.

The active selection is the range that has been set by the AI Toolkit. When set, this range is used instead of the current editor selection in operations like `tiptapReadSelection`. The range is automatically mapped through transactions to maintain correct positions as the document changes.

### Returns

- `Range | null`: The active selection range with `from` and `to` properties, or `null` if no active selection is set.

### Example

```ts
const toolkit = getAiToolkit(editor)
const activeSelection = toolkit.getActiveSelection()
```

## `setActiveSelection`

Sets the `activeSelection` variable. This variable is used when executing tool calls with the `executeTool` or `streamTool` methods, to determine what range the AI will use instead of the current editor selection in operations like `tiptapReadSelection`.

The active selection is the range that the AI should use instead of the current editor selection. The range is automatically mapped through transactions to maintain correct positions as the document changes.

### Parameters

- `selection` (`Range | null`): The range to set, with `from` and `to` properties indicating the start and end positions, or `null` to clear the active selection.

### Example

```ts
const toolkit = getAiToolkit(editor)
// Set the active selection to the current selection
toolkit.setActiveSelection(editor.state.selection)

// Set the active selection to a specific range
toolkit.setActiveSelection({ from: 10, to: 50 })

// Clear the active selection
toolkit.setActiveSelection(null)
```