# get_diagram_syntax

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

Read the diagram language as data. It is a single tool of the MCP server and the HTTP API, with the title "Get diagram syntax".

## TL;DR

| Question | Answer |
|---|---|
| What is it? | A single tool: it does one thing. |
| What does it do? | Read the diagram language as data. |
| How do I call it over HTTP? | [`GET /v1/vocabulary`](https://docs.plotwork.dev/api/get-v1-vocabulary.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? | None beyond the limits of each argument, which are in the schema 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

Read the diagram language as data. Call it once with no kind before your first diagram: the overview, the tables every kind shares (node types, arrows including dotted ..> for asynchronous calls, animated and numbered lines, icon sets, size limits, how to edit an existing SVG), and one line about each kind. For one kind in full, call it again with kind set to it: its statements, limits, and a tested example. kind flow adds the group types (type=), overlays, stack= marks, and a complete cloud architecture example; build the group tree top-down with type=, one node per service, and icons from map_icons or search_icons. For a common architecture, find_pattern gives a checked diagram to adapt. topic import-formats lists what import_source reads.

## Arguments

| Field | Type | Required | Description |
|---|---|---|---|
| `kind` | `"flow" \| "sequence" \| "schema" \| "git" \| "gantt" \| "class" \| "state" \| "timeline" \| "journey" \| "mindmap" \| "treemap" \| "pie" \| "quadrant" \| "layers" \| "c4" \| "matrix" \| "sankey" \| "xychart" \| "tree" \| "swimlane"` | no | The one kind to read in full. Omit it for the overview: the language every kind shares and one line about each kind. |
| `topic` | `"import-formats"` | no | import-formats: what import_source reads, draws, and takes, a line each. |

## Result

| Field | Type | Required | Description |
|---|---|---|---|
| `answer` | `string` | yes | What this answer is: overview, a topic (import-formats), or the kind it describes in full (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). |
| `howToGetAKind` | `string` | yes | In plain words: what this answer holds and how to get the rest. |
| `kinds` | `string[]` | yes | Header keywords: the first line names the kind. |
| `kindDetails` | `object[]` | yes | The overview lists every kind in the order of kinds, with its header, noun, and summary, and a pointer in more. A kind answer holds that kind alone, in full. |
| `kindDetails[].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. |
| `kindDetails[].header` | `string` | yes | The header line, such as flow "Title". |
| `kindDetails[].noun` | `string` | yes | What the kind's diagrams are called in a sentence, such as flow or database schema. |
| `kindDetails[].summary` | `string` | yes | One sentence: what the kind draws. |
| `kindDetails[].statements` | `object[]` | no | The statements the kind adds to the header. Empty for a kind whose language the shared tables of this reference already describe. |
| `kindDetails[].statements[].syntax` | `string` | yes | The statement with its parts named, such as: task <id> "Name" days=<n>. |
| `kindDetails[].statements[].meaning` | `string` | yes | What the statement does, and what it needs. |
| `kindDetails[].statements[].example` | `string` | yes | One line that parses. |
| `kindDetails[].limits` | `object[]` | no | The quality thresholds the kind adds. Empty for a kind whose limits are in the limits table of this reference. |
| `kindDetails[].limits[].name` | `string` | yes | What is counted, such as tasks. |
| `kindDetails[].limits[].value` | `integer` | yes | More than this in one diagram draws a quality warning. |
| `kindDetails[].limits[].meaning` | `string` | yes | Why the limit exists and what to do past it. |
| `kindDetails[].more` | `string` | no | Only in the overview, where statements and limits are left out: what a call with this kind returns that the overview does not, and how to ask for it. |
| `nodeTypes` | `object[]` | no |  |
| `nodeTypes[].type` | `"person" \| "agent" \| "client" \| "service" \| "gateway" \| "function" \| "database" \| "cache" \| "queue" \| "storage" \| "identity" \| "secret" \| "external" \| "step" \| "decision" \| "terminal"` | yes |  |
| `nodeTypes[].shape` | `"card" \| "pill"` | yes | How the node is drawn. |
| `nodeTypes[].isTinted` | `boolean` | yes | True when the card is filled and outlined in its tone, as for decisions. |
| `nodeTypes[].defaultTone` | `"neutral" \| "blue" \| "violet" \| "aqua" \| "orange" \| "green" \| "amber" \| "red"` | yes | Color family used when tone= is not set. |
| `nodeTypes[].defaultIcon` | `string \| null` | yes | Icon used when icon= is not set, or null for none. |
| `nodeTypes[].isDashed` | `boolean` | yes | True when the outline is dashed, as for external systems. |
| `nodeTypes[].usableAsActor` | `boolean` | yes | True when a sequence diagram actor may use this type. |
| `tones` | `("neutral" \| "blue" \| "violet" \| "aqua" \| "orange" \| "green" \| "amber" \| "red")[]` | no |  |
| `directions` | `("auto" \| "right" \| "down" \| "left" \| "up")[]` | no | Values for direction= on a flow header. |
| `arrows` | `object[]` | no |  |
| `arrows[].token` | `string` | yes | The arrow as written in source. |
| `arrows[].line` | `"solid" \| "dashed" \| "dotted"` | yes | How the line is drawn. |
| `arrows[].heads` | `"end" \| "both" \| "none"` | yes | Which ends carry an arrowhead. |
| `arrows[].meaning` | `string` | yes | What the arrow says, so the right one is chosen. |
| `blockTypes` | `("alt" \| "opt" \| "loop" \| "par")[]` | no | Frames a sequence diagram can wrap around messages. |
| `columnFlags` | `("pk" \| "fk" \| "unique" \| "nullable")[]` | no | Flags a schema column row may carry. |
| `themes` | `("light" \| "dark")[]` | no |  |
| `iconSets` | `("lucide" \| "simple" \| "status" \| "aws" \| "gcp" \| "azure" \| "alibaba" \| "oci" \| "ibm" \| "cloudflare" \| "digitalocean" \| "vercel")[]` | no |  |
| `iconCount` | `integer` | no | Number of bundled icons; use search_icons to find names. |
| `iconProviders` | `object[]` | no | Cloud and platform providers, each an icon set holding the provider (set:cloud) and its products. |
| `iconProviders[].set` | `"aws" \| "gcp" \| "azure" \| "alibaba" \| "oci" \| "ibm" \| "cloudflare" \| "digitalocean" \| "vercel"` | yes | Icon set prefix, as in aws:lambda. |
| `iconProviders[].title` | `string` | yes | The provider the set stands for. |
| `iconProviders[].iconCount` | `integer` | yes | Icons in the set: the provider itself (set:cloud) and its products. |
| `iconProviders[].example` | `string` | yes | One icon of the set that is bundled, for example aws:lambda. |
| `overlay` | `object` | no | A dashed frame around members that may sit in different groups; it owns none of them. |
| `overlay.options` | `string[]` | yes | Options an overlay statement takes after its name, as in: overlay id "Name" members=a,b type=scale-group. |
| `overlay.frame` | `"solid" \| "dashed" \| "dotted"` | yes | How an overlay is always drawn. |
| `overlay.meaning` | `string` | yes | What an overlay is for, so it is used where a group would be wrong. |
| `group` | `object` | no | How a flow group looks and what it accepts; its corner tab shows its icon and name. |
| `group.options` | `string[]` | yes | Options a group statement takes after its name, as in: group id "Name" type=region provider=aws {. |
| `group.defaultTone` | `"neutral" \| "blue" \| "violet" \| "aqua" \| "orange" \| "green" \| "amber" \| "red"` | yes | Color family of a group with no type when tone= is not set. |
| `group.example` | `object` | yes | A complete architecture diagram: typed groups nested by provider, a provider icon on every node, stack marks, and a dotted edge. Copy and edit it. |
| `group.example.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. |
| `group.example.title` | `string` | yes |  |
| `group.example.source` | `string` | yes | A complete diagram that is checked by the build; copy and edit it. |
| `group.types` | `object[]` | yes | Every group type. A type gives the group a default icon, tone, frame style, and a shade that deepens with nesting; icon= and tone= override them. |
| `group.types[].type` | `"cloud" \| "account" \| "region" \| "zone" \| "network" \| "subnet" \| "public-subnet" \| "private-subnet" \| "management-subnet" \| "isolated-subnet" \| "resource-group" \| "cluster" \| "scale-group" \| "service-plan" \| "web-tier" \| "app-tier" \| "data-tier" \| "storage-account" \| "messaging" \| "edge" \| "security" \| "identity-boundary" \| "trust-boundary" \| "observability" \| "ci-cd" \| "environment" \| "cloud-boundary" \| "on-premises" \| "client-side" \| "external-systems"` | yes | Value for type= on a group. |
| `group.types[].title` | `string` | yes | What the frame is called in the text description. |
| `group.types[].meaning` | `string` | yes | What the author means by this type, so the right one is chosen. |
| `group.types[].tone` | `"neutral" \| "blue" \| "violet" \| "aqua" \| "orange" \| "green" \| "amber" \| "red"` | yes | Color family the frame and tab get when tone= is not set. |
| `group.types[].frame` | `"solid" \| "dashed" \| "dotted"` | yes | How the outline is drawn. |
| `group.types[].icon` | `string` | yes | Icon in the corner tab when the group has no provider. |
| `group.types[].providerIcons` | `object` | yes | Icon in the corner tab for each provider whose icon differs from the generic one, keyed by provider set. |
| `lineOptions` | `object[]` | no | Options that animate a line (animate=on makes dashes travel toward the arrowhead) or number the steps of a flow or sequence (numbered=on, start=, and step= on a line). All are off by default. |
| `lineOptions[].key` | `string` | yes | The option as written, such as animate or step. |
| `lineOptions[].scope` | `"header" \| "line"` | yes | header: on the flow or sequence header line. line: on an edge or a message. |
| `lineOptions[].values` | `string` | yes | What the option takes. |
| `lineOptions[].meaning` | `string` | yes | What it does, and the cases where it is refused. |
| `lineOptions[].example` | `string` | yes | One line that parses. |
| `labelIcons` | `object[]` | no | Edge labels that get a tick or cross automatically; icon=none on the edge removes it. |
| `labelIcons[].label` | `string` | yes | An edge label that gets an icon automatically, matched whole and ignoring case. |
| `labelIcons[].icon` | `string` | yes | The icon the label gets. |
| `verbIcons` | `object[]` | no | The icons a flow edge label draws when it names a relationship with a verb. icon= on the edge wins, icon=none removes it, and icons=off on the header turns them all off. |
| `verbIcons[].icon` | `string` | yes | The icon drawn in the label. |
| `verbIcons[].words` | `string[]` | yes | Phrases that draw it: the whole label, or its first words followed by what is acted on ("reads orders"). |
| `style` | `string[]` | no | How to make a flow diagram look finished: verbs on arrows, role= on lines that mean something, typed groups, product names. |
| `autoIcons` | `object` | no | Items with no icon= get the icon their label names for certain (a brand, a cloud product, a common role). icon=none keeps one item plain; icons=off on the header keeps them all plain. |
| `autoIcons.key` | `string` | yes | The header option: icons. |
| `autoIcons.values` | `string` | yes | What it takes. |
| `autoIcons.meaning` | `string` | yes | What it does, and how one item opts out. |
| `autoIcons.example` | `string` | yes | One header line that parses. |
| `roleIcons` | `object[]` | no | The plain icons for common roles, drawn on flow and sequence service and external items, C4 elements, layers blocks, mind map topics, and swimlane lanes. The last role word of the label wins. |
| `roleIcons[].icon` | `string` | yes | The icon drawn. |
| `roleIcons[].words` | `string[]` | yes | Whole words of a label of three words or fewer that draw it. |
| `statusIcons` | `object[]` | no | Colored status and outcome icons: a green check, a red X, and so on. |
| `statusIcons[].ref` | `string` | yes | Value for icon=, such as status:success. |
| `statusIcons[].tone` | `"neutral" \| "blue" \| "violet" \| "aqua" \| "orange" \| "green" \| "amber" \| "red"` | yes | Color the icon is always drawn in, whatever tone its owner has. |
| `statusIcons[].meaning` | `string` | yes | What the icon says, so the right one is chosen. |
| `limits` | `object` | no | Bounds and quality thresholds. |
| `limits.maxSourceLength` | `integer` | yes |  |
| `limits.maxFlowNodes` | `integer` | yes | Quality lint: more nodes than this warns, for a diagram with no groups. |
| `limits.nodesPerGroup` | `integer` | yes | Each group of a flow diagram raises the node limit by this many. |
| `limits.maxFlowNodesCeiling` | `integer` | yes | The node limit never rises above this, whatever the groups. |
| `limits.maxSchemaTables` | `integer` | yes |  |
| `limits.maxSequenceActors` | `integer` | yes |  |
| `limits.maxNumberedSteps` | `integer` | yes | More numbered steps than this in one diagram warns (W200). |
| `limits.maxStackMarks` | `integer` | yes | Most technology marks a node carries in stack=. |
| `limits.targetWidth` | `integer` | yes | Column width in px that diagrams are checked against. |
| `editing` | `object` | no | How to edit an existing Plotwork SVG: read it back with read_diagram, change the source, draw it, and save or publish it again. |
| `editing.steps` | `string[]` | yes | In order: how to change a diagram that already exists as a Plotwork SVG, a hosted link or a file in the repository. |
| `editing.embedSource` | `string` | yes | When to set embedSource true on draw_diagram, render_diagram, or publish_diagram, and what it means for who can read the source. |
| `diagnosticCodes` | `object[]` | no |  |
| `diagnosticCodes[].name` | `string` | yes | Identifier of the code. |
| `diagnosticCodes[].code` | `string` | yes | The code to branch on, such as E120. |
| `diagnosticCodes[].severity` | `"error" \| "warning"` | yes |  |
| `examples` | `object[]` | yes | Tested examples: the overview holds the ones for the kinds the shared tables describe in full, a kind answer holds its own. |
| `examples[].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. |
| `examples[].title` | `string` | yes |  |
| `examples[].source` | `string` | yes | A complete diagram that is checked by the build; copy and edit it. |
| `importFormats` | `object[]` | no | Only for topic import-formats: every format import_source reads, a line each. |
| `importFormats[].format` | `string` | yes | The format, as import_source takes it. |
| `importFormats[].reads` | `string` | yes | What it reads. |
| `importFormats[].draws` | `string` | yes | The diagram it draws. |
| `importFormats[].options` | `string` | yes | The options it takes. |

## Behavior hints

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

## See also

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