Writing Modes
The two ways an agent changes a document. Direct write lands the edit and records a version; suggest mode proposes a tracked change a person reviews.
When an agent changes a document, it picks one of two modes. The choice is about who approves the edit: the agent itself, or a person.
The agent writes the change, it lands, and a version is recorded. Use it when the agent should just write, for example a first draft or an internal document where no human gatekeeper is needed.
agentdock docs write abc123 draft.mdOver REST, that is a PATCH /api/d/{id} with the new markdown. Over MCP, it is write_document. Either way the content is replaced and a version is snapshotted.
The agent proposes a change instead of making it. The server computes the diff, and a person sees it as tracked changes to accept or reject. Use it when a human should approve agent edits before they land, for example anything client-facing.
agentdock docs suggest abc123 "data shows" "evidence demonstrates"The suggestion is a find-and-replace turned into a tracked change. It can be a replacement, an insertion, or a deletion, and it sits pending until someone resolves it. The document is unchanged until the suggestion is accepted. Over MCP, this is suggest_edits.
A reviewer (a person, or an agent with the right scope) works through the pending list:
# See what is waiting
agentdock docs suggestions abc123
# Apply a proposal
agentdock docs accept-suggestion abc123 <sid>
# Discard one without applying
agentdock docs reject-suggestion abc123 <sid>Accepting applies the change to the document and records a version. Rejecting discards it and leaves the document as it was. In the editor, pending suggestions show up as tracked changes inline, so a person can read each proposed edit in context before deciding.
Every write and every accepted suggestion creates a version. A version carries:
- its number and the time it was made,
- whether a human or an agent made it,
- and the model name when the edit was automated.
So months later you can open any document and read its whole history as a record of who wrote what, instead of a single blob with no trail. Read versions with agentdock docs versions <id> and agentdock docs version <id> <versionId>, or over MCP with list_versions and read_version.
Because every version is tagged, an automated draft and a human revision are never indistinguishable. When an agent and a person both touch a draft, you can always tell which version came from where, and which model produced an automated one. This is the difference between an audit trail and a guess.
| Use direct write when | Use suggest mode when |
|---|---|
| The agent should just write | A person should approve before it lands |
| Drafting or internal documents | Anything client-facing or published |
| Speed matters more than review | Review matters more than speed |
An agent can use both on the same document: write the draft directly, then propose later refinements as suggestions for a person to approve.
- REST API Reference: the suggestion routes
- MCP Server Setup: the suggestion tools
- Examples and Workflows: review in a real pipeline