bpmn-js-mcp

create_bpmn_lanes

Create BPMN lanes to separate roles or departments within a process pool, with automatic or manual element distribution.

Instructions

Create lanes (swimlanes) within a participant pool. Creates a bpmn:LaneSet with the specified lanes, dividing the pool height evenly (or using explicit heights). Lanes represent roles or departments within a single organization/process. Use lanes for role separation within one pool; use separate pools (participants) for separate organizations with message flows. Requires at least 2 lanes when defined manually. Alternatively, use distributeStrategy to auto-generate lanes: "by-type" groups elements into Human Tasks vs Automated Tasks lanes; "manual" uses elementIds in each lane definition to assign elements explicitly. Use assignments ([{ laneId, elementIds }]) to assign existing elements to existing lanes, or strategy (role-based | balance | minimize-crossings, with dryRun/validate) to redistribute elements across existing lanes. These forms are mutually exclusive. Use mergeFrom to convert a multi-pool collaboration into a single pool with lanes (elements are moved, message flows become sequence flows).

Input Schema

TableJSON Schema

Name	Required	Description
`lanes`	No	Lane definitions (at least 2). Optional when distributeStrategy is "by-type" (lanes are auto-generated from element types).
`dryRun`	No	With strategy: return the redistribution plan without applying changes.
`layout`	No	When true (default), runs layout after mergeFrom conversion.
`strategy`	No	Redistribute elements across EXISTING lanes (participantId optional, auto-detected); unlike distributeStrategy, it never creates lanes. 'role-based' matches assignee/candidateGroups to lane names; 'balance' spreads elements evenly; 'minimize-crossings' minimizes cross-lane flows.
`validate`	No	With strategy: run lane validation before and after redistribution.
`diagramId`	Yes	The diagram ID
`mergeFrom`	No	Convert a multi-pool collaboration into lanes within a single pool. Provide the ID of the participant to keep as the main pool. Other expanded pools become lanes, elements are moved, and message flows are converted to sequence flows.
`reposition`	No	With assignments/strategy (default true): move elements vertically into their lane.
`assignments`	No	Assign existing elements to existing lanes (participantId and lane creation not needed).
`participantId`	No	The ID of the participant (pool) to add lanes to (required unless using assignments or strategy)
`autoDistribute`	No	When true, automatically assigns existing elements in the participant to the created lanes based on matching lane names to element roles (camunda:assignee or camunda:candidateGroups, case-insensitive). Elements without role matches fall back to type-based grouping (human tasks vs automated tasks). Flow-control elements (gateways, events) are assigned to their most-connected neighbor's lane. Run layout_bpmn_diagram afterwards for clean positioning.
`distributeStrategy`	No	Auto-generate and distribute elements to lanes. "by-type": auto-creates lanes based on element types (Human Tasks, Automated Tasks). "manual": uses elementIds in each lane definition to assign elements. When omitted, lanes are created without distribution.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only supply readOnlyHint=false and openWorldHint=false, so the description carries the real burden and does so: it discloses even height division, the 2-lane minimum, that mergeFrom moves elements and converts message flows into sequence flows, and that dryRun/validate return a plan without applying changes. This is behavioral context well beyond the safety profile.

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?

Purpose and the primary lane/pool distinction are front-loaded in the first two sentences, and each subsequent sentence covers a distinct mode rather than restating. It is dense and runs long for a description, with some overlap against the 100%-covered schema, so it falls short of maximally tight.

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 a 12-parameter tool with several mutually exclusive operating modes and no output schema, the description covers mode selection, prerequisites, side effects (element movement, flow conversion), and dry-run/validation behavior. An agent has enough to choose and invoke the correct mode without further inference.

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 schema already documents each parameter and the baseline is 3. The description still adds value the schema does not: the mutual exclusivity of lanes/distributeStrategy/assignments/strategy/mergeFrom, and the distinction that strategy redistributes across EXISTING lanes and never creates them, unlike distributeStrategy.

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 ("Create lanes (swimlanes) within a participant pool") and names the underlying construct (bpmn:LaneSet). It also explicitly distinguishes itself from the sibling create_bpmn_participant by contrasting lanes for role separation within one pool versus separate pools for separate organizations.

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

Usage Guidelines5/5

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

Explicitly routes the agent among the tool's own modes: lanes vs distributeStrategy (by-type/manual), assignments vs strategy (role-based/balance/minimize-crossings), and mergeFrom, and it states these forms are mutually exclusive. It also gives the when-not case (use separate pools for separate organizations) and prerequisites (at least 2 lanes when defined manually).

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

create_bpmn_lanes

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools