Skip to main content
Glama
sontanon

docx-mcp

by sontanon
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

validate_document_tool

Read-onlyIdempotent

Validate .docx files for structural issues to ensure they open correctly in Word and have properly formed tracked changes and comments. Use after applying changes or when debugging document corruption.

Instructions

Check a .docx file for structural issues.

Runs validation checks on the document's OOXML structure to ensure it will open correctly in Microsoft Word and that all tracked changes and comments are properly formed.

Use this tool:

  • After calling apply_changes to verify the redlined document is valid (automatically enabled by default via validate=True parameter)

  • When debugging a document that won't open correctly in Word

  • When verifying that an existing redlined document has proper structure

Validation Checks

  • Annotation ID isolation: Tracked-change and comment IDs must not collide across groups. Each <w:ins>, <w:del>, and <w:comment> needs a globally unique ID within the document.

  • Comment integrity: Every <w:comment> in comments.xml must have matching <w:commentRangeStart> / <w:commentRangeEnd> markers in the document body, and vice versa.

  • Tracked-change attributes: Every <w:ins> and <w:del> must have required attributes: w:id (unique ID), w:author (author name), and w:date (timestamp).

  • Package consistency: Content-type and relationship entries must be present in the .docx ZIP structure when comments.xml exists.

Example Output

Success case::

"Validation: passed (0 errors, 0 warnings)."

Failure case::

"Validation: FAILED (2 error(s), 1 warning(s)).
  Error 1: Annotation ID collision: ID 5 used by both tracked change and comment
  Error 2: Orphaned comment range: commentRangeStart with id=3 has no matching end
  Warning 1: Comment with id=7 is not referenced by any comment range"

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
document_pathYesAbsolute path to the .docx file to validate.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Tool Definition Quality

A4.7/5.0
Behavior5/5

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

Annotations (readOnlyHint: true, idempotentHint: true) are complemented by detailed behavioral descriptions: it lists the four specific validation checks (annotation ID isolation, comment integrity, tracked-change attributes, package consistency) and provides example success/failure output. This goes far beyond annotation hints and gives a clear picture of what the tool does, with no contradictions.

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 well-structured with clear headers, bullet points for validation checks, and code blocks for example output. Although somewhat long, every section adds value and the main purpose is front-loaded in the first sentence. No redundant or filler content.

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 tool's simplicity (one parameter, full schema coverage, no nested objects) and the presence of an output schema, the description is more than complete. It covers purpose, usage scenarios, validation checks, and example output, leaving no significant gaps for an agent to misuse the tool.

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

Parameters3/5

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

The input schema already provides 100% coverage of the single parameter document_path, including a description ('Absolute path to the .docx file to validate'). The tool description adds no additional semantics about this parameter, so baseline 3 applies.

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 opens with 'Check a .docx file for structural issues' and elaborates on validating OOXML structure for Word compatibility, tracked changes, and comments. This is a specific verb+resource statement that thoroughly distinguishes its scope from sibling tools, especially audit_document_tool, by listing the exact validation checks.

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

Usage Guidelines5/5

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

The description includes an explicit 'Use this tool:' section listing three concrete scenarios (after apply_changes, debugging open failures, verifying existing redlined documents). It also notes that validation is automatically enabled via validate=True in apply_changes, effectively communicating when the tool may not need to be called separately.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sontanon/docx-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server