# compare_diagrams

> Page: https://docs.plotwork.dev/mcp/tools/compare-diagrams. Index of every page: https://docs.plotwork.dev/llms.txt

Compare two versions of a diagram by meaning, for a pull request review. It is a single tool of the MCP server and the HTTP API, with the title "Compare diagrams".

## TL;DR

| Question | Answer |
|---|---|
| What is it? | A single tool: it does one thing. |
| What does it do? | Compare two versions of a diagram by meaning, for a pull request review. |
| How do I call it over HTTP? | [`POST /v1/diagrams/compare`](https://docs.plotwork.dev/api/post-v1-diagrams-compare.md) |
| Does it change anything? | No. It is read-only and idempotent. It saves no file and returns its answer as data. |
| Which bounds apply? | `maxCompareChanges`. See the bounds below. |
| Where do I read its schema as data? | An MCP client gets the name, description, and JSON Schema of every tool from `tools/list`. |

## What it does

Compare two versions of a diagram by meaning, for a pull request review. Send before and after, each as source, the text of a Plotwork SVG that carries its source, or a cdn.plotwork.dev link. Returns every statement added, removed, renamed (by id or label), moved to another block, or changed (options, type, edge arrow or label), with counts and a plain-language summary; markdown true adds a block ready to paste as a comment. Reordered or reformatted lines are no change. A side with no source is reported, not an error. Lays nothing out; fetches only a link.

## Arguments

| Field | Type | Required | Description |
|---|---|---|---|
| `before` | `string` | yes | The old diagram: source, the text of a Plotwork SVG that carries its source, or a cdn.plotwork.dev link. at least 1 character; at most 1000000 characters. |
| `after` | `string` | yes | The new diagram, in any of the same three forms. at least 1 character; at most 1000000 characters. |
| `markdown` | `boolean` | no | Also return a Markdown block ready to paste as a pull request comment. default false. |

## Result

| Field | Type | Required | Description |
|---|---|---|---|
| `same` | `boolean` | yes |  |
| `before` | `object` | yes |  |
| `before.from` | `"source" \| "svg" \| "url"` | yes |  |
| `before.read` | `boolean` | yes | False when no source could be read from it; message says why. |
| `before.kind` | `string \| null` | yes |  |
| `before.valid` | `boolean` | yes |  |
| `before.message` | `string \| null` | yes |  |
| `after` | `object` | yes |  |
| `after.from` | `"source" \| "svg" \| "url"` | yes |  |
| `after.read` | `boolean` | yes | False when no source could be read from it; message says why. |
| `after.kind` | `string \| null` | yes |  |
| `after.valid` | `boolean` | yes |  |
| `after.message` | `string \| null` | yes |  |
| `counts` | `object` | yes |  |
| `counts.added` | `integer` | yes |  |
| `counts.removed` | `integer` | yes |  |
| `counts.renamed` | `integer` | yes |  |
| `counts.moved` | `integer` | yes |  |
| `counts.changed` | `integer` | yes |  |
| `changes` | `object[]` | yes |  |
| `changes[].change` | `"added" \| "removed" \| "renamed" \| "moved" \| "changed"` | yes |  |
| `changes[].subject` | `"header" \| "node" \| "group" \| "edge" \| "row" \| "series" \| "line"` | yes |  |
| `changes[].name` | `string` | yes | The id, the label in quotes, or for an edge its ends. |
| `changes[].line` | `integer \| null` | yes | The line in after, or in before for a removal. |
| `changes[].detail` | `string` | yes |  |
| `truncated` | `boolean` | yes | True when more changes were found than are listed; counts covers all of them. |
| `summary` | `string` | yes | The changes in plain words, for a pull request review. |
| `markdown` | `string \| null` | yes |  |
| `next` | `string` | yes |  |

## Behavior hints

| Hint | Value |
|---|---|
| `readOnlyHint` | true |
| `destructiveHint` | false |
| `idempotentHint` | true |
| `openWorldHint` | true |

## Bounds

A bound that is reached is reported in the result; nothing is cut silently.

| Bound | Value | What it limits |
|---|---|---|
| `maxCompareChanges` | 200 | Changes listed in one answer; counts and the summary cover every change. |

## See also

| Doc | Why |
|---|---|
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | Every tool, with the workflows first |
| [`POST /v1/diagrams/compare`](https://docs.plotwork.dev/api/post-v1-diagrams-compare.md) | The same operation over HTTP |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | What the diagram source may contain |
| [Writing diagrams with an agent](https://docs.plotwork.dev/mcp/agent-loop.md) | The loop in practice |