Governing AI Agents That Edit Word Documents

Letting an AI agent read a Word document is a retrieval problem. Letting it change one is a governance problem. Once an agent can rewrite a termination clause, insert a paragraph into a policy or alter a figure in a report, three questions follow:

• What exactly did it change?
• Who, or what, made each change?
• Did a person approve it before it became final?

If the answers are not in the document itself, the organisation is relying on trust where it needs evidence.

This article sets out practical controls for AI agents editing Word documents, using SuperDoc’s agent toolkit as a concrete example. SuperDoc describes itself as “an open source DOCX Editor and Agent SDK for adding DOCX editing into web apps and agents”. Its editor code is open source under AGPLv3, while its DOCX Engine is a separately licensed, proprietary component. Its documentation is unusually candid about where an agent’s actions can go wrong. The controls are not specific to SuperDoc, though. They apply to any system that lets a model modify business documents.

Facts about SuperDoc come from its own documentation, checked on 9 October 2026. SuperDoc ships releases frequently, so check the current documentation before you build. The governance recommendations are ours.

The Agent Surfaces

SuperDoc offers several ways for an agent to work on a document:

• Node.js and Python SDKs. “Use @superdoc/sdk for Node.js or superdoc-sdk for Python. Your application opens the document, sends requests to your model provider, runs the tools it selects, and decides when to save.” The Python SDK supports Python 3.9 and newer.
• An agent toolkit in the SDK, createAgentToolkit, which returns “tool definitions in your provider’s shape, the matching system prompt, and a dispatcher bound to the same surface”. Its provider option “accepts openai, anthropic, vercel, or generic”.
• An MCP server, @superdoc/mcp, for coding agents and desktop AI clients. It “needs Node.js 20 or newer”, and the client “talks to it over stdio”.

SuperDoc states that it is “model- and provider-independent and can be used with hosted or local models.” That matters for governance, because the controls below sit in the document layer, not in any particular model.

Control 1: Make Every Agent Edit a Tracked Change, and Fail Closed

The single most valuable control is that the agent proposes and a person decides. In a Word document, the natural form of a proposal is a tracked change.

The obvious approach is to tell the model to use tracked changes. SuperDoc’s safety guidance explains why that is not enough: the change-mode argument “is optional and defaults to a direct edit, so asking for tracked mode in the prompt is not enough.” A model that forgets the argument, or is persuaded to drop it, silently rewrites the document.

The toolkit’s answer is a policy rather than an instruction:

const { tools, systemPrompt, dispatch } = await createAgentToolkit({
  provider: 'openai',
  preset: 'core',
  enforceChangeMode: 'tracked',
  allowDirectActions: ['add_comments'],
});

SuperDoc’s documentation describes the behaviour: “enforceChangeMode: 'tracked' is fail-closed and applies to all three pieces at once”. Actions that cannot record a tracked change leave the tool list and the system prompt, and the dispatcher refuses them. “The model never learns the verb exists.” Every remaining action “runs tracked whatever the call said”. When a call is upgraded, “the receipt reports changeMode: 'tracked' with changeModeForced: true so your logs show the upgrade happened.”

allowDirectActions reopens specific direct-only actions that a workflow genuinely needs. SuperDoc’s example for a reviewer agent allows comment actions. Do not hardcode your own list of which actions are tracked and which are direct. SuperDoc’s guidance is to read the dispositions from getActionDispositions() “rather than hardcoding a list, so your configuration follows the registry when an action changes bucket.”

Be clear about what the policy does not do. SuperDoc says it “does not audit what the engine produced”, and “it does not link receipts to the tracked changes they created”. It guarantees the form of the edits, not their correctness.

Control 2: Give the Agent a Name

A tracked change records its author. If the agent has no identity, the record says very little.

SuperDoc’s documentation is direct: “Without a user, tracked changes are attributed to a generic CLI author shared by every unattributed workflow, and a reviewer cannot tell which automation proposed what.” The identity is set when you create the client:

const client = createSuperDocClient({ user: { name: 'Contract bot' } });

Our recommendation is one identity per deployment and purpose. Use names such as “Contract review agent (production)” or “Policy update agent”, so that a reviewer, an auditor, or you in six months’ time can tell which automation proposed which change. Do not reuse a person’s name for an agent.

Control 3: Treat Receipts as Claims, Not Proof

Every action returns a receipt with a status of ok, partial, failed or aborted. It is tempting to treat ok as done. SuperDoc warns against exactly that:

