See it as a diagram
Everything below, as a diagram you can edit. Describe yours and see it in seconds.
No account needed · Editable canvas, not a picture
Four routes into the same canvas
create_diagram hands the whole design to the model from a written description. It has a scope parameter: overview, the default, produces roughly 12 to 20 nodes and the shape of the system; detailed itemises everything and is denser to read. Zone names you supply are treated as a specification rather than a suggestion, so naming the layers you want is the cheapest way to control the output.
create_blank_diagram opens an empty canvas and returns its id. No generation runs and no credit is spent, because the agent draws it with the canvas tools. This is the route to take when the architecture is already settled in the conversation and you want the agent to transcribe rather than invent.
edit_diagram applies one plain-language instruction to an existing diagram and returns a PNG. Specific instructions work, vague ones do not: naming the node, the direction and the label gets a correct edit, while asking for an improvement gets a redraw you did not want. When the model decides nothing needed changing, the credit is refunded and it says so.
repo_refresh is the fourth route and the one people forget. If the diagram is linked to a repository, the honest way to change it is usually to change the code and re-sync, because a sync regenerates from source and will replace canvas edits anyway.
Read before you write
get_diagram returns the full structure: every node with its type and columns, every connection, and the groups. Passing include_image as false gives a structure-only read, which is what you want before an edit, because the model reasons over the text and the picture only costs tokens. canvas_describe_canvas does the same job mid-build once the agent is already working on a canvas.
get_design_guide returns the same size, edge and zone standard that the Datadef generator follows. An agent that reads it before its first canvas call produces diagrams that are indistinguishable from generated ones, which is what keeps a workspace from splitting into hand-built diagrams and real ones.
canvas_inspect_nodes narrows that read to named nodes when the canvas is large enough that a full describe is wasteful, and export_diagram is how the picture itself reaches the client. An agent that reaches for a tool name outside this set is guessing rather than reading the surface, and the surface is cheap to read: tools/list answers anonymously and returns all 36, which are 9 outcome tools and 27 canvas tools. Two canvas primitives are deliberately absent, look_at_canvas because MCP clients render the picture themselves through export_diagram, and find_nodes because describe_canvas already returns everything it would.
The call order that produces a readable canvas
The 27 canvas tools are atomic on purpose: an agent can make one exact change instead of describing an intent and hoping. That precision comes with an ordering discipline, and skipping it is the difference between a diagram and a pile of boxes.
Group the zones first, so nodes land inside a structure rather than being reorganised afterwards. Add nodes in batches rather than one call per node. Connect only the flows that are real, because edge count is what destroys legibility faster than node count. Add the notes and labels that carry meaning. Then call canvas_layout_canvas once, at the end, and canvas_validate_canvas to catch orphans, overlaps and unlabelled edges before you look at it.
Icons are worth one extra call. canvas_search_icons searches a registry of 2,095 marks, 624 of them Azure, 438 AWS and 226 GCP, the rest data tools, Kubernetes, networking and general shapes. A diagram with the correct vendor glyphs reads as a real architecture diagram; the same nodes with generic marks read as a flowchart about a system rather than a picture of one.
get_design_guide() create_blank_diagram(name: "Ingestion platform") canvas_group_nodes(...) # zones first canvas_add_nodes(...) # in batches, with icons canvas_connect_nodes(...) # only the real flows canvas_add_text(...) # the sentences the picture cannot carry canvas_layout_canvas(...) # once, at the end canvas_validate_canvas(...) # before showing it to anyone
What each route costs
Generation-backed calls, create_diagram and edit_diagram, spend a credit each. Building on a blank canvas with the canvas tools spends none, because no Datadef generation runs: your agent does the thinking and the tools write the result. That makes the blank-canvas route attractive for small precise diagrams and for teams already paying for their own model.
The timing matters more than the cost for a good session. create_diagram waits about 35 seconds; fast generations come back finished with a preview image, slower ones return a diagram id while generation continues for one to three minutes. The correct follow-up is to poll get_diagram, roughly every 30 seconds, not to call create_diagram again. A second call produces a duplicate diagram and spends another credit, and it is the single most common agent mistake against this API.
API access comes with paid plans, and the key is shown once when you create it on the MCP and integrations page.
FAQ
Can an AI agent edit an existing architecture diagram instead of redrawing it?
When should an agent build a diagram by hand rather than generate one?
Why did my agent create two diagrams for one request?
Do agent-built diagrams look different from generated ones?
What happens to agent edits on a diagram linked to a repository?