AutoCAD MCP Pro

Overview Schema Source Related Servers Discussions Admin

Drawing: Diff Two Revisions

drawing_diff

Compare two drawing revisions by geometric signature to report changed, added, and removed entities by layer and type, optionally marking change clusters with revision clouds.

Instructions

Compare two revisions of one drawing by geometric signature (spec §10).

Entities are matched exactly first (type, layer, geometry rounded to tol, text, block, attributes - handles do not matter), then by handle while handles look stable, then by type + layer + nearest position within move_tol; what is left is added or removed. The report counts changes by layer and type, lists each changed entity with what changed (moved by, text from -> to, attribute from -> to, radius from -> to, ...), compares the block definitions when both revisions are DXF files or the headless current document, and groups the changes into clusters.

Read-only unless markup=True: then revision clouds are drawn around the model-space clusters on the current document, which must be the newer revision, and filed as one revision row - the only write this tool makes.

Refused before anything is read: markup=True with new_path (the clouds go on the current document), markup=True without a valid rev, markup=True on an engine without the revcloud capability (the live engine - capability: "revcloud"), a path that does not exist, a DXF over MAX_DXF_BYTES (the size and the variable named), a file that is not a readable DXF, and a non-positive tol or move_tol.

Input Schema

TableJSON Schema

Name	Required	Description
`rev`	No	Revision code for markup=True: one to three capitals or digits.
`tol`	No	Geometry is compared rounded to this many drawing units.
`limit`	No	Rows kept per list (changed, added, removed).
`markup`	No	Draw revision clouds around every cluster of change on the current document (the newer revision) and file them under `rev`.
`move_tol`	No	An unmatched entity is paired with the nearest one of its type and layer within this distance and reported as changed; default 2 % of the drawing's robust diagonal.
`new_path`	No	The NEWER revision: a DXF path, or omitted for the current document.
`old_path`	Yes	The OLDER revision: a DXF path (a DWG only on the live engine, which exports it read-only).
`description`	No	Revision-row text for markup=True; default: the counts.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.6.0Sep 28, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only supply destructiveHint=false, so the description carries the burden and does so richly: it discloses the matching algorithm and fallback strategy, the one write it performs (revision clouds + one revision row), engine capability requirements ('revcloud'), MAX_DXF_BYTES limits, and the full list of pre-read refusals. This is far beyond what the annotation states.

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?

Three tight paragraphs, front-loaded with the core comparison semantics before the markup caveat and the refusal list. Dense but each sentence carries weight; the refusal enumeration is long but operationally useful for an agent deciding whether a call will succeed.

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?

An output schema exists, so return values need not be re-specified, yet the description still summarizes the report shape (per-layer/type counts, per-entity change detail, block-definition and cluster grouping). Combined with the algorithm and refusal documentation, an agent has everything needed to invoke this correctly.

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 the baseline is 3, but the description adds real meaning: it explains how `tol` participates in the exact-match stage, how `move_tol` pairs leftover entities, and how `markup`/`new_path`/`rev` interact (markup=True with new_path is refused). That cross-parameter interaction is not derivable from the schema alone.

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?

Opens with a specific verb+resource and scope: 'Compare two revisions of one drawing by geometric signature.' No sibling tool performs a revision diff, and the description makes the entity-matching basis explicit, so the agent can distinguish it from audits, validation, or drawing_understand.

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?

The description gives strong context: it explains that the tool is read-only unless markup=True, that markup requires the current document be the newer revision and a valid `rev`, and it enumerates refusal conditions. It does not, however, explicitly route between this tool and adjacent diagnostics (drawing_audit, validation_check, drawing_understand), so it stops just short of full when/when-not guidance.

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

Deploy Server