For agents
Prompts and recipes
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 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 | validate, outline when needed, render when needed |
| Check this diagram and draw it in light and dark. | draw_diagram | validate, outline when needed, render when needed |
| Rename the Auth API node to gateway and add a session cache it writes to. | edit_diagram | 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 | parse when needed, outline when needed, validate when needed, render when needed |
| Convert this Mermaid flowchart to Plotwork. | convert_mermaid | convertMermaid, validate when needed, outline when needed, render when needed |
| Migrate this Mermaid diagram to Plotwork and tell me what was lost. | convert_mermaid | convertMermaid, validate when needed, outline when needed, render when needed |
| Draw our database schema from this SQL. | import_source | importSource, validate when needed, outline when needed |
| Make a diagram of this docker-compose file. | import_source | importSource, validate when needed, outline when needed |
| Which roles can call which endpoints in this OpenAPI spec? | import_source | importSource, validate when needed, outline when needed |
| Chart this CSV. | import_source | importSource, validate when needed, outline when needed |
| Which icons should I use for S3, Lambda, Postgres and a queue on AWS? | map_icons | searchIcons |
| Pick icons for every service in this architecture. | map_icons | searchIcons |
| Replace the Mermaid diagrams in README.md with Plotwork diagrams. | sync_markdown | convertMermaidFences when needed, renderPair |
| Render the diagram fences in docs/login.md and give me the files to write. | sync_markdown | convertMermaidFences when needed, renderPair |
| Which diagram should I use to show who can call which endpoint? | suggest_diagram | parse when needed |
| What is the best way to draw where our cloud spend goes? | suggest_diagram | parse when needed |
| Suggest a diagram for comparing three message brokers. | suggest_diagram | parse when needed |
| Which parts of this design doc need a diagram? | plan_document_diagrams | parse when needed |
| Add pictures to this Confluence page. | plan_document_diagrams | parse when needed |
| Plan the diagrams for our onboarding guide. | plan_document_diagrams | parse when needed |
| Draw a three-tier network with load balancers. | find_pattern | findPatterns |
| Which pattern shows a primary and a replica database in two availability zones? | find_pattern | findPatterns |
| Find a serverless API pattern for AWS. | find_pattern | findPatterns |
| Show me the three-tier network pattern for Azure and rename the office network to Branch office. | get_pattern | fillPattern |
| What can I change in the two-zone network pattern? | get_pattern | fillPattern |
| Draw a two-zone network on AWS with a replicated database. | draw_from_pattern | 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 | 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, then draw_diagram | 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, then get_diagram_syntax, then draw_diagram | 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, then draw_diagram, then sync_markdown | 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, then draw_from_pattern | 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, then draw_diagram | 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 | 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 | 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, then draw_diagram | 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, then outline_diagram | 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 | The tools and the ways to call them |
| Rules file for your agent | Guidance to paste into a project |
| Tool reference | Every tool, with its arguments and result |
| Architecture patterns | The ready-made diagrams find_pattern ranks |