# suggest_diagram

> Page: https://docs.plotwork.dev/mcp/tools/suggest-diagram. Index of every page: https://docs.plotwork.dev/llms.txt

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`](https://docs.plotwork.dev/api/post-v1-diagrams-suggest.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? | `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:

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

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

```text
Roles: Admin, Editor, Viewer
Endpoints: 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. |

## See also

| Doc | Why |
|---|---|
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | Every tool, with the workflows first |
| [`POST /v1/diagrams/suggest`](https://docs.plotwork.dev/api/post-v1-diagrams-suggest.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 |