---
title: "Suggestions with comments"
description: "Show AI-generated justifications for each change using floating tooltips."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/review-changes/suggestions-with-comments"
---

# Suggestions with comments

Show AI-generated justifications for each change using floating tooltips.

> **Continuation from the suggestions guide:**
>
> This guide continues the [suggestions
> guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/review-changes/suggestions.md). Read it first.

The AI Toolkit can instruct the AI to include justifications for each change it makes to the document. This allows you to show users *why* a change was made, not just *what* changed.

> **Interactive demo:** [justified changes](https://ai-toolkit-demos.vercel.app/justified-changes)

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

## Enable justified changes

To enable justified changes, pass the `operationMeta` option to `toolDefinitions()` on the server. The string you provide becomes the description of the `meta` field in the tool schema, which the AI uses to understand what kind of justification to provide.

```ts
// api/route.ts
const agent = new ToolLoopAgent({
  model,
  instructions: '...',
  tools: toolDefinitions({
    operationMeta: 'Brief explanation of why this change improves the text',
  }),
})
```

## Show justifications as tooltips

When a suggestion is selected, you can display the justification as a tooltip using the [Floating UI](https://floating-ui.com/) library.

### Install Floating UI

```bash
npm install @floating-ui/dom
```

### Access the justification in `renderDecorations`

The justification is available in `suggestion.metadata?.operationMeta`. Use the `isSelected` option to only show the tooltip when the suggestion is focused.

```tsx
import { computePosition, flip, offset, shift } from '@floating-ui/dom'

const result = toolkit.executeTool({
  toolName,
  input,
  reviewOptions: {
    mode: 'preview',
    displayOptions: {
      renderDecorations(options) {
        const decorations = [...options.defaultRenderDecorations()]

        // Add Accept and Reject buttons (same as the suggestions guide)
        // ...

        // Show tooltip when selected and justification exists
        const justification = options.suggestion.metadata?.operationMeta
        if (options.isSelected && justification) {
          decorations.push(
            Decoration.widget(options.range.to, () => {
              const container = document.createElement('span')
              container.style.position = 'relative'

              const tooltip = document.createElement('div')
              tooltip.textContent = justification as string
              tooltip.style.cssText =
                'position:absolute;background:white;color:#1f2937;padding:8px 12px;border-radius:8px;border:1px solid #e5e7eb;font-size:13px;max-width:400px;width:max-content;z-index:50;pointer-events:none;box-shadow:0 4px 12px rgba(0,0,0,0.08),0 1px 3px rgba(0,0,0,0.06);'
              container.appendChild(tooltip)

              requestAnimationFrame(() => {
                computePosition(container, tooltip, {
                  placement: 'top',
                  middleware: [offset(8), flip(), shift({ padding: 8 })],
                }).then(({ x, y }) => {
                  tooltip.style.left = `${x}px`
                  tooltip.style.top = `${y}px`
                })
              })

              return container
            }),
          )
        }

        return decorations
      },
    },
  },
})
```

## End result

With these changes, AI-generated suggestions include floating tooltips that explain the rationale behind each change:

> **Interactive demo:** [justified changes](https://ai-toolkit-demos.vercel.app/justified-changes)

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