# Prompts and recipes

> Page: https://docs.plotwork.dev/agents/prompts. Index of every page: https://docs.plotwork.dev/llms.txt

Requests that work well, the tool an agent calls for each, and the jobs an agent is most often given with the calls that do them.

## TL;DR

| Question | Answer |
|---|---|
| How do I phrase a request? | Say what the diagram shows and who it is for, in plain words. The agent chooses the tool, the node types, and the icons. |
| Do I name the tools? | No. A connected agent reads each tool's description and picks the right one. |
| What if the first drawing is wrong? | Say what is wrong in words, such as "put the cache between the API and the database". The agent edits the source and draws again. |
| What does an agent do when a name is ambiguous? | It asks [`map_icons`](https://docs.plotwork.dev/mcp/tools/map-icons.md) for candidates and chooses from them. It never guesses an icon name. |

## Prompts that work

Each request below leads to the tool beside it. The last column says what the tool runs.

| Request | Tool | What it runs |
|---|---|---|
| Draw a diagram of how a user signs in through an API that checks a database. | [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) | `validate`, `outline` when needed, `render` when needed |
| Check this diagram and draw it in light and dark. | [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) | `validate`, `outline` when needed, `render` when needed |
| Rename the Auth API node to gateway and add a session cache it writes to. | [`edit_diagram`](https://docs.plotwork.dev/mcp/tools/edit-diagram.md) | `parse` when needed, `outline` when needed, `validate` when needed, `render` when needed |
| Move the database into the data group and remove the old queue. | [`edit_diagram`](https://docs.plotwork.dev/mcp/tools/edit-diagram.md) | `parse` when needed, `outline` when needed, `validate` when needed, `render` when needed |
| Convert this Mermaid flowchart to Plotwork. | [`convert_mermaid`](https://docs.plotwork.dev/mcp/tools/convert-mermaid.md) | `convertMermaid`, `validate` when needed, `outline` when needed, `render` when needed |
| Migrate this Mermaid diagram to Plotwork and tell me what was lost. | [`convert_mermaid`](https://docs.plotwork.dev/mcp/tools/convert-mermaid.md) | `convertMermaid`, `validate` when needed, `outline` when needed, `render` when needed |
| Draw our database schema from this SQL. | [`import_source`](https://docs.plotwork.dev/mcp/tools/import-source.md) | `importSource`, `validate` when needed, `outline` when needed |
| Make a diagram of this docker-compose file. | [`import_source`](https://docs.plotwork.dev/mcp/tools/import-source.md) | `importSource`, `validate` when needed, `outline` when needed |
| Which roles can call which endpoints in this OpenAPI spec? | [`import_source`](https://docs.plotwork.dev/mcp/tools/import-source.md) | `importSource`, `validate` when needed, `outline` when needed |
| Chart this CSV. | [`import_source`](https://docs.plotwork.dev/mcp/tools/import-source.md) | `importSource`, `validate` when needed, `outline` when needed |
| Which icons should I use for S3, Lambda, Postgres and a queue on AWS? | [`map_icons`](https://docs.plotwork.dev/mcp/tools/map-icons.md) | `searchIcons` |
| Pick icons for every service in this architecture. | [`map_icons`](https://docs.plotwork.dev/mcp/tools/map-icons.md) | `searchIcons` |
| Replace the Mermaid diagrams in README.md with Plotwork diagrams. | [`sync_markdown`](https://docs.plotwork.dev/mcp/tools/sync-markdown.md) | `convertMermaidFences` when needed, `renderPair` |
| Render the diagram fences in docs/login.md and give me the files to write. | [`sync_markdown`](https://docs.plotwork.dev/mcp/tools/sync-markdown.md) | `convertMermaidFences` when needed, `renderPair` |
| Which diagram should I use to show who can call which endpoint? | [`suggest_diagram`](https://docs.plotwork.dev/mcp/tools/suggest-diagram.md) | `parse` when needed |
| What is the best way to draw where our cloud spend goes? | [`suggest_diagram`](https://docs.plotwork.dev/mcp/tools/suggest-diagram.md) | `parse` when needed |
| Suggest a diagram for comparing three message brokers. | [`suggest_diagram`](https://docs.plotwork.dev/mcp/tools/suggest-diagram.md) | `parse` when needed |
| Which parts of this design doc need a diagram? | [`plan_document_diagrams`](https://docs.plotwork.dev/mcp/tools/plan-document-diagrams.md) | `parse` when needed |
| Add pictures to this Confluence page. | [`plan_document_diagrams`](https://docs.plotwork.dev/mcp/tools/plan-document-diagrams.md) | `parse` when needed |
| Plan the diagrams for our onboarding guide. | [`plan_document_diagrams`](https://docs.plotwork.dev/mcp/tools/plan-document-diagrams.md) | `parse` when needed |
| Draw a three-tier network with load balancers. | [`find_pattern`](https://docs.plotwork.dev/mcp/tools/find-pattern.md) | `findPatterns` |
| Which pattern shows a primary and a replica database in two availability zones? | [`find_pattern`](https://docs.plotwork.dev/mcp/tools/find-pattern.md) | `findPatterns` |
| Find a serverless API pattern for AWS. | [`find_pattern`](https://docs.plotwork.dev/mcp/tools/find-pattern.md) | `findPatterns` |
| Show me the three-tier network pattern for Azure and rename the office network to Branch office. | [`get_pattern`](https://docs.plotwork.dev/mcp/tools/get-pattern.md) | `fillPattern` |
| What can I change in the two-zone network pattern? | [`get_pattern`](https://docs.plotwork.dev/mcp/tools/get-pattern.md) | `fillPattern` |
| Draw a two-zone network on AWS with a replicated database. | [`draw_from_pattern`](https://docs.plotwork.dev/mcp/tools/draw-from-pattern.md) | `fillPattern`, `validate` when needed, `outline` when needed, `render` when needed |
| Draw the web application pattern for Azure and call the API "Billing API". | [`draw_from_pattern`](https://docs.plotwork.dev/mcp/tools/draw-from-pattern.md) | `fillPattern`, `validate` when needed, `outline` when needed, `render` when needed |

## Recipes

A recipe is a job and the calls that do it, in order. Each tool name links to its page.

| Job | Calls | What you get |
|---|---|---|
| Draw a diagram from a request | [`get_diagram_syntax`](https://docs.plotwork.dev/mcp/tools/get-diagram-syntax.md), then [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) | Read the language once, write source, and call `draw_diagram` until it reports no errors. It returns an outline to check against the request and the SVG for light and dark. |
| Choose the kind of diagram | [`suggest_diagram`](https://docs.plotwork.dev/mcp/tools/suggest-diagram.md), then [`get_diagram_syntax`](https://docs.plotwork.dev/mcp/tools/get-diagram-syntax.md), then [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) | `suggest_diagram` ranks the kinds for the request and any pasted data, each with a reason and a starter that parses. Read the chosen kind in full, edit the starter, and draw it. |
| Add pictures to a long document | [`plan_document_diagrams`](https://docs.plotwork.dev/mcp/tools/plan-document-diagrams.md), then [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md), then [`sync_markdown`](https://docs.plotwork.dev/mcp/tools/sync-markdown.md) | `plan_document_diagrams` lists the sections a picture would help, each with a starter drafted from its text. Check each with `draw_diagram`, put it under its heading as a diagram fence, then `sync_markdown` draws them all. |
| Start from a common architecture | [`find_pattern`](https://docs.plotwork.dev/mcp/tools/find-pattern.md), then [`draw_from_pattern`](https://docs.plotwork.dev/mcp/tools/draw-from-pattern.md) | `find_pattern` ranks ready-made, checked diagrams for the request. `draw_from_pattern` fills one with a provider flavour and the names the request uses, and draws it. |
| Choose icons for many services | [`map_icons`](https://docs.plotwork.dev/mcp/tools/map-icons.md), then [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) | `map_icons` picks an icon for each name and lists candidates for an ambiguous one. Put each chosen icon on its node, then draw. |
| Move one Mermaid diagram to Plotwork | [`convert_mermaid`](https://docs.plotwork.dev/mcp/tools/convert-mermaid.md) | It returns Plotwork source, every diagnostic with its hint, and the drawing once the source is valid. Choose node types and icons, then check the result. |
| Turn the diagrams of a Markdown file into pictures | [`sync_markdown`](https://docs.plotwork.dev/mcp/tools/sync-markdown.md) | It returns the rewritten document and the SVG files to write. Set `convertMermaid` to replace Mermaid fences first. |
| Change a diagram that already exists as a hosted link or an SVG file | [`read_diagram`](https://docs.plotwork.dev/mcp/tools/read-diagram.md), then [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) | `read_diagram` returns the exact source from the link or the file. Edit it, call `draw_diagram` with `embedSource` true, then write the file again or publish again: a published diagram gets a new link, so replace the old one. |
| Read and check a diagram someone else wrote | [`validate_diagram`](https://docs.plotwork.dev/mcp/tools/validate-diagram.md), then [`outline_diagram`](https://docs.plotwork.dev/mcp/tools/outline-diagram.md) | `validate_diagram` returns every error and warning. `outline_diagram` describes a valid diagram as plain text, so an agent can say what it shows. |

## What the operations mean

A workflow is made of engine operations. Each is one small, checked step.

| Operation | What it does |
|---|---|
| `validate` | Parse the source and lint it: every error, and the quality, icon, and group-type warnings. |
| `outline` | Describe a valid diagram as plain text. |
| `render` | Lay out and paint a valid diagram in one color scheme. |
| `parse` | Parse the source and return its errors, without laying it out or linting it. |
| `convertMermaid` | Convert one Mermaid diagram to Plotwork source. |
| `importSource` | Read a file of another format (SQL, Prisma, Drizzle, OpenAPI, Terraform, a Terraform plan or state, Bicep, ARM, Pulumi, CloudFormation, CDK, Compose, Kubernetes, Helm, Kustomize, Backstage, Structurizr, AsyncAPI, GitHub Actions, GitLab CI/CD, Azure Pipelines, CSV, JSON, a tree, or a git log) into Plotwork source. |
| `searchIcons` | Search the bundled icons for a name or an idea. |
| `convertMermaidFences` | Replace every convertible mermaid fence of a Markdown document with a diagram fence. |
| `renderPair` | Draw one diagram in the light and the dark theme with its text description. |
| `findPatterns` | Search the pattern library for an architecture by its words, with optional provider, tag, and kind filters. |
| `fillPattern` | Fill one pattern for one flavour with slot values: its source, slots, notes, group tree, and outline. |

## See also

| Doc | Why |
|---|---|
| [Plotwork for AI agents](https://docs.plotwork.dev/agents/overview.md) | The tools and the ways to call them |
| [Rules file for your agent](https://docs.plotwork.dev/agents/rules.md) | Guidance to paste into a project |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | Every tool, with its arguments and result |
| [Architecture patterns](https://docs.plotwork.dev/architecture-patterns.md) | The ready-made diagrams `find_pattern` ranks |