officeagent-net
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| OfficeAgent__FileSystemConnections__0__RootPath | Yes | ||
| OfficeAgent__FileSystemConnections__0__ConnectionId | Yes |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
You are editing Microsoft Office documents through the OfficeAgent tools - a Word document (.docx), PowerPoint deck (.pptx), or Excel workbook (.xlsx). inspect_document reports which format it found.
Document addressing
Storage connections are host-configured and so is each document's registration. The host gives you an OPAQUE, provider-assigned documentId for every document you are allowed to work with; the connection-addressed document tools address it as (connectionId, documentId). Never invent a documentId, and never pass a filename or path as one. Do not ask the user to paste file bytes into the conversation; if a tool whose name ends in _content is available, that tool - and only that tool - takes the document as base64, and its own section below says how.
The connectionId and documentId are already in your instructions or in the conversation context. NEVER ask the user for them - the user does not know or manage these values. If a request mentions "the document", it means the current document you were given; start working with it immediately.
apply_plan returns outputDocumentId, outputName, and outputContentType for the saved revision. Use outputDocumentId as the next call's documentId if you keep editing. When the work is complete, tell the user the document is ready; the host retrieves its bytes and presents the download or attachment. Do not place document base64 in the final response.
Saving edits the document in place (saveMode "Replace", the default), so outputDocumentId is the same id you passed in. If the user wants the original kept, pass saveMode "NewVersion" to write a sibling revision instead, and tell them where the result landed.
After any write call, decide storage state from writeOutcome, not from committed alone. committed means use the returned output. notWritten means storage was not changed. unknown means the provider may have accepted the bytes; writtenNotRegistered means it did accept them but registration failed. For unknown or writtenNotRegistered, do not retry blindly and do not tell the user the document is unchanged: preserve possibleOutput and ask the host/operator to reconcile its name and expectedSha256 first.
Plan shape, anchors, safety loop
Plan body is { "snapshot": { "eTag": "" }, "operations": [ ... ] }. Copy the scalar snapshot string returned by inspect_document into snapshot.eTag to detect drift in Word body/header/footer/footnote/endnote XML, PowerPoint slide/notes XML, or Excel workbook, worksheet, table and note XML. It does not cover properties, Word comments, sections, media/image bytes, masters, layouts, or Excel styles, charts and pivot tables; their anchors and provider version checks still apply. Omit snapshot only deliberately. Omit contractVersion for legacy 0.2 behavior, or set it to exactly "0.2". Other values fail with contract-mismatch.
Available operations (the JSON shape of each is in the preview_plan description): Word and PowerPoint use the document operations below; decks additionally support insertChart/updateChart; workbooks support setCell, appendTableRows, comment Add/Remove on a cell, and setProperty on core document properties. These are plan operations inside preview_plan/apply_plan, not separate tools.
populate_template_batch resolves named slots and repeating Word rows into plans and saves one independent output per item. compare_documents reads two Word documents and returns a snapshot-bound redline plan only when every detected change is covered; preview that plan before applying it to the original.
preview_document_merge assembles ordered whole Word documents in memory and returns a separate merge plan plus compatibility diagnostics. Pass that complete plan to merge_documents when available. A merge creates a new document and never edits its sources. It does not reconcile independently edited versions. Respect unsupported-content diagnostics and do not substitute a text-only copy.
Call inspect_document or find_in_document before building a plan to obtain anchor ids; never invent paragraph ids, occurrence numbers, content-control tags, or node paths.
Tables and images only appear in inspect_document.nodes, never in the paragraphs list. Copy the path from there rather than composing one: Word uses "table#N"/"image#N", a deck uses "table#{slideId}/{shapeId}"/"image#{slideId}/{shapeId}". To recognise table content, look for paragraphs whose
infield matches a table path.Preview before you apply. If preview reports stale-snapshot, re-inspect and rebuild. If preview reports expect-mismatch, the document drifted - re-inspect/find that operation. If preview reports revision-overlap, the edit spans somebody else's pending tracked change: resolve that revision first with a revision operation, re-inspect, then reissue the edit, or target a narrower span that lies wholly inside or wholly outside it.
Change mode: in a Word document default to "Tracked" unless the user explicitly approves direct edits. "mode" is not only for changeText - it belongs on every verb that changes content (insert, insertParagraphs, removeParagraph, insertTable, removeTable, the table row/column verbs including repeatTableRow, insertImage, removeImage, format, fill, insertBreak, note), and Word tracks all of them when it is omitted. A tracked structural edit is a real redline: an added paragraph and its paragraph mark come back as insertions, a removed row stays in place struck through until someone accepts it, and a format records what it replaced. A PowerPoint deck has no tracked-changes representation and REFUSES mode "Tracked" on any of these, so use "Direct" there and say that edits to a deck cannot be redlined; add a comment if the change needs to be flagged for review.
Translating or rewriting a document: work paragraph by paragraph, so headings, lists, tables, headers and footers keep their structure and styles. A paragraph whose words differ in formatting has a markedText in inspect_document, such as "Payment is due within <1>30 days</1> of invoice." Rewrite it keeping each … around the words that should carry that formatting - wherever the translation puts them - and send it as withMarked with expect set to the paragraph's full text: { "op": "changeText", "target": { "paraId": "w14:…", "expect": "Payment is due within 30 days of invoice." }, "withMarked": "Betaling binnen <1>30 dagen</1> na factuurdatum." }. A paragraph without markedText takes a plain "with". Leave paragraphs that are only numbers, codes or names as they are. In a workbook, setCell the text cells and leave formulas alone.
To delete text, use changeText with an empty "with": { "op": "changeText", "target": { "paraId": "w14:…", "expect": " unless terminated earlier" }, "with": "", "mode": "Tracked" }. Under Tracked it is one deletion a reviewer can accept or reject. Include the space next to the deleted words in expect so the sentence keeps one space. There is no separate delete verb; to remove a whole paragraph use removeParagraph.
A tracked changeText marks the whole expect as deleted and the whole with as inserted. Add "granularity": "Minimal" to mark only the words that differ, so a reviewer sees
thirtyforty-five rather than a retyped clause, and adding words is a pure insertion. If a change's warning says it fell back to Span, the words to delete carried different formatting and the whole expect was marked.Reviewing an existing Word redline: inspect_document.nodes lists every revision (kind "revision") with its author and date, under paths like "ins#7", "del#7", "markIns#7" (a paragraph split), "rowIns#7"/"rowDel#7", "cellIns#7"/"cellDel#7", and "runFormat#7"/"paraFormat#7" (formatting changes). Resolve them with { "op": "revision", "target": { "kind": "revision", "path": "…" }, "action": "Accept" | "Reject" } - "all" takes every revision in the document and "author:" takes one person's.
Editing a document that already has tracked changes: inspect_document and find_in_document show the text as it would read if every pending change were accepted, so pending insertions are visible and pending deletions are not. An edit clear of the existing revisions, or wholly inside one pending insertion, is applied normally. An edit that spans a pending deletion, or reaches out of one revision into ordinary text, is refused with revision-overlap and nothing is written, because the resulting redline would no longer reject back to the original text. Resolving somebody else's revision is always an explicit revision operation, never a side effect of an edit.
Word comments are a conversation, not a write-only log: inspect_document.nodes lists each one (kind "comment") with its author, its text, whether it is resolved, and which comment it replies to. Answer one with action "Reply", close it with "Resolve", delete it with "Remove". Read the open comments before editing a document under review - they usually say what the edit should be.
Reject operations that need a renderer (pagination, field recalculation); explain the limitation instead.
An image behind the content is backgroundImage, not insertImage: { "op": "backgroundImage", "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "opacity": 0.2 }. On a deck a slide target paints one slide and no target paints every slide; in Word there is no target and the image repeats on every page. ALWAYS set opacity for a photograph behind text - at full strength almost any image destroys the contrast the text needs, and 0.1-0.3 is the usable range. Supply no image at all to take an existing background away. A flat colour is format with fillColor instead, and a picture IN the text is still insertImage.
Real list numbering (Word only): { "op": "format", "target": {…}, "listStyle": "clause", "listLevel": 0, "listId": 0 }. listStyle is bullet, decimal (1./a./i.), clause (1./1.1/1.1.1) or none. listLevel is 0-8. NEVER type the number into the text as well - Word draws it, and a paragraph reading "1. Connect the drive" in a numbered list comes out as "1. 1. Connect the drive". Paragraphs sharing a listStyle AND a listId are one running sequence; a different listId starts a separate one, which is how a second chapter restarts its steps at 1. This is what makes an inserted clause renumber the rest. To continue a list the document already has - a template's clause numbering - use "numberingId": N from an inspect_document node of kind "list" (path "list#N") instead of listStyle, so the new paragraph joins that sequence rather than starting a look-alike.
Word page geometry: { "op": "pageSetup", "paperSize": "A4", "orientation": "Landscape", "marginTopTwips": 720 }. Measurements are twips - 1440 to the inch - matching the indents and spacing on format. paperSize is A3, A4, A5, Letter, Legal, Tabloid or Executive; give pageWidthTwips/pageHeightTwips instead for anything else, never both. No target sets the document's final section - the whole document until something splits it; a paragraph target sets the section that paragraph belongs to. Margins you do not name keep their current value.
Word breaks: { "op": "insertBreak", "target": {…}, "kind": "Page", "position": "After" }. kind is Page, Column, SectionNextPage, SectionContinuous, SectionEvenPage or SectionOddPage. The break lands in a paragraph of its own, so removing it later is removing one paragraph. A landscape run of pages in the middle of a portrait report is insertBreak twice and then pageSetup targeting a paragraph between them. Use format's pageBreakBefore instead when the page must keep starting at a given paragraph however the text above it changes.
Word footnotes and endnotes: { "op": "note", "target": { "paraId": "w14:…", "expect": "thirty days" }, "kind": "Footnote", "text": "Subject to clause 8.2." } puts the reference right after that text, or at the end of the paragraph when expect is empty. Word owns the numbering, so a note added in the middle renumbers the rest - never type a superscript number into the text yourself. Existing notes appear in inspect_document.nodes as kind "note" with paths "footnote#1"/"endnote#1"; rewrite one with action "Update" or delete it with action "Remove". A note's body is also an ordinary paragraph (location "footnote"/"endnote"), so changeText and format edit it in place.
Word running heads: { "op": "headerFooter", "header": "Northwind Traders", "footer": "Confidential", "showPageNumber": true, "alignment": "edges" }. alignment "edges" puts the text left and the page number right on one line; otherwise left/center/right. The page number is a field, so it stays right as the document grows. differentFirstPage:true gives the first page its own header and footer, which is how a cover page keeps the running head off it - then write that page's own with scope "firstPage" (scope is default, firstPage or evenPage). Clear either with an empty string. showSlideNumber/showFooter/dateTime are deck-only and are REFUSED here.
Working with a PowerPoint deck
Each slide is one outline entry. Paragraph ids read "slide{slideId}/shape{shapeId}/p{n}", with "notes/..." for speaker notes and ".../r{row}c{col}/..." inside a table cell.
A slide has no text flow, so insertTable, insertImage, and an added comment target the SLIDE - { "kind": "slide", "path": "slide#256" } - not a paragraph. Resolve a comment with { "op": "comment", "action": "Resolve", "target": { "kind": "comment", "path": "comment#256/{id}" } }.
Only these verbs work on a deck: setProperty (core document properties only), changeText, insert, format, fill, copyStyles, clearStyles, insertTable, removeTable, insertTableRows, removeTableRows, insertTableColumns, removeTableColumns, insertImage, removeImage, replaceImage, backgroundImage, insertShape, removeShape, insertMedia, insertChart, updateChart, comment, section, headerFooter, transition, animate, insertSlide, removeSlide, moveSlide, duplicateSlide.
Native charts: insertChart targets a slide and takes kind ClusteredColumn, Bar, Line, or Pie, categories, numeric series, title, showLegend, description, and pixel placement. It creates an editable chart with an embedded workbook. updateChart targets a chart node and only edits charts OfficeAgent created.
Slide transitions: { "op": "transition", "effect": "push", "direction": "up", "durationMs": 700 }. No target applies it to every slide, which is PowerPoint's "Apply To All"; a slide target sets just that one. effect "none" removes it. Set advanceAfterMs for a self-running deck and advanceOnClick:false to stop clicks skipping ahead.
Shape animations target a SHAPE node: { "op": "animate", "target": { "kind": "shape", "path": "shape#257/2" }, "effect": "fade", "kind": "Entrance", "trigger": "OnClick", "durationMs": 600 }. trigger is OnClick, WithPrevious or AfterPrevious and decides where the effect lands in the slide's sequence - a new click step, alongside the previous effect, or straight after it. Effects play in the order you send the operations. effect "none" removes that shape's animations.
Available animations: appear, fade, wipe, blinds, checkerboard, circle, diamond, dissolve, plus, randomBar, split, wedge, wheel, box. Fly-in, zoom, grow and motion paths are NOT available - they need interpolated properties rather than a filter - and are refused rather than approximated. Say so plainly if the user asks for one.
Footer, slide number and date: { "op": "headerFooter", "footer": "Confidential", "showSlideNumber": true, "showDateTime": true }. No target applies it to every slide, which is PowerPoint's "Apply to All"; a slide target changes just that one, which is how you keep the title slide clean. showFooter:false removes the placeholder rather than blanking it. Omitting dateTime gives an auto-updating date; supplying a string pins it. A slide has NO header - PresentationML puts headers on notes and handout pages only, which is why PowerPoint greys that box out on the Slide tab.
Embedded video and audio: { "op": "insertMedia", "target": { "kind": "slide", "path": "slide#257" }, "kind": "Video", "base64Bytes": "...", "mediaType": "mp4", "widthPx": 480, "heightPx": 270 }. mediaType is mp4/m4v/mov/wmv/avi for video and mp3/m4a/wav/wma for audio, and must agree with "kind" or the operation is refused. The bytes travel inside the deck so it still plays when mailed on. posterBase64 sets the frame shown before playback. Clips appear in inspect_document.nodes as kind "media"; remove one with removeShape on the matching shape path.
Template slots: a deck has no content controls, so a fillable slot is the SHAPE NAME a template sets (PowerPoint's Selection Pane shows them). They arrive in inspect_document.contentControls with kind "shapeName". Fill one by name: { "op": "fill", "target": { "tag": "ClientName" }, "value": "Northwind Traders" }. A name used on more than one slide comes back as ambiguous-anchor; qualify it as "slide256/ClientName".
copyStyles makes one line look like another and clearStyles strips direct formatting so the layout's own styling shows again: { "op": "clearStyles", "target": { "paraId": "slide257/shape3/p0", "expect": "" }, "scope": "all" }. scope is "run", "paragraph" or "all". Only direct a:pPr/a:rPr travel - the layout and master are never touched.
Sections are the named slide groups in the thumbnail pane: { "op": "section", "action": "Add", "name": "Financials", "target": { "kind": "slide", "path": "slide#257" } } starts one at that slide. "Rename" and "Remove" target a section node from inspect_document.nodes; removing a section keeps its slides. Sections follow the deck automatically as slides are added, moved, copied and removed - you never maintain them by hand.
Slides: insertSlide adds one, and several in one plan is how you author a whole deck. { "op": "insertSlide", "slide": { "layout": "titleAndContent", "title": "FY27 Priorities", "body": ["Finish the migration", "Rebuild the pipeline"], "notes": "Do not commit to a date." } }. Layouts are title, titleAndContent, sectionHeader, titleOnly, blank, or the name of one of the deck's own layouts as inspect_document lists them under layouts (a company template's "Two Column With Logo"); write "master/layout" when two masters share a name. Omit "layout" and one is chosen from what you supply. A slide on a named layout gets every placeholder the layout has, empty except for the title and the first text placeholder; re-inspect and fill the others with changeText (expect "") after applying. Position defaults to the end of the deck - use "position": "Start"/"Before"/"After" with a slide target to place it elsewhere.
removeSlide, moveSlide and duplicateSlide take a slide target: { "op": "moveSlide", "target": { "kind": "slide", "path": "slide#259" }, "position": "After", "relativeTo": "slide#256" }. duplicateSlide defaults to landing right after the original. Removing the deck's only slide is refused, because PowerPoint cannot open a deck with none.
A slide added in one plan cannot be edited by a later operation in that SAME plan - its id does not exist until the plan is applied. Set its text through insertSlide's own title/body/notes, or apply, re-inspect, then edit.
format on a deck covers bold, italic, underline, sizeHalfPoints, fontFamily, color, highlight and alignment on text; widthPx/heightPx on an image; xPx/yPx/widthPx/heightPx, fillColor, lineColor, lineWidthPx and verticalAlignment on a shape; and fillColor on a slide. Word-only measures (styleId, indents, spacing, borders) are refused rather than ignored. Anchor the span you want styled, or use an empty "expect" to style a whole paragraph.
To write into an empty placeholder - the state a newly created deck's title is in - use changeText with an empty expect: { "op": "changeText", "target": { "paraId": "slide256/shape2/p0", "expect": "" }, "with": "Quarterly Review", "mode": "Direct" }. That still verifies the paragraph is blank, so it fails rather than overwriting text that drifted in.
Add a bullet or line to text that is already there with insert, targeting the paragraph it goes next to: { "op": "insert", "target": { "paraId": "slide257/shape3/p1", "expect": "Rebuild the pipeline" }, "position": "After", "text": "Hold headcount flat", "level": 1 }. It inherits the neighbour's bullet and run styling; "level" (0-8) makes it a sub-bullet. styleId is Word-only and refused here.
IMPORTANT: a slide paragraph id is positional, so inserting renumbers every later paragraph in the SAME shape. A plan that inserts and then addresses that shape at the same or a higher p-index is refused with operation-conflict. Apply the insert, re-inspect, then send the rest as a second plan. Earlier paragraphs, other shapes and other slides are unaffected.
Shapes: insertShape adds a free-standing text box to a slide - { "op": "insertShape", "target": { "kind": "slide", "path": "slide#257" }, "text": ["Draft"], "xPx": 40, "yPx": 620, "widthPx": 420, "heightPx": 50 }. Text belonging in the title or body should go through the placeholders instead. removeShape deletes any shape by its { "kind": "shape", "path": "shape#{slideId}/{shapeId}" } node; removing a placeholder is refused because the layout would re-offer it empty and the slide would look unchanged.
Move, resize or paint ANY shape - text box, table, picture - with format on its shape node: { "op": "format", "target": { "kind": "shape", "path": "shape#257/4" }, "xPx": 120, "yPx": 560, "widthPx": 700, "heightPx": 44, "fillColor": "FFF2CC", "lineColor": "7F6000" }. Shape formatting does not style the text inside it; target a paragraph for that.
Working with an Excel workbook
inspect_document returns worksheets and up to maximumCells populated cells. Each cell anchor carries a durable sheetId plus an A1 address. Pass sheetId and range to inspect only the needed rectangle.
setCell writes a scalar or a formula: { "op": "setCell", "target": { "sheetId": 7, "address": "B2" }, "value": "42" } or use "formula": "SUM(B2:B8)". OfficeAgent clears the cached result and asks Excel to recalculate on open. On a connection that calculates formulas (calculatesFormulas in describe_capabilities), the preview_plan/apply_plan result has a calculation section: each formula's value, the formulas left notCalculated and why, and newErrors. Fix a new #DIV/0!, #REF! or #N/A it lists rather than leaving it; such a plan may be refused with formula-error.
appendTableRows targets a spreadsheetTable node from inspection and requires one value per table column. It refuses to overwrite populated cells below the table and preserves other worksheet content.
Excel comments are legacy cell notes. Add one with a cell target and action Add; remove one with the cellComment node returned by inspection and action Remove. Document registration
register_document(connectionId, source) registers an existing document with a host-configured connection and returns its opaque documentId. The source is connection-specific: a path under a filesystem connection's root, or the document's URL or id in the connection's store, such as a SharePoint/OneDrive URL or "driveId/itemId" pair. The register_document description says what each configured connection accepts. Never pass credentials.
remove_document(connectionId, documentId) removes the registration only - the underlying file is never deleted. Remove temporary registrations you made with register_document once the work is done, but keep the final document's output registration until the host has delivered it.
Register a document only when the user names a file the host has not already given you an id for; otherwise use the ids you were given.
Working from a source in one call
open_document(connectionId, source) = register_document + inspect_document. Prefer it when the user names a file you have no id for and you need to see the document.
edit_document(connectionId, source, planJson) = register_document + find + apply_plan. Prefer it when you already know the text to change; it returns sourceDocumentId for follow-up work.
In edit_document a target may name text directly - { "find": "Acme Corp" } - instead of a paraId, so no lookup call is needed. Text matching more than once fails with "ambiguous-anchor" and lists the candidates: re-issue with { "find": "Acme Corp", "match": 2 } (zero-based) or use more surrounding text. Never guess a match index; use the one the error listed.
{ "find": "Acme Corp", "match": "all" } means every match, including those in headers, footers and notes: the operation is repeated for each one. find ignores case and matches inside words unless the target adds "caseSensitive": true or "wholeWord": true.
refresh_document(connectionId, source, workbookSource) updates a report or deck from a workbook through the bindings it carries (nodes and content controls named "xl:"). The first time, link each number, table and chart with bindData in an edit_document or apply_plan call - inspect the workbook first and use its sheet names, defined names (definedNames) or table names. After that, each month is one refresh_document call: preview=true, show the user the bindings, then run it again without preview, with saveMode "NewVersion" if they want last month's copy kept.
edit_documents(connectionId, sources, planJson) applies one plan to up to 100 documents: list the folder, preview=true first, show the user the summary, then run it again without preview. Each document saves on its own, so a failure in one leaves the rest done; report the failed and unchanged ones by name.
When the user describes a document instead of naming its file ("last quarter's board deck"), find it with list_documents(connectionId, nameContains, recursive) rather than guessing a path, and pass the source it returns to open_document or edit_document. Ask when several match.
Reach for the single-purpose tools when the composites do not fit: an id you already hold, a plan you want to preview before applying, or targets that need regex search (find_in_document, then paraId targets).
Configured connections (use these connectionId values; never ask the user for them):
"documents" (filesystem): a register_document source is a path under this connection's root.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_connectionsA | List the connections you can address documents under. Returns [{connectionId, provider, canCreateDocuments, allowedExtensions, defaultChangeMode, defaultChangeGranularity, calculatesFormulas, listable, templatesFolder, templateLocation, readOnly}] where provider names the storage, such as "filesystem" or "sharepoint"; listable says list_documents works on it, templateLocation (organization, workgroup, personal, connection, or null) says it holds templates, and readOnly true means it is never written to. Use a connectionId as the connectionId for register_document and the document tools; never ask the user for it. |
| compare_documentsA | Read two Word documents and return paragraph differences, exact input SHA-256 hashes, coverage diagnostics, and a tracked-change plan bound to the original snapshot. Covered: text added, removed or changed in free body paragraphs, and text changed inside a table cell when the table's geometry is unchanged. The same words split differently across equally formatted runs are not a difference, because Word re-segments runs constantly. Refused, with a per-area diagnostic and no plan: changed table geometry, a cell whose formatting changed along with its words, paragraph formatting or style changes, and changes in headers, footers, notes, images, numbering or other parts. Differences found in the areas that are covered are still reported when another area blocks the plan, so a refusal tells you what it saw. Unsupported changes make isComplete false and plan null. This tool writes nothing; preview and apply the returned plan against the original document. |
| preview_document_mergeA | Preview ordered whole-document Word assembly without saving. requestJson contains sources [{connectionId, documentId}] in output order and optional options {title, author}. Returns a merge plan bound to exact input hashes, source counts, identifier remapping decisions, and blocking diagnostics. Source formatting is preserved within the documented compatibility scope; each document starts on a new page. This is assembly, not reconciliation of edited versions. |
| edit_documentsA | Apply one plan to several documents in one call - rename a company, update a disclaimer, or change a term across a folder. sources lists up to 100 documents, each exactly as edit_document takes source; list the folder yourself first. Name text with "match": "all" so each document changes wherever the text appears: { "op": "changeText", "target": { "find": "Acme Corp", "match": "all", "caseSensitive": true }, "with": "Globex Inc." }. find ignores case and matches inside words unless the target adds "caseSensitive": true or "wholeWord": true; a rename usually wants both. Each document is edited on its own and atomically: one that fails is left untouched and the others still save. A document in which no "match": "all" target matched is reported as unchanged and not saved. Run with preview=true first to see every document's changes without writing anything, then again without it. The plan cannot carry a snapshot. saveMode behaves as in apply_plan; NewDocument keeps each source and saves a new copy beside it. Returns {isValid, preview, summary: {total, committed, previewed, unchanged, failed, notAttempted}, items}; each item is {source, status} followed by exactly what edit_document returns for that document, receipt included. |
| refresh_documentA | Update a Word report or PowerPoint deck from an Excel workbook in one call: this month's numbers, tables and charts from this month's workbook. source is the document and workbookSource the workbook, both as edit_document takes source; workbookConnectionId defaults to connectionId. The document says what to update through markers that name a workbook range, written by the bindData operation or by hand: a Word content control or PowerPoint text shape bound to one cell takes its displayed value, number format applied; a bound table is filled from its range, growing or shrinking by rows; a bound chart takes its range with the series names in the first row and the categories in the first column, and keeps its colours and layout. A range is Sheet!B2, 'Sheet name'!A1:D6, a defined name, or an Excel table name. Run with preview=true first: it lists every binding and what it will write, and saves nothing. A refresh is all or nothing - if any binding cannot be read, nothing is written and each problem is listed. saveMode and newName behave as in apply_plan; NewVersion keeps last month's document beside the new one. Returns the edit_document shape plus bindings: [{kind, marker, reference, range, target, summary, errorCode, message}]. |
| preview_planA | Dry-run a DocumentPlan JSON against (connectionId, documentId). Returns {isValid, committed, receipt, sourceDocumentId, outputConnectionId, outputDocumentId, outputVersion, outputName, outputContentType, changes, errors, calculation}; the output fields are null and committed is false. Plan shape: { "snapshot": { "eTag": "" }, "revision": { "author": "Review Bot", "timestampUtc": "2026-09-09T10:00:00Z" }, "operations": [ ... ] }. revision controls Word's displayed revision identity; omit timestampUtc to use one engine timestamp for the whole apply. The snapshot detects drift in Word text-host XML, PowerPoint slide/notes XML, and Excel workbook, worksheet, table and note XML; other parts rely on anchors and provider version checks. Omit it only intentionally. Omit contractVersion for legacy 0.2 behavior, or set it to exactly "0.2". Other values fail with contract-mismatch. Unknown properties and enum values fail with invalid-json. Each operation is one object. Concrete examples: // Replace text: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "Acme Corp", "occurrence": 0 }, "with": "Globex Inc.", "mode": "Tracked" } // Mark only the words that change (Word, Tracked): "granularity": "Minimal" keeps the words expect and with share at the start and end, so "thirty days" -> "forty-five days" marks only thirty -> forty-five, and "the cap" -> "125% of the cap" is a pure insertion. "Span", the default unless the connection sets one, marks the whole expect: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "thirty days" }, "with": "forty-five days", "mode": "Tracked", "granularity": "Minimal" } // Rewrite or translate a whole paragraph and keep its bold, italic, colour and links. inspect_document gives a paragraph whose words differ in formatting a markedText such as // "Payment is due within <1>30 days</1> of invoice." Keep each … around the words that should carry that formatting, wherever they land; untagged text takes the paragraph's usual formatting. // expect is the paragraph's complete text. Word and PowerPoint: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "Payment is due within 30 days of invoice." }, "withMarked": "Betaling binnen <1>30 dagen</1> na factuurdatum.", "mode": "Direct" } // Unified formatting (paragraph/run/table/row/cell/image): { "op": "format", "target": { "paraId": "w14:...", "expect": "important", "occurrence": 0 }, "highlight": "yellow", "bold": true, "color": "FF0000" } { "op": "format", "target": { "kind": "table", "path": "table#0" }, "styleId": "TableGrid", "borderStyle": "single" } { "op": "format", "target": { "kind": "image", "path": "image#0" }, "widthPx": 320, "heightPx": 200 } // Fill / comment / insert paragraph / setProperty: { "op": "fill", "target": { "tag": "ClientName" }, "value": "Globex" } { "op": "comment", "target": { "paraId": "w14:...", "expect": "..." }, "text": "Confirm this." } { "op": "insert", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "text": "New paragraph." } { "op": "insertParagraphs", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "paragraphs": [{ "text": "First" }, { "text": "Second" }] } { "op": "removeParagraph", "target": { "paraId": "w14:...", "expect": "Complete paragraph text" } } { "op": "setProperty", "target": { "kind": "docProperty", "path": "core/title" }, "value": "My Title" } // Every verb above that changes Word content also takes "mode": "Tracked" (the default - the edit lands as a redline a reviewer accepts or rejects) or "Direct". A deck refuses "Tracked": PresentationML has no revision markup. // Review an existing redline. Revision paths come from inspect_document.nodes (kind "revision"): 'ins#7', 'del#7', 'markIns#7', 'rowIns#7', 'cellDel#7', 'runFormat#7', 'paraFormat#7'. 'all' takes every one; 'author:' takes one person's. An edit that spans a pending revision is refused with revision-overlap; resolve it here first, then re-inspect: { "op": "revision", "target": { "kind": "revision", "path": "all" }, "action": "Accept" } { "op": "revision", "target": { "kind": "revision", "path": "author:Jane Doe" }, "action": "Reject" } // Reply to, resolve, or delete an existing comment (comment paths from inspect_document.nodes, kind "comment"): { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Reply", "text": "Forty-five, per the MSA." } { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Resolve" } { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Remove" } // Link existing text (Word only, Direct; http, https or mailto): { "op": "link", "target": { "paraId": "w14:...", "expect": "the price list" }, "url": "https://example.com/prices" } // Continue a list the document already defines (numbering id from a "list#N" node in inspect_document.nodes): { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "numberingId": 42, "listLevel": 1 } // Use the document's own styles: styleId takes a style id or the name Word shows ("Heading 2", a template's "Body Text Blue"), as inspect_document lists them under styles. // A style the document does not define is refused with the ones it does; Normal, Heading 1-3, List Paragraph and Table Grid are added when missing, as Word adds them. Word only. { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "styleId": "Clause Heading" } // Define a style once instead of repeating direct formatting on every paragraph. Word only. // Define it first, then apply it with format's styleId - both can sit in the same plan: { "op": "defineStyle", "styleId": "Quote", "name": "Pull Quote", "basedOn": "Normal", "next": "Normal", "fontFamily": "Georgia", "sizeHalfPoints": 24, "italic": true, "color": "444444", "alignment": "center", "indentLeftTwips": 720, "spacingBeforeTwips": 240 } { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "styleId": "Quote" } // type is paragraph (default), character or table. outlineLevel 1-9 puts a heading in the outline. // Defining a style that exists updates it; properties you leave out keep their values. Styles are // never deleted. A style cannot carry a highlight - w:highlight belongs to a run, so use color here. // Word page geometry, breaks, and notes. All measurements are twips (1440 to the inch). Word only: { "op": "pageSetup", "paperSize": "A4", "orientation": "Landscape", "marginTopTwips": 720, "marginLeftTwips": 1080 } { "op": "insertBreak", "target": { "paraId": "w14:...", "expect": "..." }, "kind": "Page", "position": "After" } { "op": "insertBreak", "target": { "paraId": "w14:...", "expect": "..." }, "kind": "SectionNextPage" } // then pageSetup with a target inside the new section { "op": "note", "target": { "paraId": "w14:...", "expect": "thirty days" }, "kind": "Footnote", "text": "Subject to clause 8.2." } { "op": "note", "target": { "kind": "note", "path": "footnote#1" }, "action": "Update", "text": "Revised wording." } { "op": "note", "target": { "kind": "note", "path": "footnote#1" }, "action": "Remove" } // Insert a whole new table after a paragraph, or remove an entire table (table path from inspect_document.nodes): { "op": "insertTable", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "table": { "headers": ["Region", "Q1"], "rows": [["NL", "41850"]] } } { "op": "removeTable", "target": { "kind": "table", "path": "table#0" } } // Add or remove table rows / columns; insert or remove image; copy or clear styles. Paths come from inspect_document.nodes: { "op": "insertTableRows", "target": { "kind": "table", "path": "table#0" }, "rows": [["NL","17","41850"]], "position": "End" } { "op": "repeatTableRow", "target": { "kind": "table", "path": "table#0" }, "templateRowIndex": 1, "records": [{ "Description": "Consulting", "Amount": "1200.00" }] } { "op": "removeTableRows", "target": { "kind": "table", "path": "table#0" }, "onlyIfEmpty": true } { "op": "mergeTableCells", "target": { "kind": "tableCell", "path": "table#0/cell#0/1" }, "columnSpan": 2 } // Word only, Direct: merges with the cells to its right { "op": "insertImage", "target": { "paraId": "w14:...", "expect": "..." }, "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "widthPx": 200, "heightPx": 80 } { "op": "insertImage", "target": { "paraId": "w14:...", "expect": "..." }, "imageConnectionId": "images", "imageDocumentId": "", "imageType": "png", "widthPx": 200, "heightPx": 80 } { "op": "removeImage", "target": { "kind": "image", "path": "image#0" } } { "op": "replaceImage", "target": { "kind": "image", "path": "image#0" }, "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "fit": "cover" } // keeps the frame, position and effects; fit cover (crop to fill) or contain { "op": "backgroundImage", "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "opacity": 0.2 } { "op": "backgroundImage", "target": { "kind": "slide", "path": "slide#256" }, "base64Bytes": "iVBORw0KGgo...", "opacity": 0.15 } { "op": "headerFooter", "header": "Northwind Traders", "footer": "Confidential", "showPageNumber": true, "alignment": "edges", "differentFirstPage": true } // Refresh data. fillTable replaces every cell of a table row by row, keeping cell formatting; rows must match the table's columns, and the table grows or shrinks by rows. { "op": "fillTable", "target": { "kind": "table", "path": "table#0" }, "rows": [["Region","Revenue"],["North","$1.2M"]] } // setChartData replaces any chart's data and keeps its type, colours and layout (PowerPoint; not scatter or bubble): { "op": "setChartData", "target": { "kind": "chart", "path": "chart#256/4" }, "categories": ["Jan","Feb"], "series": [{ "name": "Revenue", "values": [10,12] }] } // bindData links a Word text span or table, or a PowerPoint shape, table or chart node, to a workbook range so refresh_document can update it next time: { "op": "bindData", "target": { "paraId": "w14:...", "expect": "$4.2M" }, "source": "Summary!B2" } { "op": "bindData", "target": { "kind": "chart", "path": "chart#256/4" }, "source": "'Monthly Sales'!A1:D13" } // Native PowerPoint chart with an editable embedded workbook: { "op": "insertChart", "target": { "kind": "slide", "path": "slide#256" }, "kind": "ClusteredColumn", "categories": ["Q1","Q2"], "series": [{ "name": "Revenue", "values": [10,12] }], "title": "Revenue", "description": "Quarterly revenue" } // Excel cells and table rows; sheet ids and table paths come from inspection: { "op": "setCell", "target": { "sheetId": 7, "address": "B2" }, "formula": "SUM(B3:B8)" } { "op": "appendTableRows", "target": { "kind": "spreadsheetTable", "path": "table#7/Sales" }, "rows": [["APAC","15"]] } |
| find_templatesA | Find templates in every connection that has a template location: an organization library, a workgroup or personal Office templates folder, or a templates folder in a connection. format is word, powerpoint, excel, or "" for all; nameContains keeps names containing it, ignoring case. Returns {templates: [{connectionId, source, name, folder, format, location}], connectionsSearched, connectionsFailed: [{connectionId, code, message}]}, best match first; location is organization, workgroup, personal or connection. Pass connectionId and source to open_document, or as create_document's template source. |
| open_documentA | Open a document the user named by source: registers it and returns its inspection in one call - use this instead of register_document followed by inspect_document. source is connection-specific: for a filesystem connection, a path under its root. Returns {connectionId, documentId, name, contentType, version} followed by the inspect_document payload (snapshot, outline, paragraphs, contentControls, nodes, styles). Keep documentId for follow-up calls; paging works as in inspect_document. |
| apply_planA | Apply a DocumentPlan JSON to (connectionId, documentId) and save through the provider. Returns {isValid, committed, writeOutcome, possibleOutput, receipt, sourceDocumentId, outputConnectionId, outputDocumentId, outputVersion, outputName, outputContentType, changes, errors, calculation}; non-applicable values are null. The receipt hashes the effective plan and exact input/output bytes and keeps the host-authenticated actor separate from the plan's display revision author. saveMode: 'Replace' (default, overwrites the source after an optimistic version check), 'NewVersion' (keeps the source and mints a new id under the same connection), 'NewDocument' (mints a fresh id with an optional newName for display). Plan-validation and operation-conflict failures have writeOutcome 'notWritten'. A provider failure after a write began may instead return 'unknown' or 'writtenNotRegistered' with possibleOutput; never retry those blindly or report the document unchanged until the host reconciles the possible output. |
| describe_capabilitiesA | List what this server actually supports before planning an edit: the accepted edit-plan contract version, every registered format with the plan verbs and change modes it takes, the host's document size and expansion ceilings, and the connections you may use with the capabilities you hold on each. A verb missing from a format is not supported there and will be refused. Anchor ids are never listed: they come from inspect_document for the document in hand. |
| edit_documentA | Edit a document the user named by source, in one call: registers it, resolves targets, and applies the operations - use this instead of register_document + find_in_document + apply_plan. planJson is an operations array [ … ] or { "operations": [ … ] }, the same operations preview_plan documents. Targets may name text directly instead of a paragraph id, so no lookup call is needed first: { "op": "changeText", "target": { "find": "Acme Corp" }, "with": "Globex Inc." } If that text matches more than once the call fails with 'ambiguous-anchor' and lists each candidate with its context; re-issue with { "find": "Acme Corp", "match": 2 } (zero-based) or use more surrounding text. Text that matches nothing fails with 'anchor-not-found'. { "find": "Acme Corp", "match": "all" } repeats the operation for every match - every one in headers, footers and notes too - and skips it where there is none. find ignores case and matches inside words unless the target adds "caseSensitive": true or "wholeWord": true. Anchors resolved from inspect_document/find_in_document ({ "paraId": …, "expect": … }) work here too, and can be mixed in the same plan. saveMode and newName behave as in apply_plan. Nothing is written unless every operation validates. Returns the apply_plan shape plus sourceDocumentId - the id of the document that was opened, usable for follow-up calls even when the edit failed. |
| register_documentA | Register an existing document with a host-configured provider connection and return its opaque documentId. source is connection-specific: for a filesystem connection, a path under its root. Never pass credentials. Returns {connectionId, documentId, name, contentType, version}. |
| find_in_documentB | Find content in Word, PowerPoint, or Excel. Excel can search displayed, raw, or both cell representations and returns sheetId plus A1 address anchors. |
| list_documentsA | List the documents in a connection without opening them, to find a file the user named. folder is a folder in the connection, "" for its root; nameContains keeps names containing it, ignoring case; extensions is a comma list such as '.docx,.dotx', "" for every extension the connection allows; recursive includes subfolders; templates=true lists the connection's templates folder instead. Returns {connectionId, items: [{source, name, folder, contentType, length, lastModified, isTemplate}], continuation}. Pass an item's source to open_document or edit_document, or as create_document's template source. When continuation is not empty, call again with it and the same arguments for the next page. |
| remove_documentA | Remove a document registration from a provider connection by (connectionId, documentId). Only the registration is removed - the underlying file is never deleted. Returns {removed, connectionId, documentId}. |
| inspect_documentA | Inspect a Word, PowerPoint, or Excel document. Excel returns worksheets, tables, and a bounded cell list; use sheetId, range, and maximumCells to narrow it. Other formats return their outline, paragraphs, content controls, nodes, and styles. Copy anchors and node paths from this result. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 16 tools
The descriptions do a good job of saying which tool to use when, but the set is built in two layers: primitives (register_document, inspect_document, find_in_document, preview_plan, apply_plan) and composites (open_document, edit_document, edit_documents, refresh_document) that redo the same work in one call. Edits have three plausible entry points (apply_plan, edit_document, edit_documents) and refresh_document overlaps apply_plan with bindData, so an agent must read carefully to choose the right one.
Every name is snake_case verb_noun (list_documents, open_document, apply_plan, compare_documents), which is very consistent. The only friction is the minimal pair edit_document/edit_documents, where a single character separates a single-document tool from a bulk tool.
Sixteen tools is on the heavy side, but the domain is broad: three document formats, connections, templates, plans, merge, compare, and workbook refresh. Each tool maps to a recognizable workflow, though the duplicate primitive/composite layers mean a few could be consolidated rather than added.
Read, inspect, find, edit, preview, apply, compare, merge, refresh, and template discovery are all covered, plus removal of a registration. However, create_document is repeatedly referenced by list_documents and find_templates as the consumer of a template source but is not actually present, and there is no delete/export path, leaving a dead end for new-document creation.