compare_diagrams
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 |
| 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 | Every tool, with the workflows first |
POST /v1/diagrams/compare | The same operation over HTTP |
| Language reference | What the diagram source may contain |
| Writing diagrams with an agent | The loop in practice |