Paperboy

Official

Overview Schema Source Related Servers Discussions Admin

compare_pdfs

Read-onlyIdempotent

Compare two PDF versions page by page to detect changed pages, lines, and visual differences in text or colour, with options for passwords and case-insensitive matching.

Instructions

Compare two versions of a PDF (A, the older, and B, the newer) page by page.

Pages are matched first, by their text, so a page inserted or deleted (or page-number footers shifting) doesn't make every later page look changed; reordered pages show as removed and added. mode "text" compares each matched page's text and lists the lines removed and added (lines shown as written; up to 50 per page and 50,000 characters in all); "visual" matches pages by position and compares how they look, in colour (the % of pixels that differ), returning images of the most changed pages with what was removed in red, added in green and recoloured in blue; "both" matches by text and does both. Pages with no text (e.g. scans) can only be compared visually; in text mode they are "unknown". Whitespace and Unicode forms are ignored; ignore_case ignores case too. complete is false if the 60 s limit stopped some pages being compared. Needs the owner password of a PDF that forbids copying, except in visual mode. Nothing is written to disk.

Any password argument can be "ask": the user then types it on a local page, so it never passes through the chat.

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": {
      "path_a": "<path_a>",
      "path_b": "<path_b>"
    },
    "name": "compare_pdfs"
  }
}

Input Schema

Name	Required	Default
`mode`	No	text
`path_a`	Yes
`path_b`	Yes
`password_a`	No
`password_b`	No
`ignore_case`	No

Output Schema

Name	Required	Description	Default
`mode`	Yes
`same`	Yes
`added`	Yes
`images`	Yes
`path_a`	Yes
`path_b`	Yes
`changed`	Yes
`pages_a`	Yes
`pages_b`	Yes
`removed`	Yes
`unknown`	Yes
`complete`	Yes
`identical`	Yes
`truncated`	Yes
`differences`	Yes
`pages_skipped`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.1Nov 12, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Goes well beyond the readOnly/idempotent annotations: discloses the 60 s budget and the 'complete: false' signal, output caps (50 lines per page, 50,000 characters), that changed-page images are returned with red/green/blue diff coloring, that nothing is written to disk, and the password handling including the 'ask' local-prompt flow. The only gap is that it does not describe the overall response structure, though an output schema exists to cover that.

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

Conciseness4/5

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

Purpose is front-loaded in the first clause and every following sentence carries operational information rather than filler. It is dense and long-sentenced, but trimming would lose real semantics such as the diff color coding or the truncation limits.

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?

For a six-parameter comparison tool with no schema descriptions, the definition covers inputs, mode semantics, edge cases (scans, reordered pages, footer shifts), limits, partial-completion signaling, and password handling. Nothing an agent needs to call it correctly is missing.

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?

With 0% schema description coverage, the description carries the full load and does so: it defines the three 'mode' values even though the schema has no enum, explains what ignore_case does alongside the default whitespace/Unicode normalization, clarifies path_a/path_b as older/newer, and explains password_a/password_b including the 'ask' option.

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?

States a specific verb and resource plus the ordering convention ('Compare two versions of a PDF (A, the older, and B, the newer) page by page'), which immediately tells an agent what the tool does and how to order its inputs. The page-matching semantics (text-based vs position-based) further distinguish it from any listing or extraction sibling.

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?

Gives explicit mode-selection guidance: 'text' compares matched page text, 'visual' matches by position and compares appearance, 'both' does both. It also states a hard when-not condition — pages with no text such as scans 'can only be compared visually' and appear as 'unknown' in text mode — and notes the owner-password requirement except in visual mode.

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