bpmn-js-mcp

layout_bpmn_diagram

Idempotent

Arrange BPMN diagram elements automatically in a clean left-to-right layout with orthogonal connections and labels. Use after structural changes or to preview and apply layout fixes.

Instructions

Automatically arrange elements in a BPMN diagram using bpmn-auto-layout, producing a clean left-to-right layout with orthogonal connections and placed labels. Handles parallel branches, reconverging gateways, loops, boundary events, subprocesses, pools, lanes, message flows, and artifacts. Use this after structural changes (adding gateways, splitting flows) to automatically clean up the layout. The whole layout is a single undo step in bpmn_history. Use dryRun to preview changes before applying them. Use labelsOnly: true to only adjust label positions without moving elements. Partial layout: pass scopeElementId to re-layout only one participant/subprocess, or elementIds to re-layout only a set of sibling elements (e.g. a newly added branch); the rest of the diagram is left unchanged and connections crossing the boundary are re-routed. Elements positioned with move_bpmn_element are pinned and keep their position until the next full layout.

Input Schema

TableJSON Schema

Name	Required	Description
`dryRun`	No	When true, preview layout changes without applying them. Returns displacement statistics showing how many elements would move and by how much. Default: false.
`verbose`	No	When true, include full diagnostics: the non-orthogonal flow ID list, per-pool/lane sizing issues, cross-lane crossing flow IDs, the recomputed association ID list, and the full nextSteps list. Default: false — a compact summary with only actionable warnings and up to two nextSteps.
`gridSnap`	No	Optional pixel grid snapping. Pass a number (e.g. 10) to snap element positions to a pixel grid after layout. Off by default.
`diagramId`	Yes	The diagram ID
`elementIds`	No	Optional IDs of flow elements to layout in isolation. All elements must share the same parent process or subprocess; boundary events follow their host task. The subset keeps its current top-left position. Cannot be combined with scopeElementId.
`labelsOnly`	No	When true, only adjust labels without performing full layout. Useful for fixing label overlaps after importing diagrams or manual positioning.
`autosizeOnly`	No	When true, only resize pools and lanes to fit their contents without running full layout. Accepts participantId to scope resizing to a single pool. Default: false.
`participantId`	No	Optional. When autosizeOnly is true, scope pool resizing to this participant ID.
`poolExpansion`	No	Additionally run the pool/lane autosize pass after layout. The layout engine already sizes pools and lanes to fit their contents, so this is rarely needed. Default: false.
`scopeElementId`	No	Optional ID of a Participant or SubProcess to layout in isolation, leaving the rest of the diagram unchanged. The scope element keeps its top-left position but may be resized.
`expandSubprocesses`	No	When true, expand collapsed subprocesses that have internal flow-node children before running layout. Converts drill-down plane subprocesses to inline expanded subprocesses so the layout engine can arrange their children on the main plane. Default: false (preserve existing collapsed/expanded state).

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 6, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only give readOnlyHint=false and idempotentHint=true; the description adds substantial behavioral context beyond that: the whole layout is a single undo step in bpmn_history, dryRun previews changes, labelsOnly only moves labels, and elements positioned with move_bpmn_element are pinned. These are exactly the mutation-side effects an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core behavior before the mode flags and partial-layout details. It is dense and a little long, but each sentence (undo step, dryRun, labelsOnly, partial layout, pinning) carries distinct operational information rather than restating the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter mutating tool with no output schema, the description covers the key call paths (full, partial, labels-only, autosize) and the interaction with move_bpmn_element and bpmn_history. Nothing essential for correct invocation appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter interaction meaning the schema only partly conveys: the difference between scopeElementId and elementIds, that partial layout re-routes boundary-crossing connections, and that pinned move_bpmn_element positions survive until the next full layout.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (arrange elements in a BPMN diagram) plus the underlying engine (bpmn-auto-layout) and the output shape (left-to-right, orthogonal connections, placed labels). It also enumerates the structural cases it handles, which distinguishes it from align_bpmn_elements and move_bpmn_element.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('after structural changes (adding gateways, splitting flows) to automatically clean up the layout') and describes partial-layout alternatives (scopeElementId vs elementIds). It does not directly contrast with the sibling align_bpmn_elements, so the boundary with that tool is left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

layout_bpmn_diagram

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools