Extract text from a .docx file as tagged fragments.

Call this first to get fragment IDs, then use those IDs in ``apply_changes``.

Output format::

    <f=1>**Title**</f=1>
    <f=2>Body paragraph.</f=2>
    <table=3 rows=2 cols=3>
    <cell=3.1.1>Header</cell=3.1.1>
    <cell=3.1.2 span="2">Merged cell</cell=3.1.2>
    </table=3>

Fragment IDs:
  - Body: ``"1"``, ``"2"``, ...
  - Headers: ``"header_1.1"``, ``"header_1.2"``, ...
  - Footers: ``"footer_1.1"``, ``"footer_2.1"``, ...
  - Table cells: ``"table_id.row.col"`` (e.g., ``"3.1.2"``)

Formatting: ``**bold**``, ``_italic_``, ``__underline__``. ``

`` for paragraph breaks.

Limitations:
  - Images, nested tables, VML text boxes are skipped.
  - Pre-existing tracked changes are hard-rejected.

Args:
    document_path: Absolute path to the .docx file.

Returns:
    Tagged text string with fragment and table markup.

Apply tracked changes to a .docx file and save a new redlined document.

Produces Word-compatible tracked changes (``w:ins`` / ``w:del``) with comments.
Always call ``extract_fragments`` first to get fragment IDs.

Paragraph changes (use ``fragment_id``):
  - ``modify``: Word-level diff. ``new_text`` required.
  - ``delete``: Marks paragraph deleted. Omit ``new_text``.
  - ``append_after``: Insert after target. ``new_text`` required.

Table changes (use ``cell_id`` like ``"2.1.3"``):
  - ``modify_cell``: Replace cell text. ``new_text`` required. Use ``

for multi-paragraph cells. -clear_cell: Delete cell content. Omit new_text``.

Rules:
  - ``delete_next_blanks`` only with ``delete``.
  - ``blank_lines_before`` / ``blank_lines_after`` only with ``append_after``.
  - Header/footer changes work but comments are silently dropped.
  - Documents with pre-existing tracked changes are hard-rejected.

``new_text`` uses pseudo-Markdown: ``**bold**``, ``_italic_``, ``__underline__``.

Example::

    changes = [
        {
            "fragment_id": 1,
            "change_type": "modify",
            "new_text": "**Updated title**",
            "justification": "Fixed typo"
        },
        {
            "cell_id": "2.1.1",
            "change_type": "modify_cell",
            "new_text": "New header",
            "justification": "Clarified"
        }
    ]

Args:
    document_path: Absolute path to the input .docx file.
    changes: List of change objects (paragraph or table cell changes).
    output_path: Where to save the redlined document. Defaults to
        ``<stem>_redlined.docx`` beside the input file.
    author: Author name for tracked changes and comments. Defaults to
        "AI Review".

Returns:
    Summary string with change counts, output path, and validation result.

Same as apply_changes but reads the change list from a JSON file.

Useful for large change sets that would exceed token limits in a direct tool call, or for reusing a change set across multiple runs.

The JSON file must contain either a bare array of change objects, or an object with a "changes" key::

 [
   {"fragment_id": 1, "change_type": "modify", "new_text": "..."},
   {"cell_id": "2.1.1", "change_type": "modify_cell", "new_text": "..."}
 ]

See apply_changes for change object schema and rules.

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"

Audit a .docx file for structural issues and skipped content.

Reports headers, footers, images, tables, section breaks, tracked changes, comments, and unsupported elements (footnotes, endnotes, text boxes).

Compare two .docx files and show paragraph and table-level text differences.

Extracts the pseudo-Markdown text from each paragraph and table cell in both documents, then produces a word-level diff for each fragment position. This is useful for understanding what changed between two versions of a document.

Use this tool:

• To compare an original document with its redlined version (see what changes were applied)

• To verify that apply_changes produced the expected modifications

• To understand differences between two versions of a document

Important Limitations

Fragments are matched by position (fragment 1 vs fragment 1, fragment 2 vs fragment 2, etc.). This tool does not detect fragment reordering or track moved sections. If the documents have very different structures (different fragment counts, major reordering), the output will show extensive changes.

Best used for comparing documents with the same basic structure where you made local edits (word changes, clause deletions, appended sections, table cell modifications).

Output Format

Each fragment is reported with its change status.

Paragraphs::

Fragment 1: unchanged
Fragment 2: modified
  - shall deliver
  + must deliver immediately
Fragment 3: unchanged
Fragment 5: deleted (only in original)
  - This clause is removed.
Fragment 10: added (only in modified)
  + This is a new clause.

Tables::

Table 56: modified
  Cell 56.2.2: modified
    - Gwendolyn Mahon, M.Sc., Ph.D
    + John H. Smith, Ph.D.
Table 57: unchanged
Table 58: dimensions changed (3x2 → 4x2)

Lines starting with - show deleted text, + shows inserted text. Unchanged fragments are listed but their text is omitted for brevity.

For tables, each modified cell is shown with its cell ID (table_id.row.col) followed by the word-level diff of the cell content.

Difference from extract_fragments

• extract_fragments shows the plain text of a single document (paragraphs, headers, footers, tables). Pre-existing tracked changes cause a hard rejection.

• diff_fragments compares two separate documents and computes the differences between their plain text (ignoring any tracked changes)