# read_diagram

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

Read the source of an existing Plotwork SVG so you can edit the diagram. It is a single tool of the MCP server and the HTTP API, with the title "Read diagram".

## TL;DR

| Question | Answer |
|---|---|
| What is it? | A single tool: it does one thing. |
| What does it do? | Read the source of an existing Plotwork SVG so you can edit the diagram. |
| How do I call it over HTTP? | [`POST /v1/diagrams/read`](https://docs.plotwork.dev/api/post-v1-diagrams-read.md) |
| Does it change anything? | No. It is read-only and idempotent. 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 source of an existing Plotwork SVG so you can edit the diagram. Send the text of an .svg file as svg, or a hosted link (https://cdn.plotwork.dev/d/<22 characters>.svg) as url. Returns the exact source, its kind, the stored diagram id if it was published, and a parse check. Call it first when asked to change a diagram that already exists, then edit the source and call draw_diagram (or edit_diagram); next says how to save or publish it again. Only a picture saved with embedSource true (or by sync_markdown) carries its source; otherwise status is no-source, with the title, outline, and labels to rebuild it from. A text that is not an SVG and a refused or unreachable link come back as data. Only cdn.plotwork.dev and cdn-preview.plotwork.dev are fetched (https, no redirects, 5 seconds, 1 MB); svg reads nothing from the network.

## Arguments

| Field | Type | Required | Description |
|---|---|---|---|
| `svg` | `string` | no | The text of a Plotwork SVG: the content of an .svg file in the repository. Send this or url, not both. at least 1 character; at most 1000000 characters. |
| `url` | `string` | no | The link of a hosted Plotwork picture, https://cdn.plotwork.dev/d/<22 characters>.svg. Only Plotwork's own picture hosts are fetched. Send this or svg, not both. at least 1 character; at most 200 characters. |

## Result

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `"read" \| "no-source" \| "damaged" \| "not-a-picture" \| "refused" \| "unreachable"` | yes | read: the source was found. no-source: the picture carries none. damaged: it carries one that cannot be read back. not-a-picture: the text is not an SVG. refused: the link is not one this tool fetches. unreachable: the link could not be fetched. |
| `hasSource` | `boolean` | yes | True when source is set. |
| `source` | `string \| null` | yes | The exact source the picture was drawn from, ready to edit and send to draw_diagram; null when there is none. |
| `kind` | `string \| null` | yes | The diagram kind of the source, or null. |
| `id` | `string \| null` | yes | The id of the stored diagram when the picture was published (data-plotwork-id), or null. |
| `from` | `"text" \| "url"` | yes | Where the picture came from: the text that was sent, or the link that was fetched. |
| `validation` | `object \| null` | yes | The check of the source, or null when there is none. It parses the source; draw_diagram also lays it out and returns warnings. |
| `picture` | `object \| null` | yes | What the picture says about itself, or null when the text is not an SVG. |
| `message` | `string` | yes | What happened, in one sentence. |
| `next` | `string` | yes | The next step in one sentence. |

## Behavior hints

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

## See also

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