Skip to main content
Glama
xsnj-9527

docs-mcp

by xsnj-9527
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Edit a .docx

docx_edit
Destructive

Apply text, paragraph, and metadata edits to Microsoft Word .docx files, then write the updated document back in place or to a new path.

Instructions

Apply edits to a Microsoft Word .docx document and write the result back.

Call docx_read first to learn paragraph indices. All index values refer to the ORIGINAL document as docx_read reported it — operations are applied together, so earlier operations never shift the indices of later ones.

Operations:

  • {op:"replace_text", find, replace, all?} — replace text inside a paragraph, matching across formatting runs so the surrounding formatting is preserved. Works on the whole document unless you set all:false, in which case only the first occurrence is replaced. A match spanning a tab or line break is refused; use replace_paragraph for those.

  • {op:"replace_paragraph", index, text} — replace one paragraph's whole text, keeping the formatting of its first run.

  • {op:"insert_paragraph_after", index, text, style?} — insert a new paragraph after the given index; use index 0 to insert at the very start. style takes a style id such as Heading1.

  • {op:"delete_paragraph", index} — remove a paragraph (inside a table it becomes an empty one, because a table cell must keep at least one paragraph).

  • {op:"set_metadata", title?, subject?, creator?, keywords?, description?, lastModifiedBy?} — update the document properties.

By default the file is modified in place, and the first in-place edit leaves a one-time backup next to it as ".orig.docx". Pass output_path to write elsewhere instead, or dry_run:true to see what would change without writing anything.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYesPath to the .docx to modify.
dry_runNoReport what would change without writing anything.
operationsYesEdits to apply, in order.
output_pathNoWrite the result here instead of modifying path in place.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds substantial behavioral context beyond that: in-place edits, a one-time .orig.docx backup, output_path redirection, dry_run behavior, and operation ordering semantics that keep indices tied to the original document.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but appropriately structured for a multi-operation editing tool, front-loading the purpose and prerequisite before listing operations and write-behavior details. Every section earns its place by clarifying either an operation, an index rule, or a file-write effect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description still covers the essential invocation and side-effect details an agent needs: required path and operations, operation ordering, backup behavior, dry-run reporting, and alternate output destination. There is no obvious missing context that would cause misuse.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline would be 3, but the description materially enriches parameter meaning. It explains each op's find/replace/all behavior, index semantics for paragraph operations, style id usage, and edge cases like table-cell paragraph deletion and refused matches across tabs or line breaks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: apply edits to a Microsoft Word .docx document and write the result back. It explicitly tells the agent to call docx_read first, which distinguishes this tool from the read sibling and makes its editing scope clear without needing the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operational context, including the prerequisite to call docx_read first and an explicit alternative when a text match spans a tab or line break: use replace_paragraph. It does not compare docx_edit against docx_create or state when not to use this tool, so it falls short of full when/when-not/alternatives guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools