Word

View as Markdown

Exposes a docx round-trip over the Microsoft Graph drive content API as agent tools: read text, create a document from paragraphs, append text, find/replace text, and export to PDF. Operates on .docx files in the acting user's OneDrive, editing them in-process with python-docx.

What it does

An agent-invocable tool node — no data flows through lanes. Each operation is a @tool_function an agent calls on demand. Operational targets (file path/id, new-document destination path) are always tool-call parameters, never node config. Outputs are cleaned shapes (id, name, webUrl, text), not raw Graph JSON and never the raw docx/PDF bytes.

There is no persisted Word Online editing session. Every write downloads the current .docx (GET metadata for the eTag, then GET .../content), edits it in-process, and re-uploads the whole file (PUT .../content) with an If-Match header carrying that eTag — Graph rejects the write with 409/412 if the file changed in between, which surfaces as a GraphError naming the conflict rather than silently last-writer-wins overwriting someone else's edit. On a conflict, re-read with word_read_text and retry.

Configuration

Field	Notes
`microsoft.authType`	`service` (Entra app, client credentials) or `user` (OAuth).
`microsoft.tenantId` / `microsoft.clientId` / `microsoft.clientSecret`	Entra app credentials for `service` auth.
`microsoft.userPrincipalName`	Acting user's UPN for `service` auth (app-only calls target `/users/{upn}`).
`microsoft.oAuthButton` / `microsoft.userToken`	User OAuth: sign in to populate the access token.
`word.access`	`readonly` or `write` (default). Resolved by the shared `WORD` spec in `core/microsoft_access.py`; scopes are never hand-entered.

Access tiers → scopes

Tier	Scope	Capability
`readonly`	`Files.Read`	read document text only
`write`	`Files.ReadWrite`	full read/write (default)

There are no destructive gate flags.

Tools

Read: word_read_text — every body paragraph plus every table cell's text, newline-joined.
Write: word_create_document (new .docx from a paragraph list, no If-Match — nothing to conflict with yet), word_append_text (append paragraphs, If-Match-guarded), word_replace_text (find/replace across paragraphs and table cells, If-Match-guarded, returns a replacement count), word_export_pdf (server-side PDF conversion, uploaded beside the source; returns file metadata, never the PDF bytes).
Diagnostics: word_check_connection verifies that granted OAuth scopes cover the configured access tier.

`word_replace_text` approach

Replacement runs in a single pass per paragraph (body and table cells alike), scanning each paragraph's original text exactly once:

original = paragraph.text (the concatenation of all its runs) is scanned for find and the count and replacement are both computed from that one, never-mutated string. Scanning already-replaced text instead (a run-then-paragraph two-pass approach) is how a replace value that itself contains find would double-count and corrupt the result — e.g. find='foo', replace='foobar' on 'foo is here' would match once, rewrite it to 'foobar is here', then find 'foo' again inside the freshly written 'foobar' on a second pass, ending with a wrong count of 2 and corrupted text 'foobarbar is here'. A single pass over the original text avoids this entirely.
Paragraphs with zero matches are left completely untouched — no run is touched, no formatting is disturbed.
Paragraphs with at least one match get their new text written into the first run, with every other run in that paragraph blanked. The first run's formatting wins for the whole merged text — a multi-run paragraph that matches loses its intra-paragraph formatting boundaries (bold/italic spans, etc.) on replacement. This is a known trade-off of a plain read-modify-write text replace, not a substitute for a real Word editing session.

Setup

Authenticate with either an Entra app (microsoft.tenantId / microsoft.clientId / microsoft.clientSecret / microsoft.userPrincipalName, client-credentials flow) or user OAuth (click sign-in to populate microsoft.userToken). See microsoft-oauth.md for the Entra app / consent setup shared by every Microsoft 365 tool service. The Graph permission the app needs depends on the auth mode:

Auth mode	Tier	Graph permission
User OAuth (delegated)	`readonly`	`Files.Read`
User OAuth (delegated)	`write`	`Files.ReadWrite`
Entra app (application, admin consent)	`readonly`	`Files.Read.All`
Entra app (application, admin consent)	`write`	`Files.ReadWrite.All`

Application permissions always require admin consent. Unlike the Excel workbook API, Word's drive-item download/upload/convert calls work app-only, so both auth modes are fully supported.

Limits

Concurrency: round-trip edits (word_append_text, word_replace_text) use If-Match; a stale eTag (someone else edited the file since it was downloaded) surfaces as a GraphError naming the conflict. The tool does not retry automatically — re-read with word_read_text and retry the edit.
word_export_pdf relies on Graph's server-side format conversion (?format=pdf); very large or exotic documents may take longer to convert or fail conversion upstream.
word_replace_text writes a matched paragraph's new text into its first run and blanks the rest, collapsing per-run formatting in that paragraph to the first run's style — acceptable for plain text edits, not a substitute for a real Word editing session. Unmatched paragraphs are untouched.
Rate limits are per Entra app / tenant; the node retries 429/5xx with exponential backoff.

Examples

An agent creates a report, then finds and replaces a placeholder:

word_create_document  { "path": "Docs/report.docx",
                         "paragraphs": ["Q3 Report", "Status: DRAFT"] }
word_replace_text      { "file": "Docs/report.docx", "find": "DRAFT",
                          "replace": "FINAL" }

Upstream docs

Microsoft Graph drive content API: https://learn.microsoft.com/en-us/graph/api/driveitem-get-content
DriveItem format conversion: https://learn.microsoft.com/en-us/graph/api/driveitem-get-content-format
python-docx: https://python-docx.readthedocs.io/

Troubleshooting

Scope / 403 errors: call word_check_connection; if scopes are missing, disconnect and reconnect the Microsoft account (user auth) or grant/consent the Entra app permission (service auth) at the required tier.
access is read-only: write tools raise MicrosoftAccessError; raise word.access to write.
Conflict / 409 / 412 errors: the file changed since it was downloaded (someone else edited it, or a prior call's upload already advanced the eTag). Call word_read_text to get the current content and retry the edit.
word_replace_text returns 0: confirm the exact text — find is a literal (case-sensitive) substring match, not a regex.

What it does​

Configuration​

Access tiers → scopes​

Tools​

word_replace_text approach​

Setup​

Limits​

Examples​

Upstream docs​

Troubleshooting​