“Treat a successful receipt as a claim, not proof. An action whose target matched nothing still reports ok, so compare the receipt’s before and after revisions when you need to know a change actually landed.”

The receipt carries preSnapshot and postSnapshot revisions, and “Differing revisions are the evidence that the document changed.” SuperDoc’s own example loop checks them. In outline:

function changedTheDocument(receipt) {
  const before = receipt.preSnapshot?.revision;
  const after = receipt.postSnapshot?.revision;
  return before != null && after != null && before !== after;
}

The reverse also holds: “failed does not mean nothing happened.” An action can apply its change and then fail its own post-check, so “a failed receipt is not a safe retry”. Compare revisions before retrying, or the edit may be applied twice. SuperDoc’s safety guidance also rules out a simulation to fall back on: “no action simulates a mutation, and the surface refuses dryRun rather than accepting it and editing anyway.”

For workflows where completeness matters, SuperDoc’s advice is worth adopting wholesale: “decide the required edits before the run, give each one a stable id, and check them off as receipts arrive. Otherwise treat a clean run as a draft worth reviewing, not as proof the instruction was carried out.”

Control 4: Choose the Tool Surface Deliberately

SuperDoc offers presets that define which tools the model sees. The current recommendation is core, which “advertises two tools”: superdoc_inspect, for “Read-only snapshots of current document state”, and superdoc_perform_action, for “One named, statically validated edit verb from the action registry”.

The trap is the default. The older legacy preset “remains the default when preset is omitted, so code written before presets existed keeps working.” SuperDoc’s documentation warns that omitting the preset “selects the older legacy tool surface for backward compatibility, which advertises a different set of tools.” Always pass the preset explicitly.

Two further points from the documentation:

• You can narrow the surface. excludeActions removes actions from all three pieces at once. For example, excluding accept_tracked_changes and reject_tracked_changes stops the agent deciding its own proposals.
• Presets “are not versioned… Pin the SDK version if your integration needs the advertised surface to hold still.” For a governed workflow, it does.

Control 5: Treat Tool Calls as Untrusted Input

A document can contain instructions. An agent editing a contract sent by a counterparty is reading text that someone else wrote, and that text can try to steer the model. SuperDoc’s safety guidance addresses this directly:

“A model chooses tool names from what it was shown, but nothing guarantees it stays there. It can invent a name, and it can be persuaded toward one by text inside the document it is editing. … Validate the tool name against the list you advertised before dispatching, and reject anything else rather than passing it through.”

This is not theoretical. SuperDoc’s documentation notes that the dispatcher “accepts more tool names than the toolkit advertises”. With the core preset, it can route several unadvertised tools, and “They skip the tracked-mode check”. The application’s own allow list is therefore the real boundary:

const ADVERTISED_TOOLS = new Set(['superdoc_inspect', 'superdoc_perform_action']);

if (!ADVERTISED_TOOLS.has(call.function.name)) {
  // Reject the call and tell the model; never pass it to dispatch().
}

Control 6: An MCP Server Is Not a Sandbox

The MCP server is the quickest way to give a coding agent or desktop AI client the ability to edit Word documents. SuperDoc documents the configuration for clients such as Claude Desktop:

{
  "mcpServers": {
    "superdoc": {
      "command": "npx",
      "args": ["@superdoc/mcp"],
      "env": { "MCP_PRESET": "core" }
    }
  }
}

The documentation is equally clear about the risks. “The server can access files allowed by the account running it.” “superdoc_save overwrites an existing file without asking”. “A nonexistent input path opens a blank document”. Most importantly: “An instruction to the model does not enforce a filesystem boundary.”

SuperDoc’s recommendation is to “run the server under a dedicated user, in a container with only the working folder mounted, or in an OS sandbox.” Our view is that this should be the default for any MCP server that writes files, not just this one. Telling the model “only edit files in this folder” is a request, not a control.

Control 7: Bound the Loop and Protect the Original

• Cap turns. SuperDoc’s guidance is to “Cap turns explicitly”, and to bound retries after a stale-revision failure, re-querying before retrying. Its example loop stops after 16 turns. A model that keeps calling tools must still terminate.
• Never overwrite the source. “Save to a new path and keep the source until the result is verified.” In the SDK:

await doc.save({ out: 'contract.reviewed.docx' });
await doc.close({ discard: true });
await client.dispose();

