# Revising documents with an external AI agent

URL: https://mindmax.me/docs/guides/revising-documents-with-an-agent/
Last verified: 2026-11-11

> How a connected AI app changes a draft in MindMax — whole rewrites, sections, single passages or review-only comments — and how you accept each group of edits.

## Revising documents with an external AI agent

A connected AI app can rewrite a sentence, a section or a whole draft — but a change to a document
you already wrote always comes back as a **proposal**, shown as tracked changes on your own text.
Nothing is written to the file until you accept it. New documents are created directly; edits to
existing ones wait for your review. That single rule is why you can let a capable model loose on a
report and still know exactly what changed.

## Before you start[​](https://mindmax.me/#before-you-start)

- An app [connected to this workspace](https://mindmax.me/docs/getting-started/connect-an-ai-agent/) with
**Collaborate** access. A read-only connection cannot propose a change.

- A draft you want changed, in a format that can be revised: Markdown or `.docx`. PDFs, ebooks and
slides are read-only here — see [what cannot be changed](https://mindmax.me/#what-cannot-be-changed).

- A sentence that says what to hand back — see [handing work to an agent](https://mindmax.me/docs/guides/handing-work-to-an-agent/).

## Four ways to ask for a change[​](https://mindmax.me/#four-ways-to-ask-for-a-change)

| You want | Say something like | What the app calls | What comes back |
| --- | --- | --- | --- |
| A whole new draft | "Rewrite the report I have open for a non-specialist reader, keep every number, and propose it as suggestions." | suggest_edits with whole-document newText | One proposal, split into groups |
| One section rewritten | "Rewrite section 3 so the conclusion is more cautious. Leave the rest alone." | suggest_edits with {section, newText} | Groups only inside that section |
| A few sentences replaced | "Replace the claim in the second paragraph with the one from my notes, and say why." | suggest_edits with {find, replace, near?} | A local replacement located in the current text |
| No changes at all | "Read this like an editor and leave the problems as comments. Don't change the text yet." | add_comments / reply_to_comment | Notes on the passages, each waiting for you |

Long documents are better handled section by section: one huge whole-document edit is harder to read
than six small ones. Each edit is located in the text that is on disk right now and reported as
found, not found, ambiguous or overlapping. If the file changed after the proposal was made,
[generate the revision again](https://mindmax.me/docs/troubleshooting/common-issues/).

Four of the [ready-made prompts](https://mindmax.me/docs/reference/agent-tools/#prompts) cover the same ground without
you writing the sentence: `proofread` sends fixes as suggestions, `writing-review` leaves editorial
comments, `resolve-comments` answers the threads waiting on a draft and proposes what they ask for,
and `verify-claims` checks assertions against your library and leaves the verdicts as comments.

## Reading the review card[​](https://mindmax.me/#reading-the-review-card)

Deletions are struck through and additions highlighted **on your own sentences**, not in a fresh
copy you have to compare line by line. Each group carries the reason it exists and, when there is
one, the comment it answers. You accept or reject a group as a whole — there is no per-word toggle;
if half a group is right, accept it and fix the rest by hand.

A review pass lands in the margin or the review card — on the passage, signed, and waiting for your decision.

`answering` is the small detail that keeps the conversation together. When a proposal names the
comment threads it answers, MindMax posts the reason into those threads as the app's reply — no
extra message needed — and resolves them when you accept the change. Rejecting leaves the thread
exactly as it was. See [working in the margin with an AI agent](https://mindmax.me/docs/guides/comments-with-an-agent/)
for how the turn moves between you and the app, and
[reviewing AI revisions](https://mindmax.me/docs/guides/reviewing-ai-revisions/) for the panel's controls.

## What cannot be changed[​](https://mindmax.me/#what-cannot-be-changed)

- **A PDF, an ebook or a PowerPoint file is not edited.** A PDF gets an editable Markdown copy with the
same name beside it, created only when you apply; the original stays where it is. On read-only
material the app answers in the comment thread or writes a new note.

- **An existing document is never overwritten or deleted**, at either access level. There is no
delete tool in the set.

- **A Word file gets real Word tracked changes.** Accepted edits go into the same `.docx` as
revisions you can open in Word; a Markdown note is edited in place.

- **A change is not applied for you.** Accepting is a separate action, and you can
`withdraw_proposal` on something you have not reviewed yet.

[Controlling agent access](https://mindmax.me/docs/guides/controlling-agent-access/) covers the paper trail: version
history names the app that wrote each version, so a bad pass can be compared and rolled back like
any other save.

## Common problems[​](https://mindmax.me/#common-problems)

**The app used its own file-writing tool and nothing appeared in the review card.** Some hosts try to
write directly to the workspace. On Claude-style hosts a write guard points them back to
`suggest_edits` and `create_document`. Ask for "propose the changes as suggestions in MindMax", or
check [common issues](https://mindmax.me/docs/troubleshooting/common-issues/).

**A comment stayed open after I accepted the edit.** Only the threads the proposal named in
`answering` are resolved. Others you close yourself by replying or marking them done.

**The anchor no longer matches.** You rewrote the sentence after leaving the comment. Reply with the
current wording, or comment again on the new sentence.

**It rewrote far more than I wanted.** Name the section, say what must not change, and put the
constraint in a comment on that passage — the comment stays with the text for the next pass.

## Next[​](https://mindmax.me/#next)

- [Reading and reviewing with an agent](https://mindmax.me/docs/guides/reading-and-reviewing-with-an-agent/) — when
the right answer is an opinion, not a rewrite.

- [Revise a draft with your own AI agent](https://mindmax.me/use-cases/revise-with-your-own-ai-agent/) — the same
pass as a worked, seven-step workflow.

Last updated on **Nov 11, 2026**