Tool reference

The operations an AI agent can call. Each tool has a name, a description written for a model, typed arguments, and a typed result, and its own page. The same manifest backs the HTTP API and the MCP (Model Context Protocol) server, so a tool behaves the same everywhere. Workflows come first: each does the work of several single tools and returns one combined answer.

TL;DR

Question	Answer
Which tool do I call first?	`get_diagram_syntax`, once, to read the language.
What is a workflow?	A tool that performs several engine operations and returns one combined answer, so an agent spends one turn where it would spend several. It publishes its steps and the most operations one call can perform.
What is the write loop?	Write source and call `draw_diagram`. If it returns errors, fix every one using its line, column, and hint and call again; nothing is drawn until the source is valid. Then use the pictures it returns.
How do I put diagrams in a document?	Call `sync_markdown` with the document and its path. It returns the rewritten document and the SVG files to write. Set `convertMermaid` to replace Mermaid fences first.
When do I use a single tool?	For one fine-grained step: `validate_diagram` to check, `outline_diagram` to describe, `render_diagram` to draw one theme, `search_icons` for one query.
Do any tools change anything?	Not the tools on this page: each is read-only, idempotent, and closed-world, and none saves a file. Workflows return files as data for the caller to write. The hosted server adds three tools that work on your account: `publish_diagram` stores a diagram, `list_diagrams` reads your library, and `delete_diagram` removes a diagram you name. They are described in the MCP server guide.
What happens on bad source?	A workflow returns the errors as data. `validate_diagram` returns them as data too. `render_diagram` and `outline_diagram` fail with the same diagnostics.
Where do I get this as data?	An MCP client reads every name, description, and JSON Schema from `tools/list`. The language itself comes from `get_diagram_syntax`, or from `GET /v1/vocabulary` over HTTP.

Workflows

A workflow performs several engine operations in one request. Each declares the operations it may call and the most it can perform, and a test runs every workflow with its widest input and fails if it calls an undeclared operation or passes its ceiling. An agent never has to guess: an ambiguous input comes back as candidates, and a mistake in the input comes back as data.

Workflow	Operations	Most operations per call	Replaces
`draw_diagram`	`validate`, `outline`, `render`	4	validate_diagram, outline_diagram and render_diagram calls
`edit_diagram`	`parse`, `outline`, `validate`, `render`	4	rewriting the source by hand and the draw_diagram check
`convert_mermaid`	`convertMermaid`, `validate`, `outline`, `render`	5	convert, validate_diagram, outline_diagram and render_diagram calls
`import_source`	`importSource`, `validate`, `outline`	26	validate_diagram and outline_diagram
`map_icons`	`searchIcons`	80	up to 40 search_icons calls
`sync_markdown`	`convertMermaidFences`, `renderPair`	31	convert, validate, render and sync steps for every fence in a document
`suggest_diagram`	`parse`	3	reading every kind in get_diagram_syntax to choose one
`plan_document_diagrams`	`parse`	12	reading the document section by section and choosing a kind for each
`find_pattern`	`findPatterns`	1	searching the documentation for an example to copy
`get_pattern`	`fillPattern`	1	searching for an example and copying it by hand
`draw_from_pattern`	`fillPattern`, `validate`, `outline`, `render`	5	get_pattern, validate_diagram, outline_diagram and render_diagram calls

Single tools

Each single tool does one thing. Use one when a workflow does more than you need.

Tool	Title	What it does
`read_diagram`	Read diagram	Read the source of an existing Plotwork SVG so you can edit the diagram
`compare_diagrams`	Compare diagrams	Compare two versions of a diagram by meaning, for a pull request review
`get_diagram_syntax`	Get diagram syntax	Read the diagram language as data
`validate_diagram`	Validate diagram	Check diagram source without drawing it: every error in one pass, each with line, column, and a fix hint, plus quality warnings
`render_diagram`	Render diagram	Render valid source to a self-contained, accessible SVG in the light or dark theme, with its pixel size and quality warnings
`outline_diagram`	Outline diagram	Describe valid diagram source as plain text: participants, steps, tables, and connections in reading order, to check the diagram says what you meant or to use as alt text
`search_icons`	Search icons	Find bundled icon names by keyword, idea, product, or abbreviation ("postgres", "token exchange", "s3", "cosmos db")

Bounds

