---
title: "Available tools"
description: "Complete list of available tools that allow AI agents to read and edit Tiptap documents on the server."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/tools"
---

# Available tools

Complete list of available tools that allow AI agents to read and edit Tiptap documents on the server.

The Server AI Toolkit exposes tool definitions through `POST /v3/ai/toolkit/tools` and executes
tool calls through `POST /v3/ai/toolkit/execute-tool`.

See the [REST API reference](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api.md) for
the endpoint definitions.

> **Note:**
>
> Currently, the Server AI Toolkit API returns the tool definitions in a generic format. Convert
> them to the format required by your provider or framework (OpenAI, Anthropic, Langchain).

Each call to `POST /v3/ai/toolkit/execute-tool` requires these parameters:

- `input` (required): Tool input generated by the AI model.
- `toolConfig?` (optional): Tool-specific parameters provided by the developer.

And the response contains these fields:

- `output` (`unknown`): Tool response that should be read by the AI model.
- `toolResult` (`unknown`, optional): Tool response in a format that is designed to be parsed by
  the developer. Not intended to be read by the AI.

Below is a list of the available tools.

## `tiptapRead`

Reads a slice of top-level document nodes. **It also edits the document** to prepare it for efficient edits.

### Tool config (`toolConfig`)

`null`

### Tool input (`toolInput`)

- `from` (`number`): Zero-based index of the first top-level node to read.

### Tool output (`toolOutput`)

Success response:

- `success` (`true`): Indicates that the read request was successful.
- `totalNodeCount` (`number`): Total number of top-level nodes in the document.
- `nodeRange` (`[number, number]`): Top-level node range that was read.
- `content` (`JSONContent[] | string`): Document content for the returned range. When `format` is
  `json`, this is a Tiptap JSON fragment. When `format` is `shorthand`, this is a Tiptap Shorthand
  string.

Error response:

- `success` (`false`): Indicates that the read request failed.
- `error` (`string`): Error message.
- `totalNodeCount?` (`number`): Total number of top-level nodes.

### Tool result (`toolResult`)

`null`

## `tiptapEdit`

Edits document nodes by replacing a target, inserting before a target, or inserting after a target.
Targets are node hashes from `tiptapRead`, or `"doc"` for the whole document.

### Tool config (`toolConfig`)

`null`

### Tool input (`toolInput`)

- `operations` (`array`): Edit operations applied sequentially. The format of the operations is described in the tool definition. If you are a customer, contact us for more information on the operation format.

### Tool output (`toolOutput`)

Success or partial-success response:

- `success` (`boolean`): Whether all operations completed successfully.
- `operationResults` (`array`): Result for each operation.
  - `success` (`boolean`): Whether the operation completed successfully.
  - `target` (`string`): String identifier of the element targeted by the operation.
  - `error` (`string | null`): Failure reason, or `null` if the operation succeeded.

Error response:

- `success` (`false`): Indicates that the edit request failed.
- `reason` (`'validationError' | 'unexpectedError'`): Error category.
- `error` (`string`): Error message.

### Tool result (`toolResult`)

`null`

## `getThreads`

Reads persisted comment threads, their comments, and their document locations.

> **Requires a Tiptap Cloud document:**
>
> This tool requires `experimental_documentOptions` in the request body because threads are stored
> on the Tiptap Document Server. Pass a `documentId` referencing your Tiptap Cloud document.

### Tool config (`toolConfig`)

`null`

### Tool input (`toolInput`)

- `from` (`number`): Zero-based index of the first thread to read.

### Tool output (`toolOutput`)

Success response:

