Skip to main content
Glama
GuilhermeVarallo

bpmn-js-mcp

by GuilhermeVarallo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

set_bpmn_element_properties

Idempotent

Set BPMN and Camunda element properties, replace element types, and apply batch updates in one undo step with validation before changes.

Instructions

Set BPMN or Camunda extension properties on an element. Supports standard properties (name, isExecutable, documentation, default, conditionExpression) and Camunda extensions with camunda: prefix (e.g. camunda:assignee, camunda:class, camunda:type, camunda:topic). Also handles: scriptFormat/script on ScriptTask, camunda:connector, camunda:field, camunda:properties, camunda:retryTimeCycle, isExpanded on SubProcess, and cancelActivity on BoundaryEvent (false = non-interrupting). See bpmn://guides/element-properties for the full property catalog by element type. Supports optional elementType to replace the element type (e.g. bpmn:Task → bpmn:UserTask). Also accepts optional sub-objects for other concerns, settable together with properties in one call: inputOutput, formData, listeners, callActivityVariables, loop, eventDefinition. To update several elements in one call — e.g. setting camunda:assignee on every task in an executable process — pass updates: [{ elementId, properties, ... }] instead of the single-element elementId/properties/etc. fields. Every item is validated before any element is changed, and the whole batch applies as one undo step.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
loopNoLoop/multi-instance characteristics on tasks, subprocesses, or call activities. Equivalent to the former set_bpmn_loop_characteristics tool.
updatesNoBatch form: apply properties/elementType/sub-objects to several elements in one call, as a single undo step. Alternative to the single-element elementId (+ properties/elementType/...) fields above — do not combine elementId with updates.
formDataNoGenerated task form fields (camunda:FormData) for UserTasks/StartEvents. Equivalent to the former set_bpmn_form_data tool.
diagramIdYesThe diagram ID
elementIdNoThe ID of the element to update. Required unless `updates` is used instead.
listenersNoExecution listeners, task listeners, and/or error event definitions. Equivalent to the former set_bpmn_camunda_listeners tool.
propertiesNoKey-value pairs of properties to set. Use 'camunda:' prefix for Camunda extension attributes (e.g. { 'camunda:assignee': 'john', 'camunda:formKey': 'embedded:app:forms/task.html' }).
elementTypeNoOptional element type to replace the element with (e.g. "bpmn:UserTask", "bpmn:ServiceTask"). When provided, replaces the element type before setting properties.
inputOutputNoCamunda input/output parameter mapping (camunda:InputOutput). Equivalent to the former set_bpmn_input_output_mapping tool.
eventDefinitionNoEvent definition to add/replace on an event element (StartEvent, EndEvent, IntermediateCatchEvent/ThrowEvent, BoundaryEvent).
callActivityVariablesNoCallActivity in/out variable mappings (camunda:in / camunda:out). Equivalent to the former set_bpmn_call_activity_variables tool.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false and idempotentHint=true; the description adds real behavioral context beyond that: 'Every item is validated before any element is changed, and the whole batch applies as one undo step,' and it notes that listener sub-objects 'replace existing.' It stops short of describing failure modes or permission requirements.

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?

It is long but front-loaded and each sentence carries distinct information (supported property families, batch form, validation/undo semantics). The element-type replacement detail is repeated from the schema but the density is justified for a tool this broad.

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

Completeness4/5

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

For an 11-parameter, deeply nested mutation tool with no output schema, the description covers the key concerns: what can be set, the batch alternative, validation-before-application, and single-undo-step behavior. Return values are omitted, but callers of a setter rarely need them described.

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 description coverage is 100%, so the schema already documents parameters; baseline would be 3. The description adds value by clarifying the mutually exclusive single-element vs `updates` batch forms and by pointing to bpmn://guides/element-properties for the property catalog, which goes beyond what any single schema field says.

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?

The description opens with a specific verb+resource ('Set BPMN or Camunda extension properties on an element') and then enumerates the concrete property families it handles (standard props, camunda: extensions, scriptFormat, listeners, etc.). It clearly distinguishes this consolidated setter from element-creation siblings like add_bpmn_elements.

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?

It gives explicit guidance on the batch-vs-single choice ('pass `updates: [...]` instead of the single-element elementId/properties/etc. fields') and notes not to combine elementId with updates. It does not, however, state when to prefer this tool over siblings such as manage_bpmn_root_elements or add_bpmn_elements.

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

Deploy Server

Other Tools