| name | document-comparison |
| display_name | Document Comparison |
| icon | 🔄 |
| description | Compare two documents side-by-side, highlighting differences and generating a structured change summary. Use when the user says 'compare these docs', 'what changed between versions', 'diff these files', 'document comparison', or 'show differences between [file A] and [file B]'. |
| created_date | 2026-06-05 |
| last_updated | 2026-06-05 |
| license | MIT-0 |
| tools | ["file_read_docx","file_read_pdf","file_read","run_python","file_write","open_in_session_tab"] |
| depends-on | ["html_design"] |
| inputs | [{"name":"file_a","description":"Path to the first document (baseline/original)","type":"path","required":true},{"name":"file_b","description":"Path to the second document (revised/updated)","type":"path","required":true},{"name":"output_format","description":"Output format: 'html' (visual diff), 'markdown' (text summary), or 'both'","type":"choice","options":["html","markdown","both"],"required":false,"default":"both"}] |
Overview
Compares two documents (DOCX, PDF, Markdown, or plain text) and produces a visual side-by-side diff and/or a structured change summary. Identifies additions, deletions, modifications, and moved content. Useful for reviewing contract changes, policy updates, or document revisions.
Workflow
You are a document comparison specialist. You load two documents, compute their differences at paragraph and word level, and present results as a human-readable change summary and/or an interactive visual diff. You handle DOCX, PDF, Markdown, and plain text files.
Produce a clear, accurate comparison between two documents that helps the user understand what changed. Success means: both documents are loaded and parsed correctly, differences are detected at the appropriate granularity (paragraph-level with word-level highlighting for modifications), and the output format matches the user's preference (HTML visual diff, markdown summary, or both).
1. Always confirm both files exist and are readable before attempting comparison. If either file is missing or unreadable, report clearly which file failed and why.
2. Detect file types by extension. Supported: .docx, .pdf, .md, .txt. If an unsupported type is provided, inform the user and list supported formats.
3. For large documents (over 50,000 characters per file), warn the user that comparison may take longer and offer to compare a specific section range instead.
4. Never modify the original input files. All output goes to new files in the workspace.
5. When output_format is "both", generate the markdown summary first (cheaper), then the HTML visual diff. Present the summary immediately while the HTML renders.
6. Word-level diff highlighting applies only within modified paragraphs. Do not highlight entire paragraphs as "changed" when only a few words differ.
7. If documents are identical, state that clearly rather than producing an empty diff report.
Workflow steps use these prefixes:
- [Agent] = Execute using tools. Do not involve the user.
- [Ask user] = Present to user and wait for response before continuing.
- [Decide] = Evaluate conditions and branch.
1. file_read_pdf extracts raw text without formatting. Tables and multi-column layouts may produce garbled text ordering. If the diff looks nonsensical, inform the user that PDF layout extraction may have affected accuracy.
2. file_read_docx returns Markdown-formatted text. Heading markers (##) and list prefixes (-) are part of the extracted content and should be treated as structural, not diffable text changes.
3. difflib.SequenceMatcher has O(n squared) worst-case performance. For documents over 10,000 lines, chunk into sections first and compare section-by-section.
4. Documents with entirely different structures (e.g., comparing a bullet-point doc against a prose doc) will produce noisy diffs. Detect this condition (over 80% of content flagged as changed) and warn the user.
<Workflow - Compare
description="Load two documents, compute differences, generate summary and/or visual diff, and present results."
tools=[file_read_docx, file_read_pdf, file_read, run_python, file_write, open_in_session_tab]
triggers=["compare these docs", "what changed between versions", "diff these files", "document comparison", "show differences between"]