• Leave force off. SuperDoc’s safety page advises: “Leave force off. Without it, the SDK’s save refuses a path that already exists”. Some of SuperDoc’s quick-start examples pass force: true for convenience. For a governed workflow, follow the safety page.
• Handle encrypted files. “Encrypted or password-protected documents fail at open, so handle that case explicitly rather than letting it surface as an unexplained crash mid-run.”

Control 8: Log Evidence, Not Content

SuperDoc’s logging guidance strikes the right balance: “Log operation ids, action names, receipt statuses, and error codes. Do not log document text, full mutation payloads, or complete receipts, and be deliberate about what reaches a model provider: content sent for a decision leaves your infrastructure.”

Combined with named authors and tracked changes, that gives two complementary records: what the agent did, in your logs, and what it proposed, in the document.

Keeping a Person in the Loop

SuperDoc’s guidance on human review is short: “Decide up front which operations an agent may complete alone. Excluding the review actions is a practical default: the agent proposes, a person decides.”

In practice, our recommended pattern for document agents is:

1. The agent works with enforceChangeMode: 'tracked', a named identity and the review actions excluded.
2. The output is saved as a new file, or into a review state in your application.
3. A named person reviews the tracked changes, in Word or in a browser editor, and accepts or rejects each one.
4. Only the reviewed document becomes the record.

Where This Meets AI Governance

This section is our analysis. An organisation using AI on its documents should be able to show where AI was involved and who took responsibility for the result. A document whose AI-proposed changes are tracked, attributed to a named agent and accepted by a named person carries that evidence with it. We set out the wider audit-trail approach in AI Document Review with an Audit Trail: Practical Guardrails for Compliance Teams.

The EU AI Act’s Article 50 transparency obligations have applied since 2 August 2026, with a grace period to 2 December 2026 for the Article 50(2) marking duty on systems placed on the market before 2 August 2026, and they include duties around AI-generated text. Whether and how they apply to a particular document workflow depends on your role and on exceptions in the text, which we cover in The EU AI Act After the AI Omnibus: The Timeline That Now Applies. Our view is that the controls above, especially attribution and human review, are good practice whatever your obligations turn out to be.

A Checklist

1. Force tracked changes with a fail-closed policy, not a prompt.
2. Give every agent deployment its own named identity.
3. Verify changes by revision, not by receipt status. Plan required edits up front when completeness matters.
4. Pass the core preset explicitly and pin the SDK version.
5. Validate tool names against an allow list before dispatch.
6. Sandbox MCP servers at the operating-system level.
7. Cap turns, save to a new path, and leave force off.
8. Log ids and statuses, not document content.
9. Exclude review actions, so that a person decides.

How McKenna Consultants Can Help

McKenna Consultants builds AI features over business documents through our AI First practice, and embedded document editing through our systems integration and Microsoft document integration work. We can design governed document-agent workflows on SuperDoc, Microsoft 365 or both, implement the controls above, and build the review and audit trail your compliance team will ask for.

Contact us to discuss AI agents that work on your documents.

Sources

All sources checked on 9 October 2026.

• SuperDoc — llms.txt: product description.
• SuperDoc documentation — SuperDoc DOCX Engine licence: the DOCX Engine is proprietary and separately licensed from the AGPLv3 editor code.
• SuperDoc — superdoc.dev FAQ: “model- and provider-independent”.
• SuperDoc documentation — Agents overview: Node.js and Python SDKs; the application’s role.
• SuperDoc documentation — Build an agent: createAgentToolkit; providers; enforceChangeMode; allowDirectActions; author attribution; receipts; unadvertised tools; example loop.
• SuperDoc documentation — Core action reference: receipt preSnapshot and postSnapshot revisions as evidence of change.
• SuperDoc documentation — Tools: core and legacy presets; default preset; excludeActions.
• SuperDoc documentation — Legacy tools: presets are not versioned; pin the SDK version.
• SuperDoc documentation — Safety: receipts as claims; no dry run; untrusted tool calls; turn caps; saving; force; encrypted files; logging; human review.
• SuperDoc documentation — Connect the MCP server: package; Node.js 20; stdio; client configuration; filesystem access and sandboxing.
• SuperDoc documentation — Python SDK: Python 3.9 and newer.
• European Commission — Transparency obligations under Article 50 of the AI Act: “Article 50 of the AI Act applies as from 2 August 2026”; Article 50(2) marking grace period to 2 December 2026 for systems placed on the market before 2 August 2026.
• AI Act Service Desk — Article 50: Transparency obligations for providers and deployers of certain AI systems: marking of synthetic text content (Article 50(2)) and disclosure of AI-generated text published to inform the public (Article 50(4)).