# plan_document_diagrams

> Page: https://docs.plotwork.dev/mcp/tools/plan-document-diagrams. Index of every page: https://docs.plotwork.dev/llms.txt

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`](https://docs.plotwork.dev/api/post-v1-markdown-plan.md) |
| 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:

```json
{
  "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"
}
```

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

```text
# Refunds

How a refund moves through the company.

## Process

Customer: asks for a refund
Support: checks the order
Billing: issues the refund
Customer: 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. |

## See also

| Doc | Why |
|---|---|
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | Every tool, with the workflows first |
| [`POST /v1/markdown/plan`](https://docs.plotwork.dev/api/post-v1-markdown-plan.md) | The same operation over HTTP |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | What the diagram source may contain |
| [Writing diagrams with an agent](https://docs.plotwork.dev/mcp/agent-loop.md) | The loop in practice |