---
title: "Selection awareness"
description: "Let the server-side AI read and edit a collaborator's live selection."
canonical_url: "https://tiptap.dev/docs/ai/ai-toolkit/agents/selection-awareness"
---

# Selection awareness

Let the server-side AI read and edit a collaborator's live selection.

Make AI aware of the user's selected content, so it can edit it.

> **Continuation from the AI agent chatbot guide:**
>
> This guide continues the [AI agent chatbot guide](https://tiptap.dev/docs/ai/ai-toolkit/agents/ai-agent-chatbot.md). Read it
> first.

> **Interactive demo:** [server read selection](https://ai-toolkit-demos.vercel.app/server-read-selection)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

## The `readSelection` tool

With the `readSelection` tool, the AI can read the user's selection. This tool only works with Tiptap Cloud collaborative documents.

Enable it in the `fetch-tools` request alongside the other tools:

```ts
const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/fetch-tools`, {
  method: 'POST',
  headers: await getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    tools: {
      readSelection: true,
      // Other tools
      tiptapRead: true,
      tiptapEdit: true,
    },
  }),
})
```

The `readSelection` tool reads the selection of a single user. This is usually the user who prompts the AI. Pass the user ID as the `tool.config.user` parameter when the tool is executed. The developer passes this parameter, so the AI does not generate it.

```ts
const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/execute-tool`, {
  method: 'POST',
  headers: await getAuthHeaders(documentId),
  body: JSON.stringify({
    editorContext,
    document: { type: 'cloud', id: documentId },
    tool: {
      name: 'readSelection',
      // The AI calls the readSelection tool with no input parameters
      input: {},
      // The user's ID is passed by the developer
      config: { user: 'user-1' },
    },
  }),
})
```

See the [REST API reference](https://tiptap.dev/docs/ai/ai-toolkit/api-reference/rest-api.md#readselection) for more details about the tool.

## Publish the selection to awareness

The server reads the selection from live collaboration awareness data. To make this data available, configure
the [`CollaborationCaret` extension](https://tiptap.dev/docs/editor/extensions/functionality/collaboration-caret.md) and give the user an `id` that matches the `tool.config.user` you
send to the server. Create the editor once the provider is connected so the caret can attach.

```tsx
import { CollaborationCaret } from '@tiptap/extension-collaboration-caret'

const editor = useEditor({
  extensions: [
    StarterKit,
    Collaboration.configure({ document: doc }),
    CollaborationCaret.configure({
      provider,
      // The id is what readSelection matches against on the server.
      user: { id: 'user-1', name: 'You', color: '#6a00f5' },
    }),
    ServerAiToolkit,
  ],
})
```

## Preserving the selection

The server reads the selection from awareness at the moment the tool runs. `CollaborationCaret`
clears the awareness selection when the editor loses focus, so if the user clicks into a chat input
before sending, the server reads an empty selection.

Re-focus the editor when the user sends a message so `CollaborationCaret` re-publishes the current selection:

```tsx
const handleSubmit = () => {
  if (!input.trim()) return
  // Re-publish the selection to awareness: moving to the chat input blurred the
  // editor and cleared the awareness cursor.
  editor.commands.focus()
  sendMessage({ text: input })
  setInput('')
}
```

## End result

With additional CSS styles, the result is a chatbot that can edit the user's selection:

> **Interactive demo:** [server read selection](https://ai-toolkit-demos.vercel.app/server-read-selection)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

## Limitations

### Only works with Tiptap Cloud documents on the `default` field

The `readSelection` tool reads the selection state from the live updates sent by the `CollaborationCaret` extension. Therefore, it only works with Tiptap Cloud collaborative documents and is not compatible with documents provided inline.

An advanced option of collaborative documents is to store [multiple fields](https://tiptap.dev/docs/editor/extensions/functionality/collaboration.md#field). Currently, the `readSelection` tool only supports the `default` field. If you have a use case that involves multiple fields, [contact us](mailto:humans@tiptap.dev).

### AI model behavior

`readSelection` tells AI what content is selected, but it does not force it to edit only the
selection. Smaller, less capable AI models may rewrite the surrounding paragraph instead of
just the selected span, especially for a sub-sentence selection.

In our testing, models with reasoning enabled (for example, `gpt-5.4-mini` with reasoning effort set
to `low`) keep their edits scoped to the selection more reliably. A clear instruction such as "edit
only the selected text" also helps.

## Next steps

- Read the [`readSelection` REST API reference](https://tiptap.dev/docs/ai/ai-toolkit/api-reference/rest-api.md#readselection)
- Add more capabilities to your agent by following the guides in the [Agents section](https://tiptap.dev/docs/ai/ai-toolkit/agents.md)