Skip to main content
Glama

compare_documents

Read-only

Compare two DOCX or ODT files, or a file against session edits, and save the differences as a tracked-changes output document.

Instructions

Compare two documents and produce a tracked-changes output document. Provide original_file_path + revised_file_path for standalone comparison, or file_path to compare session edits against the original. DOCX and ODF (.odt) support both modes. DOCX output always uses the revised archive as its package base and publishes tagged revisions; engine, strategy, reconstruction, premerge, and refinement selectors are not exposed. DOCX stats count insertions/deletions as contiguous ranges, expose tagged-token-v1 totals as insertedAtoms/deletedAtoms with atomMetricVersion, report formatChanges separately from modifiedParagraphs, and report detected moves as moves/movedParagraphs with moveFromRanges/moveToRanges (moved content is not also counted as insertions or deletions, so a pure move reports moves > 0 with zero insertions/deletions). When a DOCX input difference is preserved in the output without tracked-change markup (for example a removed section's header or footer, or an unsupported header/footer topology), the response includes unrepresented_changes (objects with scope, kind, sectionIndex, for header/footer scopes role, and for the contentControl scope a contentControl identity: a changed w:sdtPr/w:sdtEndPr is published as the revised properties without markup, because CT_SdtPr admits no revision elements) plus one warnings string per entry, and the message carries a WARNING. Both fields are absent when no reportable unrepresented change was detected; the detector covers section properties, selected header/footer stories and content-control properties, so absence is not a guarantee about differences outside that scope. ODF compares at inline granularity (a modified paragraph is marked up in place — only the changed spans are struck or inserted).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "save_to_local_path": "<save_to_local_path>"
    },
    "name": "compare_documents"
  }
}

Input Schema

NameRequiredDescriptionDefault
authorNoAuthor name for track changes. Default: 'Comparison' (DOCX) or the configured AI author (ODF).
file_pathNoPath to the DOCX or ODT file.
compare_movesNoDetect moved content (DOCX only). Default: true.
ignore_formattingNoIgnore formatting differences (DOCX only). Default: false.
revised_file_pathNoPath to the revised DOCX or .odt file.
revision_groupingNoHow DOCX revisions are grouped. 'readable-semantic' (default) shows each rewritten passage as one deletion followed by one insertion, absorbing short unchanged words, spaces and punctuation between changes; runs keep their own formatting, and moves, fields, bookmarks, comment ranges and note references are never absorbed. 'token-minimal' emits the smallest word-level deletion/insertion set, which alternates word by word in heavily rewritten paragraphs. Accept All and Reject All results are the same either way. DOCX only.
original_file_pathNoPath to the original DOCX or .odt file.
save_to_local_pathYesPath to save the tracked-changes output (DOCX or .odt).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.25.1
    • addedInput schema / properties / revision_grouping
      Added value: +{
      +  "description": "How DOCX revisions are grouped. 'readable-semantic' (default) shows each rewritten passage as one deletion followed by one insertion, absorbing short unchanged words, spaces and punctuation between changes; runs keep their own formatting, and moves, fields, bookmarks, comment ranges and note references are never absorbed. 'token-minimal' emits the smallest word-level deletion/insertion set, which alternates word by word in heavily rewritten paragraphs. Accept All and Reject All results are the same either way. DOCX only.",
      +  "enum": [
      +    "readable-semantic",
      +    "token-minimal"
      +  ],
      +  "type": "string"
      +}
  2. Changed3 schema fields changedv0.21.2
    • addedInput schema / properties / compare_moves
      Added value: +{
      +  "description": "Detect moved content (DOCX only). Default: true.",
      +  "type": "boolean"
      +}
    • removedInput schema / properties / engine
      Removed value: -{
      -  "description": "Comparison engine (DOCX only). Default: 'auto'.",
      -  "enum": [
      -    "auto",
      -    "atomizer"
      -  ],
      -  "type": "string"
      -}
    • addedInput schema / properties / ignore_formatting
      Added value: +{
      +  "description": "Ignore formatting differences (DOCX only). Default: false.",
      +  "type": "boolean"
      +}
  3. Changed6 schema fields changedv0.12.1
    • changedInput schema / properties / author / description
      Previous value: -"Author name for track changes. Default: 'Comparison'."New value: +"Author name for track changes. Default: 'Comparison' (DOCX) or the configured AI author (ODF)."
    • changedInput schema / properties / engine / description
      Previous value: -"Comparison engine. Default: 'auto'."New value: +"Comparison engine (DOCX only). Default: 'auto'."
    • changedInput schema / properties / file_path / description
      Previous value: -"Path to the DOCX file."New value: +"Path to the DOCX or ODT file."
    • changedInput schema / properties / original_file_path / description
      Previous value: -"Path to the original DOCX file."New value: +"Path to the original DOCX or .odt file."
    • changedInput schema / properties / revised_file_path / description
      Previous value: -"Path to the revised DOCX file."New value: +"Path to the revised DOCX or .odt file."
    • changedInput schema / properties / save_to_local_path / description
      Previous value: -"Path to save the tracked-changes DOCX output."New value: +"Path to save the tracked-changes output (DOCX or .odt)."
  4. First observed

TDQS

A3.6/5.0
Behavior1/5

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

The description says the tool produces a tracked-changes output document and requires save_to_local_path, which is a filesystem write operation. The annotations declare readOnlyHint=true, so the description contradicts the structured safety signal. Apart from that contradiction, the description adds unusually rich behavioral context about DOCX/ODF behavior, output packaging, stats, warnings, and unrepresented changes.

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

Conciseness3/5

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

The core purpose and input modes are front-loaded, which is good. However, the description is long and dense with internal implementation details such as tagged-token-v1, insertedAtoms/deletedAtoms, atomMetricVersion, and w:sdtPr/w:sdtEndPr, which are not necessary for selecting or invoking the tool.

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

Completeness4/5

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

For a complex comparison tool with no output schema, the description covers modes, output behavior, DOCX/ODF differences, stats reporting, and unrepresented-change warnings. It is substantially complete for correct invocation. It could still be clearer about whether source files are modified and about the exact response shape outside the specific warning fields.

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

Parameters4/5

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

Schema coverage is 100%, so all eight parameters are already documented. The description adds meaning beyond the schema by explaining the mutually exclusive input modes and by clarifying that DOCX and ODF support both modes. It does not explain every parameter in detail, but the mode-level guidance is valuable.

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 a specific verb and resource: 'Compare two documents and produce a tracked-changes output document.' It clearly distinguishes two operating modes: standalone comparison via original_file_path + revised_file_path, or session comparison via file_path. This is enough for an agent to identify the tool's role without opening 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 explicitly states which parameter combinations select standalone comparison versus session-edit comparison, which is the key usage decision for this tool. It does not name alternatives such as extract_revisions or has_tracked_changes, so it stops short of full when-to-use/when-not guidance.

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