Exposes diagonaldiagrams as tools to describe figure contracts, validate inputs, render and audit diagrams, audit SVGs, export rendered figures, and infer scatter specs.
describe: list supported figure types or get the spec shape, flags, and budgets for one type.
render: validate, draw, and audit one figure from Mermaid, a JSON spec, inline CSV, or a file; writes SVG, HTML, and a receipt with ok, layout, and fixes for errors.
validate: check a spec or CSV without drawing.
audit: check any SVG for collisions, clipping, and arrows through boxes.
export: write png, pdf, or svg from a rendered figure's receipt.
infer: propose a scatter spec from a CSV.
Exports rendered diagrams to Excalidraw format, preserving boxes, frames, and routed arrows so users can open and edit the figure in Excalidraw.
Accepts Mermaid flowchart, sequenceDiagram, and erDiagram input and renders them into audited diagrams.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@diagonaldiagrams turn this Mermaid flowchart into an SVG and audit it for overlapping labels: A-->B; B-->C"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Diagrams and charts an agent can draw, and check, before it shows you. One command takes Mermaid, a short JSON spec, or a CSV, lays it out, draws an SVG, and audits the drawing for labels on labels, arrows through boxes, and text that spills.
Try it in the browser. The real engine, running in the page.
Each one passed its audit, then was filmed. The specs are in examples/showcase/.
Related MCP server: excalidraw-mcp
Claude Code, as a plugin:
/plugin marketplace add lucas19919/diagonaldiagrams
/plugin install diagonaldiagrams@diagonaldiagramsAny agent, as a command:
pip install git+https://github.com/lucas19919/diagonaldiagrams
diagonaldiagrams mermaid flow.mmd -o out/flow.svgThe command prints one line of JSON. ok: true means the audit passed, and layout says what was drawn, so the agent can check the figure without a screenshot. ok: false comes with errors, each with a fix.
--fit column is the size for a README or a docs page. slide, the default, wraps a long flow for a deck. page is for print.
From a checkout, py -3 graph.py takes the same arguments. Agents install with .agents/skills/diagonaldiagrams-install/SKILL.md and draw with .agents/skills/graph-engine/SKILL.md. The short version is llms.txt.
diagonaldiagrams 0.8.0 against Mermaid CLI and Pele, on 2026-10-19. The same four flowcharts, 5, 11, 20 and 40 steps. The method is in bench/.
Milliseconds for one figure, a new process each time. diagonaldiagrams was remeasured the same day: median of 7 calls, from bytecode (bench/speed/cli-2026-10-19.json). Pele and Mermaid CLI are that day's earlier run, not rerun.
5 steps | 11 steps | 20 steps | 40 steps | |
Pele, a new process | 95 | 104 | 101 | 107 |
diagonaldiagrams | 136 | 142 | 152 | 154 |
Mermaid CLI | 2,333 | 2,399 | 2,340 | 2,556 |
A diagonaldiagrams call is about 1.4 times a Pele process, and about 16 times faster than Mermaid CLI. Mermaid starts Node and a browser on every call. Pele only draws. diagonaldiagrams also audits the drawing and writes the page and the receipt.
Each point is a fresh Claude Sonnet agent with one prose task and nothing else. Two runs. Tokens are what the agent wrote, what came back, files it read, and screenshots. The harness and thinking are left out.
Steps | diagonaldiagrams | Mermaid CLI | Pele |
5 | 4.4k | 1.8k | 2.6k |
11 | 6.0k | 2.8k | 1.7k |
20 | 5.1k | 4.0k | 1.3k |
40 | 6.4k | 15.4k | 6.3k |
All eight runs:
Tokens | Calls | Screenshots | Time | |
Pele | 23.9k | 57 | 18 | 5 min |
diagonaldiagrams | 43.8k | 69 | 9 | 7 min |
Mermaid CLI | 47.8k | 79 | 32 | 13 min |
Pele cost the least, because the model already knows Mermaid and reads no skill. diagonaldiagrams stays about the same at every size. Of its tokens, about 1.4k a run is reading the skill. Mermaid CLI grows fastest, and at 40 steps most of its tokens are screenshots of a figure several thousand pixels tall. Every one of the 24 figures passed this audit. Two runs is a small sample: single runs differed by up to 3.5 times.
An earlier run, on 0.5.0 (2026-10-04), had different prompts and is not comparable. It is in docs/data/bench_tools.csv.
Blind pairs. Two judges, both orders, two questions: which is clearer, and which looks better. The chart is the share diagonaldiagrams won on clarity; past the 50% line it won.
vs Pele | vs Mermaid | |
On a slide, every figure | 85% (106/124) | 97% (120/124) |
In a column, flows, each of 5, 11, 20, 40 steps | 100% (16/16) | 100% (16/16) |
In a column, architecture we wrote | 75% (6/8) | 88% (7/8) |
In a column, that architecture translated from Mermaid | 0% (0/8) | 50% (4/8) |
The column numbers are after --fit column, which keeps a README column near full-size text. The translated-architecture loss is one figure: the agent platform won 4 of 4 against Mermaid, and the checkout groups won none against either tool.
Command | Input | Draws |
|
| A flow, a sequence, or a schema |
| JSON | The same four, from a spec |
| CSV | A comparison, a trend, a relationship |
| CSV or GeoJSON | Places on a built-in coastline |
| CSV or JSON | About 60 more |
describe <type> prints the contract. diagonaldiagrams story SPEC.json -o out/story.html walks through one figure. --gif OUT.gif films a view when ffmpeg is on the PATH. An edit is a JSON patch (apply), and export OUT --to png|pdf|drawio|excalidraw writes other formats.
py -3 tests_smoke.py
py -3 scripts/golden.py
py -3 scripts/build_site.pyExit 0 on the first is the contract an agent relies on. The second compares 115 figures. The third rebuilds the site, and refuses a figure that fails its audit. How the engine is put together, for contributors: docs/ARCHITECTURE.md.
MIT. See LICENSE.
Check any SVG for collisions, clipping, and arrows through boxes.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the three issue categories it detects but says nothing about whether the operation is read-only, whether it reports or mutates, what the output looks like, or any performance/limit characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no waste; the scope of checks is stated immediately. It is efficient, though it is arguably too terse given the surrounding gaps rather than genuinely concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description should explain what the audit returns (report, pass/fail, issue list) and how the path argument is supplied. Neither is covered, so an agent cannot fully predict invocation or result shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the sole parameter 'path' is never mentioned in the description. 'Check any SVG' loosely implies the input is an SVG, but it does not clarify that the parameter is a filesystem path (string) rather than SVG markup, leaving the required argument's format ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Check') and resource (SVG) with three concrete check categories (collisions, clipping, arrows through boxes), so an agent knows exactly what the tool inspects. However, it does not differentiate itself from the closely related sibling 'validate', leaving overlap unresolved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus the sibling 'validate', nor any prerequisites or exclusions. The agent must infer that 'audit' is broader/diagnostic and 'validate' is rule-based, with nothing in the text to support that inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The spec shape, flags, and budgets for one figure type. No type: the list of types.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the useful 'no type → list of types' branching behavior, but says nothing about read-only status, auth/permission needs, return structure, or failure modes for a tool whose whole purpose is introspection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary content description, so nothing is padded. However, the brevity tips into under-specification rather than crispness — the fragments are terse to the point of ambiguity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 1-param introspection tool with no annotations and no output schema, the description should explain what the returned spec shape/flags/budgets actually look like, since nothing else documents the return value. It hints at return content but leaves the agent without enough to call or interpret confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does add real meaning for the single optional 'type' param by defining the no-type fallback (returns the list of types), which the bare string schema does not convey. It still omits what valid type values look like and the format of the per-type output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gestures at content ('spec shape, flags, and budgets') but never states a clear verb — it reads as a noun phrase, leaving the agent to infer that the tool 'describes' things. The resource ('one figure type') is identifiable and distinct from siblings like render/validate/audit, but the domain jargon ('spec shape') keeps the purpose somewhat opaque.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage signal is the conditional 'No type: the list of types,' which explains one calling mode but not when to choose describe over render, validate, audit, export, or infer. No context, prerequisites, or exclusions are offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write png, pdf, or svg from a rendered figure's receipt.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| out | No | ||
| path | Yes | ||
| layout | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. "Write" implies a filesystem mutation, but the description never says whether existing files are overwritten, whether directories are created, what permissions or paths are required, or what the tool returns. Only the output format list is conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the output formats front-loaded and no filler. It is efficiently sized, though its brevity reflects under-specification rather than disciplined editing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations, no output schema, and zero parameter documentation, the description is too thin. An agent lacks the information needed to supply "path", "out", and "layout" correctly or to anticipate side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across four parameters, so the description must compensate and largely does not. It echoes the png/pdf/svg values already encoded in the schema's enum and says nothing about "path" (required), "out", or "layout".
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a verb ("Write") and the output formats (png, pdf, svg) sourced from a rendered figure's "receipt", so the general intent is graspable. However, "receipt" is unexplained domain jargon and the description does not clearly distinguish this tool from the sibling "render", which an agent might reasonably confuse with producing figure output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus the siblings (render, describe, validate, audit, infer), nor any prerequisite such as needing a prior render step. The phrase "from a rendered figure's receipt" hints at an ordering dependency but never states it explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose a scatter spec from a CSV.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| path | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, yet it discloses nothing about behavior: whether it is read-only, whether it mutates state, what it returns, or whether it needs a file path versus inline data. 'Propose' hints at a non-destructive suggestion but is never made explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words, which is structurally sound. However, it is under-specified rather than genuinely concise, so brevity here costs more than it saves.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and 0% parameter coverage, the description is the only information source and it is one sentence. It leaves the agent without enough to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for two parameters (data, path), so the description must compensate but does not. It only vaguely references a CSV input and never clarifies the distinction between supplying inline data versus a path, nor which is expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (propose) and resource (scatter spec) with the input source (CSV), so the agent can tell what it produces. It does not, however, differentiate itself from siblings like render or describe, leaving overlap ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this versus alternatives. With siblings such as render, describe, and validate, the agent has no signal about which tool to reach for in a given situation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate, draw, and audit one figure. Writes OUT.svg, OUT.html, and a receipt. ok false: read errors, change the spec or options, call again.
| Name | Required | Description | Default |
|---|---|---|---|
| out | Yes | output path ending .html | |
| data | No | CSV text, inline | |
| path | No | or a spec/CSV file on disk | |
| spec | No | JSON spec, inline | |
| type | Yes | mermaid (data = Mermaid text), flow, arch, seq, schema, bar, line, scatter, geo, or any describe type | |
| options | No | CLI flags without dashes, e.g. {"x": "month", "y": "signups", "group": "product", "title": "...", "highlight": ["Atlas"]}. describe lists them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses side effects (writes OUT.svg, OUT.html, and a receipt) and a failure mode (ok false indicates read errors), but says nothing about overwriting existing files, permissions, or the precedence between inline spec/data and path.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no padding; outputs are named early. The telegraphic 'ok false' phrasing is terse to the point of being cryptic, costing a little clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-param tool with nested objects and no output schema, the description covers the write side effects and a failure signal, which is the right scope. It still omits how the 'ok'/receipt is surfaced to the caller and how spec vs path precedence works, leaving gaps an agent would hit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters, including the 'type' enum values and options shape. The description adds no parameter meaning beyond mentioning 'spec or options' in its error note, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states concrete actions (validate, draw, audit) and names the concrete artifacts produced (OUT.svg, OUT.html, a receipt), so an agent knows this renders a figure to disk. However it gives no differentiation from the siblings validate and audit, which it claims to also perform, leaving overlap unresolved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is a hint of recovery guidance ('ok false: ... call again'), but nothing states when to use render versus describe, export, validate, or audit. An agent gets no routing signal for choosing this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a spec or CSV without drawing.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | CSV text, inline | |
| path | No | or a spec/CSV file on disk | |
| spec | No | JSON spec, inline | |
| type | Yes | ||
| options | No | CLI flags without dashes, e.g. {"x": "month", "y": "signups", "group": "product", "title": "...", "highlight": ["Atlas"]}. describe lists them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses only the absence of rendering; it says nothing about what 'check' means (schema validity? CSV parse errors?), what the result looks like, or whether it can fail silently. For a tool with zero annotation coverage this is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no waste. It is arguably over-compressed for a five-parameter tool, but the structure itself is efficient and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five parameters (one nested options object), one required field, no annotations, and no output schema, the description should explain what validation means and what failure returns. A one-line sentence leaves an agent unable to predict the outcome of a call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is ~80%, so the schema already documents data, path, spec, and options. The description adds only 'spec or CSV,' which maps loosely to three of the five parameters and gives no format, precedence (data vs path vs spec), or meaning for the undocumented 'type' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a verb (check/validate) and the resources it operates on (a spec or CSV), and the phrase 'without drawing' implicitly distinguishes it from the sibling render tool. The name 'validate' alone is generic, but the description supplies the missing object of the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Without drawing' hints at when to prefer this over render (dry-run validation), but no explicit when-to-use or when-not-to-use guidance is given. The alternative (render) is only implied, never named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0auditdescribeexportinferrendervalidateScored across 6 tools
Each tool has a distinct role: describe (spec shape), render (draw), validate (dry-run check), audit (SVG QA), export (format conversion), infer (CSV to spec). The main overlap is between validate and render (which internally validates) and between audit and render (which internally audits), but descriptions make the boundaries reasonably clear.
All six tools use a consistent single lowercase verb convention (describe, render, validate, audit, export, infer). No mixed casing, no noun_verb hybrids, no stylistic deviations.
Six tools is well-scoped for a diagram spec/render/export pipeline. Each tool covers a distinct stage (introspect, author, check, QA, convert, generate) and none feels redundant or bolted on.
The surface covers a full lifecycle: discover spec shape, infer from CSV, validate, render, audit, and export to multiple formats. Minor gaps like batch rendering or listing prior outputs exist, but core workflows have no dead ends.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Create, edit and organize hand-drawn diagrams (flowcharts, ER, architecture) from any AI agent.
Create, inspect, manage, and render charts and data visualizations as SVG/PNG or interactive embeds.