Writing diagrams with an agent

TL;DR

1. The loop

PictureSourceOutline

2. Read the language

get_diagram_syntax returns the language as data, in two sizes so that an agent does not pay for kinds it does not draw. With no arguments it returns the overview: every node type with its default icon and tone, arrows, line options, tones, status icons, icon sets and providers, limits, how to edit an existing picture, one line about each kind, and the tested examples of the kinds those shared tables describe. Pass kind (for example git or flow) to get that kind in full: its statements, limits, and a tested example. flow also carries the group types with their frame, tone, and icon, the overlays, and a complete cloud architecture example. The error codes are in the diagnostic codes reference, because every diagnostic a tool returns already carries its code, line, column, and hint. It lists the icon sets but not every icon: it points to search_icons, which finds a product icon from its name. It never changes, so an agent reads the overview once per session, and a kind once.

3. Validate until clean

validate_diagram takes the source and returns every problem in one pass. A mistake is a normal result, not an exception, so the agent can loop.

Source with a misspelled type:

1flow "T"2node a servce "A"

Each mistake has a code, a position, and a hint. Drawn with the offending line and a caret under the characters to change, it reads like this.

error E120: Unknown node type "servce"   2 | node a servce "A"     |        ^^^^^^hint: Did you mean "service"?

The agent changes servce to service, validates again, and gets valid: true. The tool returns the same facts as data:

1{2  "valid": false,3  "errors": [4    {5      "code": "E120",6      "message": "Unknown node type \"servce\"",7      "line": 2,8      "column": 8,9      "length": 6,10      "hint": "Did you mean \"service\"?"11    }12  ],13  "warnings": []14}

Icon and group-type suggestions

For an architecture diagram, validate_diagram also suggests the icon and the group type an author left out. Each suggestion is a warning with the exact text to add, so the fix is one edit and never a guess. Nothing is applied for you.

The rules are fixed, so the same source gets the same suggestions every time. A label counts only as whole words, the longest phrase wins, and a label that fits two products or two types gets no suggestion. A generic phrase such as SQL database counts only inside a group, or a diagram, whose provider= owns that product, and a brand such as Redis counts only when it is the whole label. The cloud architecture guide shows the full recipe.

4. Check the meaning

A valid diagram can still say the wrong thing: an arrow reversed, a node in the wrong group. outline_diagram returns the diagram as plain text, in reading order. Compare it to the intent. The one-line summary becomes the alt text of the picture, and the rest appears in the collapsed Text description, so it is also what a screen reader hears.

5. Render and place

render_diagram returns the SVG, its pixel size, and any warnings, in the light or dark theme. To put a diagram in a document, write it as a diagram fence in the Markdown file and call sync_markdown with the file; see Diagrams in Markdown and on GitHub.

6. Habits that produce good diagrams

7. Ways to call the tools

8. Workflows: one call instead of several

A workflow is a tool that performs several operations and returns one combined answer, so the agent spends one turn where it would spend three or four. The single tools stay for fine-grained steps. Every workflow is read-only, never guesses, and keeps its work bounded; the tool reference lists the operations and the limit of each.

To move the Mermaid diagrams in a document, the sequence is:

1. Call sync_markdown with the document text, its path, convertMermaid: true, and mode: "check". Read the report.
2. Call it again with mode: "sync". The result holds the rewritten document and the picture files.
3. Write the returned markdown to the document and each returned file to its path. The tool writes nothing itself.
4. Review the change in git before committing.

Migrating from Mermaid explains the diagnostics and shows the result of each call.

9. Choosing a kind and planning a document

Two workflows help before any source is written. Both are cheap: they read text, parse each starter once, and lay nothing out.

The shape of the text counts as much as its words:

A starter is a start: replace its placeholders, call get_diagram_syntax with its kind, and check it with draw_diagram before you draw. To put the pictures into the document, add each as a diagram fence under its heading and call sync_markdown.

The MCP server also offers prompts, which a client lists in its prompt menu. Each tells the agent which tools to call, in order.

10. Save diagrams to your library

Saving a finished diagram to Plotwork keeps it where your team can find it, beside the files and view links on your machine. Where it goes depends on how you connect.

See also