---
title: "Review options"
description: "Configure tracked changes review behavior for Server AI Toolkit tool execution."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/review-options"
---

# Review options

Configure tracked changes review behavior for Server AI Toolkit tool execution.

The Server AI Toolkit `execute-tool` endpoint accepts a `reviewOptions` property. Use it to control how `tiptapEdit` writes reviewable changes instead of directly mutating the document.

```ts
import { getAuthHeaders } from '@/lib/server-ai-toolkit/get-auth-headers'

const response = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    editorContext,
    document,
    reviewOptions: {
      mode: 'trackedChanges',
    },
  }),
})
```

The `reviewOptions` property takes a `ReviewOptions` configuration object.

## `ReviewOptions`

- `mode?` (`'disabled' | 'trackedChanges'`): Controls whether edits are applied directly or written as tracked changes. Default: `'disabled'`
  - `'disabled'`: The edit is applied directly to the document.
  - `'trackedChanges'`: The edit is encoded as tracked changes using the [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) extension so users can accept or reject individual changes.
- `trackedChangesOptions?` (`{ userId: string, userMetadata?: Record<string, unknown> | null }`): Author metadata for the `trackedChanges` mode. `userId` identifies the suggestion author. Defaults to `'AI'` when omitted. `userMetadata` stores additional author information such as a display name. Defaults to `null`.
- `useDiffUtility?` (`boolean`): Whether to use the diff utility for tracked-changes reconstruction. When `true`, changes are computed via fine-grained diffing. When `false` or absent, range-level tracked changes are applied directly.
- `diffUtilityOptions?` (`object`): Advanced options for reconstructing tracked changes from the before/after document state.
  - `simplifyChanges?` (`boolean`, default: `true`): Simplify nearby changes before tracked changes are generated.
  - `ignoreAttributes?` (`string[]`, default: `['id', 'data-thread-id', '_hash']`): Ignore specific node attributes during diffing.
  - `ignoreMarks?` (`string[]`, default: `['inlineThread']`): Ignore specific marks during diffing.
  - `changeMergeDistance?` (`number | null`, default: auto-calculated): Merge nearby changes within this distance. Set to `null` to disable merging.
  - `mode?` (`'inline' | 'block' | 'smart'`, default: `'smart'`): Diff strategy to use when generating tracked changes.
  - `groupInlineChanges?` (`number`, default: `1`): Group inline edits that are within this distance.
  - `expandBlockChanges?` (`string[]`, default: `['listItem']`): Node types that should be expanded as block changes.

## Typical configurations

### Direct edits

Skip review mode and apply edits immediately:

```ts
reviewOptions: {
  mode: 'disabled',
}
```

### Tracked changes with AI author metadata

Attach a stable AI identity to the generated suggestions:

```ts
reviewOptions: {
  mode: 'trackedChanges',
  trackedChangesOptions: {
    userId: 'ai-assistant',
    userMetadata: {
      name: 'AI Assistant',
    },
  },
}
```

### Tracked changes with custom diff behavior

Tune how edits are grouped and displayed:

```ts
reviewOptions: {
  mode: 'trackedChanges',
  diffUtilityOptions: {
    mode: 'block',
    groupInlineChanges: 2,
  },
}
```