Nothing a workflow does per item is unbounded. A bound that is reached is reported in the result; nothing is cut silently. Each tool page lists the bounds that apply to it.

Bound	Workflow	Value	What it limits
`maxIconNames`	`map_icons`	40	Names in one call.
`maxIconNameLength`	`map_icons`	80	Characters in one name.
`maxIconAlternatives`	`map_icons`	3	Other icons listed beside a chosen icon.
`maxIconCandidates`	`map_icons`	4	Icons listed for a name that could mean several.
`maxSummaryOutlineLines`	`draw_diagram`	40	Outline lines in a summary; detail "full" returns all of them.
`maxMarkdownLength`	`sync_markdown`	10000000	Characters in the document.
`maxDiagrams`	`sync_markdown`	30	Diagram fences, plus mermaid fences when converting, handled in one call; the rest are left alone and reported.
`maxOutputBytes`	`sync_markdown`	2000000	Bytes in the returned document and files together; fences that would pass it are not drawn and are reported.
`maxPatternQueryLength`	`find_pattern`	200	Characters in the query.
`maxPatternTags`	`find_pattern`	5	Tags a search can require.
`maxPatternResults`	`find_pattern`	5	Matches in one answer.
`maxPatternSlots`	`get_pattern`	40	Slot values in one call; draw_from_pattern takes the same.
`maxPathLength`	`sync_markdown`	300	Characters in the document path or the assets directory.
`maxPrefixLength`	`sync_markdown`	32	Characters in the file name prefix.
`maxRequestLength`	`suggest_diagram`	1000	Characters in the request.
`maxSuggestDataLength`	`suggest_diagram`	20000	Characters in the pasted data.
`maxSuggestions`	`suggest_diagram`	3	Kinds suggested in one answer.
`maxPlanDocumentLength`	`plan_document_diagrams`	10000000	Characters in the document.
`maxPlanSections`	`plan_document_diagrams`	200	Sections read; a document with more says so in caps.
`maxPlanSuggestions`	`plan_document_diagrams`	12	Sections suggested in one answer, the strongest first; the rest are counted in caps.
`maxStarterItems`	`suggest_diagram`	8	Items, rows, or columns a starter takes from the text; plan_document_diagrams takes the same.
`maxEditOperations`	`edit_diagram`	50	Operations in one call.
`maxImportLength`	`import_source`	10000000	Characters an import reads, not counting white space or lines that are only a comment. A longer text is answered with I102.
`maxImportLocalLength`	`import_source`	100000000	Characters of text in one call on the local server, which runs on your own machine. A guard on memory, not a cap a real project meets.
`maxImportTextLength`	`import_source`	10485760	Characters of text in one hosted call, comments and white space included, all files together.
`maxImportFiles`	`import_source`	200	Files in one hosted call.
`maxImportLocalFiles`	`import_source`	20000	Files in one call on the local server.
`maxImportParts`	`import_source`	24	Diagrams one import is split into when the file is too big for one picture; each is validated.
`maxImportNodes`	`import_source`	40	Boxes in an imported flow; the rest are left out with an I200 diagnostic.
`maxImportTables`	`import_source`	20	Tables in an imported schema.
`maxImportRows`	`import_source`	20	Rows of an imported matrix: endpoints, or rows of a table.
`maxImportColumns`	`import_source`	8	Columns of an imported matrix: roles, scopes, or schemes.
`maxImportPoints`	`import_source`	60	Places, slices, flows, or tiles in an imported chart.
`maxImportSeries`	`import_source`	6	Series in an imported XY chart.
`maxImportEntries`	`import_source`	60	Rows of an imported tree; a folder past it ends with an omitted line.
`maxImportCommits`	`import_source`	40	Commits of an imported git graph, the newest kept, and events of an imported timeline.
`maxImportMessages`	`import_source`	30	Messages of an imported sequence.
`maxEditTextLength`	`edit_diagram`	2000	Characters in one field of an operation, such as a statement, a find, or a replacement.
`maxCompareChanges`	`compare_diagrams`	200	Changes listed in one answer; counts and the summary cover every change.
`maxSyncPageSize`	`sync_markdown`	30	Pictures in one page of files, with page and pageSize.

Doc	Why
API reference	The same operations over HTTP, one page for each endpoint
Language reference	What the diagram source may contain
Writing diagrams with an agent	The loop in practice

TL;DR

Workflows

Single tools

Bounds

See also