Workflows

suggest_diagram

Picks the kind of diagram for a request in plain words, such as "permission matrix for these endpoints and roles" or "where our cloud spend goes", with optional pasted data (a table, a list, numbers by period). It is a workflow of the MCP server and the HTTP API, with the title "Suggest diagram".

TL;DR

Question	Answer
What is it?	A workflow: one call does the work of several tools and returns one combined answer.
What does it do?	Picks the kind of diagram for a request in plain words, such as "permission matrix for these endpoints and roles" or "where our cloud spend goes", with optional pasted data (a table, a list, numbers by period).
What does it replace?	reading every kind in get_diagram_syntax to choose one.
How do I call it over HTTP?	`POST /v1/diagrams/suggest`
Does it change anything?	No. It is read-only and idempotent, and it talks to nothing outside itself. It saves no file and returns its answer as data.
Which bounds apply?	`maxRequestLength`, `maxSuggestDataLength`, `maxSuggestions`, `maxStarterItems`. 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

Workflow. Picks the kind of diagram for a request in plain words, such as "permission matrix for these endpoints and roles" or "where our cloud spend goes", with optional pasted data (a table, a list, numbers by period). Returns up to 3 kinds, best first, each with a one-sentence reason, a confidence, the statements to use, and a short starter source that parses, built from the names and numbers in the request and data. Call it when you are unsure which kind fits, then edit the starter and call draw_diagram. Replaces reading every kind in get_diagram_syntax to choose one.

Steps

Operation	Runs	What it does
`parse`	only when needed	Parse the source and return its errors, without laying it out or linting it.

One call performs at most 3 operations.

Example call

The arguments of the call, as JSON:

1{2  "request": "Permission matrix for these endpoints and roles",3  "data": "Roles: Admin, Editor, Viewer\nEndpoints: GET /posts, POST /posts, DELETE /posts"4}

The data argument, written out one line at a time:

Roles: Admin, Editor, ViewerEndpoints: GET /posts, POST /posts, DELETE /posts

Prompts that lead to it

Which diagram should I use to show who can call which endpoint?
What is the best way to draw where our cloud spend goes?
Suggest a diagram for comparing three message brokers.

Arguments

Field	Type	Required	Description
`request`	`string`	yes	What the picture is for, in plain words, such as "permission matrix for these endpoints and roles" or "how a refund moves between support and billing". at least 1 character; at most 1000 characters.
`data`	`string`	no	Optional text to draw from: a pasted table, a list, numbers by period, or notes. Names and numbers in it are used in the starters. at most 20000 characters.

Result

Field	Type	Required	Description
`request`	`string`	yes	The request that was read.
`suggestions`	`object[]`	yes	Up to 3, best first, one for each kind and style.
`suggestions[].kind`	`string`	yes	A diagram kind: flow, sequence, schema, git, gantt, class, state, timeline, journey, mindmap, treemap, pie, quadrant, layers, c4, matrix, sankey, xychart, tree, or swimlane today. Later versions add kinds, so expect others.
`suggestions[].style`	`string \| null`	yes	The style the starter uses: compare, score, raci, or risk for a matrix, files or org for a tree; null for the kind's only style.
`suggestions[].why`	`string`	yes	One sentence: why this kind fits.
`suggestions[].confidence`	`"high" \| "medium" \| "low"`	yes	high: the text names this kind of picture or its shape fits it exactly. medium: it leans toward it. low: a fallback worth considering.
`suggestions[].starter`	`string`	yes	A short Plotwork source of this kind that parses without errors: built from the names and numbers in the text where it could find them, otherwise a small example to edit. Replace every placeholder before you draw it.
`suggestions[].tailored`	`boolean`	yes	True when the starter uses names or numbers from the text; false when it is the kind's small example.
`suggestions[].statements`	`string[]`	yes	The few statements of this kind to write, as syntax. get_diagram_syntax with this kind has them all.
`importFormat`	`string`	no	Present when the data is, or the request names, a file import_source reads (sql, openapi, compose, terraform, and so on): call import_source with this format and the file's text instead of editing a starter.
`next`	`string`	yes	The next step in one sentence.

Behavior hints

Hint	Value
`readOnlyHint`	true
`destructiveHint`	false
`idempotentHint`	true
`openWorldHint`	false

Bounds

A bound that is reached is reported in the result; nothing is cut silently.

Bound	Value	What it limits
`maxRequestLength`	1000	Characters in the request.
`maxSuggestDataLength`	20000	Characters in the pasted data.
`maxSuggestions`	3	Kinds suggested in one answer.
`maxStarterItems`	8	Items, rows, or columns a starter takes from the text; plan_document_diagrams takes the same.

Doc	Why
Tool reference	Every tool, with the workflows first
`POST /v1/diagrams/suggest`	The same operation over HTTP
Language reference	What the diagram source may contain
Writing diagrams with an agent	The loop in practice