- `success` (`true`): Indicates that the read request was successful.
- `totalThreadCount` (`number`): Total number of threads in the document.
- `threadRange` (`[number, number]`): Thread range that was read, as `[from, to)`.
- `threads` (`array`): Returned thread objects.
  - `id` (`string`): Unique thread identifier.
  - `nodeRange` (`[number, number] | null`): Node range where the thread is located, or `null` if
    the thread is not annotated in the document.
  - `content` (`JSONContent[] | string | null`): Content marked by the thread. When `format` is
    `json`, this is a Tiptap JSON fragment. When `format` is `shorthand`, this is a Tiptap
    Shorthand string. `null` means the thread is not annotated in the document.
  - `comments` (`array`): Comments in the thread.
    - `id` (`string`): Unique comment identifier.
    - `content` (`string`): Comment text.
    - `userId` (`string`): ID of the user who created the comment.
    - `createdAt` (`string`): ISO timestamp when the comment was created.
    - `updatedAt` (`string`): ISO timestamp when the comment was last updated.
  - `resolvedAt?` (`string | null`): ISO timestamp when the thread was resolved, or `null` if
    unresolved.
  - `createdAt` (`string`): ISO timestamp when the thread was created.
  - `updatedAt` (`string`): ISO timestamp when the thread was last updated.
  - `data?` (`Record<string, unknown>`): Public thread metadata.

Error response:

- `success` (`false`): Indicates that the read request failed.
- `error` (`string`): Error message.
- `totalThreadCount?` (`number`): Total number of persisted threads, when known.

### Tool result (`toolResult`)

`null`

## `editThreads`

Creates, updates, removes, resolves, or unresolves comment threads and comments.

> **Requires a Tiptap Cloud document:**
>
> This tool requires `experimental_documentOptions` in the request body because threads are stored
> on the Tiptap Document Server. Pass a `documentId` referencing your Tiptap Cloud document.

### Tool config (`toolConfig`)

`null`

To attach metadata to new AI-generated threads or comments, pass `experimental_commentsOptions` on
the `execute-tool` request.

### Tool input (`toolInput`)

- `operations` (`array`): Thread operations applied sequentially. The format of the operations is described in the tool definition. If you are a customer, contact us for more information on the operation format.

### Tool output (`toolOutput`)

Success or partial-success response:

- `success` (`boolean`): Indicates whether all operations completed successfully.
- `operations` (`array`): Result for each operation.
  - `type` (`string`): Operation type that was executed.
  - `success` (`boolean`): Whether the operation completed successfully.
  - `message` (`string`): Human-readable operation result.
  - `threadId?` (`string`): Thread ID for operations that create or reference a thread.

Error response:

- `success` (`false`): Indicates that the request failed before operations were processed.
- `error` (`string`): Error message.

### Tool result (`toolResult`)

`null`

## `readDocument`

Reads the content of the entire document.

### Tool config (`toolConfig`)

`null`

### Tool input (`toolInput`)

`{}`

### Tool output (`toolOutput`)

Success response:

- `success` (`true`): Indicates that the document was read successfully.
- `content` (`JSONContent[] | string`): Whole effective document content. When `format` is `json`,
  this is a Tiptap JSON fragment. When `format` is `shorthand`, this is a Tiptap Shorthand string.

> **Returns entire document:**
>
> The tool output contains the content of the entire document, which might overflow the context
> window. To avoid it, you must manage the context window yourself.

### Tool result (`toolResult`)

Same shape as `toolOutput`.

## `proofreader`

Applies small edits to the document. Optimized for use cases where the AI makes small edits of one or few words. For example, proofreading the document or checking for spelling mistakes.

This tool only supports `format: "shorthand"`.

### Tool config (`toolConfig`)

`null`

### Tool input (`toolInput`)

- `operations` (`array`): Proofreader operations applied sequentially. The format of the operations is described in the tool definition. If you are a customer, contact us for more information on the operation format.

### Tool output (`toolOutput`)

Success or partial-success response:

- `success` (`boolean`): Indicates whether all operations completed successfully.
- `operationResults` (`array`): Result for each operation.
  - `target` (`string`): String identifier of the element targeted by the operation.
  - `success` (`boolean`): Whether the operation completed successfully.
  - `error` (`string | null`): Failure reason, or `null` when the operation succeeded.

### Tool result (`toolResult`)

`null`