d2
grade
reliability
overall
D2 is a modern diagram scripting language that turns text to diagrams.
D2 is a command-line compilation tool that converts a declarative text file into a vector graphic diagram. Handing this tool to an agent provides a highly secure, reliable, and deterministic environment for layout generation. The agent writes diagram specifications in a simple markup syntax and runs a single command to generate the final image, with no risk of runtime side effects or unauthorized system access.
Surfaces × lenses
| surface ↓ lens → | Coherence | Economy | Consistency | Verifiability | Safety |
|---|---|---|---|---|---|
| Disclosure | |||||
| Interface | |||||
| Loop | |||||
| Recursion | |||||
| Human |
Click any cell for what was measured and why. A corner dot marks a cell filled by a hard instrument (checker, telemetry); undotted cells are judged by the rater ensemble. 53% of this matrix is hard-measured.
Teaching sources compared
Teaching source barely matters for d2: sources land within a grade of each other (docs A, skill A).
The teaching source does not affect the performance of the agent when using this tool. Both the standard documentation and the specialized skill instructions resulted in nearly identical outcomes, with the agent successfully compiling the target diagram in both cases.
This parity is due to the simple and declarative nature of the tool's syntax. The basic syntax rules for defining nodes, clusters, and connectors are clear and concise in both formats, making the tool easy to adopt regardless of the instruction method.
| Source | Grade | Renders | Disclosure | Interface | Loop | Recursion | Human |
|---|---|---|---|---|---|---|---|
| official docs ★ | A | ✓ | +0.26 | +0.69 | +0.45 | +0.42 | +0.37 |
| skill | A | ✓ | +0.14 | +0.65 | +0.47 | +0.37 | +0.26 |
Same harness, same reference agent, same briefs, same trial count — the only variable is how the agent was taught the tool. ★ = best source.
The experience
The compilation workflow proceeds exceptionally well due to the simple CLI interface and declarative layout syntax. The agent writes visual specifications in a text file using block syntax and arrows to define structures, then executes the tool using a single terminal command. This input mapping eliminates complex API calls or runtime state issues. The compilation is deterministic, ensuring that identical source code yields identical SVG layouts.
The editing loop works poorly because of the lack of interactive layout controls. In the recorded interaction, the agent required nearly ten cycles to complete a simple diagram containing eight labeled nodes and two cluster blocks. Because the layout engine places blocks automatically, adjustments to line styling, container nests, and connector nodes require continuous source code modification and rendering trials. The agent struggles to predict the exact visual results of complex code combinations, leading to slow iterative refinement.
File management and execution security work well. The tool operates exclusively on local files within the current working directory, which removes any risk of side effects or dangerous system operations. The compilation environment remains perfectly reliable and idempotent. If a fresh agent resumes a task using only the existing source files, it can continue modifying the diagram without altering prior layout configurations.
Fit
D2 is a good fit for agents that need to quickly generate standard technical system diagrams, flowcharts, or architecture maps where structural correctness matters more than precise aesthetic positioning. The simple textual syntax allows agents to programmatically map structural data directly into visual diagrams.
D2 is not a good fit for agents tasked with custom graphic design, highly customized art assets, or pixel-perfect layout controls. Because the layout engine handles the positioning of nodes automatically, attempting to override the engine to achieve specific aesthetic designs leads to excessively long edit-and-render loops.
Notes
This diagram illustrates the multi-step cycle of file edits and compilations required to finalize a diagram representation.
Validation
Convergent check. Where a hard instrument and the independent rater panel measure the same cell, they agree on 9 of 16 cross-checked cells (78%). Two independent methods landing on the same number is our accuracy signal — not just the raters agreeing with each other.
| Cell where they disagree | Instrument | Rater | Δ |
|---|---|---|---|
| disclosure.verifiability | -0.40 | +0.70 | 1.10 |
| human.verifiability | -0.20 | +0.80 | 1.00 |
| recursion.coherence | -0.25 | +0.50 | 0.75 |
| recursion.verifiability | +0.00 | +0.70 | 0.70 |
| disclosure.economy | +0.06 | +0.70 | 0.64 |
| recursion.economy | +0.72 | +0.20 | 0.52 |
| human.coherence | +0.10 | +0.60 | 0.50 |
Ground truth
5 of 5 requirements met · deterministic checker, no model judgment- renders without error — exit 0
- 6+ labeled nodes — 15 nodes
- 7+ directed edges — 8 edges
- 2+ clusters/groups — 4 clusters
- has a title — present
Reliability (pass^k): one attempt succeeds 100% of the time · three in a row 100% · all runs 100%. A fresh agent resuming from the files alone never broke prior work.
Models & runs
2026-07-06Scored cross-model runs — the same battery, checker and grading re-run with a different driver model (hardens the reference result; not folded into rankings).
| model | source | grade | checker | pass³ | coverage |
|---|---|---|---|---|---|
| pi:xiaomi/mimo-v2.5 | docs | A− 0.868 | 1 | — | 27/30 |
| claude-code-acp:claude-sonnet-5 | docs | A− 0.882 | 1 | — | 27/30 |
| Model | Harness | Runs | Solved | Turns |
|---|---|---|---|---|
 glm-5.2 |  PI | 25 | 25/25 | 13 |
Each path is one run through the shared semantic space; nodes are turns (red = an errored turn). Hover a model — here or in the graph — to isolate its runs.
How this was measured
- reference agent
- pi:z-ai/glm-5.2
- trials
- 25 (n=5/tier)
- methodology
- v0.1 3e74a3c6
- cost
- $1.0474
- hard-measured cells
- 53%
- teaching source
- d2 (official docs) (official-docs)
Same brief, same reference agent, and the same trial count for every tool in a category — a difference in the numbers is attributable to the tool (and its teaching source), not the setup. Profiles carry the methodology hash; results under different hashes are not compared.