Workflows

plan_document_diagrams

Reads a whole document (Markdown, HTML, or plain text pasted from Confluence, Notion, or Google Docs), splits it by its headings, and returns the sections a picture would help: the heading and its line, the kind, a one-sentence reason, a confidence, and a starter source drafted from the section's own lists, tables, numbers, and dates. It is a workflow of the MCP server and the HTTP API, with the title "Plan document diagrams".

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?	Reads a whole document (Markdown, HTML, or plain text pasted from Confluence, Notion, or Google Docs), splits it by its headings, and returns the sections a picture would help: the heading and its line, the kind, a one-sentence reason, a confidence, and a starter source drafted from the section's own lists, tables, numbers, and dates.
What does it replace?	reading the document section by section and choosing a kind for each.
How do I call it over HTTP?	`POST /v1/markdown/plan`
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?	`maxPlanDocumentLength`, `maxPlanSections`, `maxPlanSuggestions`. 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. Reads a whole document (Markdown, HTML, or plain text pasted from Confluence, Notion, or Google Docs), splits it by its headings, and returns the sections a picture would help: the heading and its line, the kind, a one-sentence reason, a confidence, and a starter source drafted from the section's own lists, tables, numbers, and dates. Sections that read well as text, or already have a diagram, are left out. Draws nothing and changes nothing. Replaces reading the document section by section and choosing a kind for each.

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 12 operations.

Example call

The arguments of the call, as JSON:

1{2  "document": "# Refunds\n\nHow a refund moves through the company.\n\n## Process\n\nCustomer: asks for a refund\nSupport: checks the order\nBilling: issues the refund\nCustomer: gets the money back\n\n## Who does what\n\n| Task | Support | Billing | Finance |\n|---|---|---|---|\n| Approve | A | R | I |\n| Pay out | I | A R | C |\n"3}

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

# Refunds
How a refund moves through the company.
## Process
Customer: asks for a refundSupport: checks the orderBilling: issues the refundCustomer: gets the money back
## Who does what
| Task | Support | Billing | Finance ||---|---|---|---|| Approve | A | R | I || Pay out | I | A R | C |

Prompts that lead to it

Which parts of this design doc need a diagram?
Add pictures to this Confluence page.
Plan the diagrams for our onboarding guide.

Arguments

Field	Type	Required	Description
`document`	`string`	yes	The whole document: Markdown, plain text pasted from Confluence, Notion, or Google Docs, or HTML. Up to 10000000 characters. at least 1 character; at most 10000000 characters.
`maxSuggestions`	`integer`	no	Most sections to suggest a picture for, up to 12. The strongest are kept, in document order. The default is 8. minimum 1; maximum 12; default 8.

Result

Field	Type	Required	Description
`summary`	`string`	yes	One sentence: how many sections were read and how many would gain a picture.
`format`	`"markdown" \| "html" \| "text"`	yes	How the document was read: Markdown headings, HTML h1 to h6, or plain text with heading-like lines.
`sectionsRead`	`integer`	yes	Sections read, up to the cap.
`suggestions`	`object[]`	yes	In document order. Sections that read well as text, or already have a diagram, are not listed.
`suggestions[].heading`	`string`	yes	The heading of the section, as written.
`suggestions[].line`	`integer`	yes	The 1-based line of the heading in the document that was sent. minimum 1.
`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: what in the section points to this kind.
`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.
`caps`	`object`	yes
`caps.hit`	`boolean`	yes	True when a cap left something out; messages says what.
`caps.messages`	`string[]`	yes
`caps.maxSections`	`integer`	yes
`caps.maxSuggestions`	`integer`	yes
`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
`maxPlanDocumentLength`	10000000	Characters in the document.
`maxPlanSections`	200	Sections read; a document with more says so in caps.
`maxPlanSuggestions`	12	Sections suggested in one answer, the strongest first; the rest are counted in caps.

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