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
- An app connected to this workspace 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. - A sentence that says what to hand back — see handing work to an agent.
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.
Four of the ready-made 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
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.
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
for how the turn moves between you and the app, and
reviewing AI revisions for the panel's controls.
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
.docxas 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_proposalon something you have not reviewed yet.
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
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.
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
- Reading and reviewing with an agent — when the right answer is an opinion, not a rewrite.
- Revise a draft with your own AI agent — the same pass as a worked, seven-step workflow.