Converts Mermaid flowchart code into BPMN 2.0 diagrams, enabling AI agents to bootstrap business process diagrams from concise Mermaid syntax.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP-BPMN Server create a new BPMN process for order handling"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that enables AI agents to create, manipulate, and manage BPMN 2.0 (Business Process Model and Notation) diagrams programmatically.
MCP-BPMN provides a standardized interface for AI assistants to work with business process diagrams. It generates valid BPMN 2.0 XML files that can be viewed and edited in any BPMN-compliant tool (VS Code BPMN Editor, Camunda Modeler, etc.).
✅ Complete BPMN 2.0 Support: Events, activities, gateways, pools, and sequences
✅ Mermaid to BPMN Conversion: Bootstrap BPMN diagrams from Mermaid flowcharts
✅ Smart Auto-Layout: Automatic positioning with branch handling for gateways
✅ File Persistence: Save diagrams locally for editing in visual tools
✅ Proper Visual Rendering: Accurate waypoint calculation for connections
✅ Enterprise-Ready: Clean API design following BPMN standards
✅ No Browser Dependencies: Server-side XML generation
Related MCP server: MCP Diagram Server
# Clone the repository
git clone https://github.com/your-org/mcp-bpmn.git
cd mcp-bpmn
# Install dependencies
npm install
# Build the project
npm run build
# Run tests (optional)
npm testAdd to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"mcp-bpmn": {
"command": "node",
"args": ["/absolute/path/to/mcp-bpmn/dist/server/index.js"]
}
}
}Use the compiled CommonJS bundle:
node dist/server/bundle.cjsMCP-BPMN uses a stateful API design where you work with one diagram at a time. All operations apply to the current diagram context, eliminating the need for processId parameters.
new_bpmnCreate a new BPMN process or collaboration diagram and set it as the current context.
{
name: "Order Processing",
type: "process" // or "collaboration" (optional, defaults to "process")
}new_from_mermaidCreate a new BPMN diagram from Mermaid code and set it as the current context.
{
name: "My Process",
mermaidCode: "graph TD\n A[Start] --> B[Task] --> C[End]"
}open_bpmnOpen an existing BPMN file and set it as the current context.
{
filename: "my-process.bpmn"
}open_mermaid_fileOpen and convert a Mermaid file to BPMN, setting it as the current context.
{
filename: "my-flowchart.mmd"
}saveSave the current diagram to its file (requires filename to be set).
{}save_asSave the current diagram with a new filename.
{
filename: "my-process.bpmn"
}closeClose the current diagram and clear the context.
{}currentGet information about the current diagram.
{}add_eventAdd events (start, end, intermediate, boundary) to the current diagram.
{
eventType: "start", // start, end, intermediate-throw, intermediate-catch, boundary
name: "Order Received",
eventDefinition: "message", // optional: message, timer, error, signal, etc.
position: { x: 100, y: 200 } // optional
}add_activityAdd activities (tasks, subprocesses) to the current diagram.
{
activityType: "userTask", // task, userTask, serviceTask, scriptTask, etc.
name: "Review Order",
position: { x: 250, y: 200 }, // optional
properties: { assignee: "reviewer" } // optional
}add_gatewayAdd gateways for branching logic to the current diagram.
{
gatewayType: "exclusive", // exclusive, parallel, inclusive, eventBased
name: "Payment Check",
position: { x: 400, y: 200 } // optional
}connectConnect two elements with a sequence flow in the current diagram.
{
sourceId: "StartEvent_1",
targetId: "UserTask_1",
label: "Start Flow", // optional
condition: "amount > 1000" // optional, for conditional flows
}add_poolAdd a pool (participant) to a collaboration diagram.
{
name: "Customer",
position: { x: 100, y: 100 }, // optional
size: { width: 600, height: 250 } // optional
}add_laneAdd a lane to a pool (not yet fully implemented).
{
poolId: "Participant_1",
name: "Sales Department",
position: "bottom" // optional
}list_elementsList all elements in the current diagram.
{
elementType: "bpmn:Task" // optional filter
}get_elementGet details of a specific element.
{
elementId: "UserTask_1"
}update_elementUpdate element properties.
{
elementId: "UserTask_1",
name: "Updated Task Name",
properties: { assignee: "john.doe" }
}delete_elementDelete an element and its connections.
{
elementId: "Task_1"
}exportExport the current diagram as BPMN 2.0 XML.
{
format: "xml", // only xml is currently supported
formatted: true // optional, defaults to true
}validateValidate the current diagram structure.
{}auto_layoutApply automatic layout to position elements in the current diagram.
{
algorithm: "horizontal" // currently only horizontal is supported
}list_diagramsList all saved BPMN diagrams.
{}delete_diagram_fileDelete a saved diagram file.
{
filename: "old-process.bpmn"
}get_diagrams_pathGet the storage path for diagrams.
{}The MCP-BPMN server uses a stateful design where you work with one diagram at a time:
Create or Open: Start by creating a new diagram (new_bpmn, new_from_mermaid) or opening an existing one (open_bpmn, open_mermaid_file)
Manipulate: All operations (add_event, connect, etc.) apply to the current diagram
Save: Save your work with save or save_as
Close: Close the current diagram with close
If you try to perform operations without a current context, you'll get a helpful error message:
No current context. Please create a diagram first with:
- new_bpmn(name) to create a new BPMN diagram
- new_from_mermaid(name, mermaidCode) to convert from Mermaid
- open_bpmn(filename) to open an existing BPMN file
- open_mermaid_file(filename) to convert a Mermaid file// Step 1: Create a new process (sets it as current context)
await new_bpmn({ name: "Approval Workflow" });
// Step 2: Add elements (all operations apply to current diagram)
await add_event({ eventType: "start", name: "Request Received" });
await add_activity({ activityType: "userTask", name: "Review Request" });
await add_gateway({ gatewayType: "exclusive", name: "Approved?" });
await add_activity({ activityType: "serviceTask", name: "Process Approval" });
await add_activity({ activityType: "userTask", name: "Handle Rejection" });
await add_event({ eventType: "end", name: "Complete" });
// Step 3: Connect elements
await connect({ sourceId: "StartEvent_1", targetId: "UserTask_1" });
await connect({ sourceId: "UserTask_1", targetId: "ExclusiveGateway_1" });
await connect({ sourceId: "ExclusiveGateway_1", targetId: "ServiceTask_1", label: "Yes" });
await connect({ sourceId: "ExclusiveGateway_1", targetId: "UserTask_2", label: "No" });
await connect({ sourceId: "ServiceTask_1", targetId: "EndEvent_1" });
await connect({ sourceId: "UserTask_2", targetId: "EndEvent_1" });
// Step 4: Apply auto-layout for proper positioning
await auto_layout();
// Step 5: Save and export the diagram
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();// Step 1: Create from Mermaid syntax (much more concise!)
await new_from_mermaid({
name: "Approval Workflow",
mermaidCode: `
graph TD
A((Request Received)) --> B[Review Request]
B --> C{Approved?}
C -->|Yes| D[Process Approval]
C -->|No| E[Handle Rejection]
D --> F((Complete))
E --> F
`
});
// Step 2: Apply auto-layout (Mermaid conversion includes basic layout)
await auto_layout();
// Step 3: Make additional edits if needed
await update_element({
elementId: "UserTask_1",
properties: { assignee: "reviewer" }
});
// Step 4: Save and export
await save_as({ filename: "approval-workflow.bpmn" });
const xml = await export();// Create first diagram
await new_bpmn({ name: "Process A" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task A" });
await save_as({ filename: "process-a.bpmn" });
// Create second diagram (automatically closes the first)
await new_bpmn({ name: "Process B" });
await add_event({ eventType: "start" });
await add_activity({ activityType: "task", name: "Task B" });
await save_as({ filename: "process-b.bpmn" });
// Go back to first diagram
await open_bpmn({ filename: "process-a.bpmn" });
await add_event({ eventType: "end" });
await save();
// Check current diagram info
const info = await current();
console.log(info); // Shows: { name: "Process A", filename: "process-a.bpmn", ... }BPMN diagrams are automatically saved to your local filesystem:
Unix/Linux/Mac: ~/mcp-bpmn/
Windows: %USERPROFILE%\mcp-bpmn\
Custom path via environment variable:
export MCP_BPMN_DIAGRAMS_PATH=/custom/pathFiles are named: {ProcessId}_{ProcessName}.bpmn
TypeScript - Type-safe development
Node.js - Runtime environment
MCP SDK - Model Context Protocol implementation
Jest - Testing framework
SimpleBpmnEngine - Core BPMN XML generation without browser dependencies
DiagramContext - Stateful context management for current diagram
AutoLayout - Smart positioning algorithm with branch handling
BpmnRequestHandler - MCP request processing
MermaidConverter - Mermaid to BPMN conversion
TypeMappings - BPMN element type conversions
IdGenerator - Consistent ID generation
mcp-bpmn/
├── src/
│ ├── core/ # Core BPMN engine
│ ├── server/ # MCP server implementation
│ ├── utils/ # Utilities (layout, ID generation)
│ ├── types/ # TypeScript type definitions
│ └── config/ # Configuration
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── dist/ # Compiled output
└── docs/ # Documentationnpm run build # Build TypeScript
npm run build:bundle # Build CommonJS bundle
npm run build:watch # Build with watch mode
npm test # Run all tests
npm run test:unit # Run unit tests only
npm run test:e2e # Run end-to-end tests
npm run lint # Run ESLint
npm run dev # Development mode with hot reload
npm start # Start the MCP serverThe project includes comprehensive test coverage:
Unit Tests: Core functionality testing
Integration Tests: Handler and tool testing
E2E Tests: Full MCP protocol testing
Run tests with:
npm test # All tests
npm run test:coverage # With coverage report
npm run test:watch # Watch modeFast XML Generation: Direct XML string building
Efficient Layout: O(n) complexity for standard flows
Minimal Dependencies: No browser or heavy libraries
Bundled Size: ~48KB CommonJS bundle
SVG export not yet implemented (XML only)
Vertical layout algorithm pending
Lanes within pools not fully implemented
Complex gateway merging patterns need manual positioning
SVG export support
Vertical and radial layout algorithms
Enhanced BPMN validation framework
Mermaid diagram import/export (Completed!)
Natural language to BPMN conversion
Integration with Camunda/Activiti engines
Subprocess expansion support
Message flow between pools
BPMN execution simulation
Contributions are welcome! Please:
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
TypeScript with strict mode
ESLint configuration provided
Jest for testing
Conventional commits
MIT License - see LICENSE file for details.
Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: See /docs folder for detailed guides
Built on the Model Context Protocol specification
Inspired by bpmn-js for BPMN standards
Thanks to the Anthropic team for MCP development
Add an activity to the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the activity | |
| position | No | Position of the activity (optional) | |
| properties | No | Additional properties (assignee, candidateGroups, etc.) | |
| activityType | Yes | Type of activity |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details beyond the basic action. It does not mention side effects (e.g., diagram modification), required permissions, or error conditions. Given the absence of annotations, the description fails to disclose important behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) and front-loaded with the verb. However, it is too brief to be informative; it essentially restates the tool name without adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (including nested objects and an enum) and no output schema, the description is severely incomplete. It does not explain return values, error handling, or behavior when the current diagram is not set, making it insufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description adds no additional meaning beyond the schema; it does not compensate for any missing parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add an activity') and context ('to the current diagram'). It uses a specific verb and resource, but does not differentiate from sibling tools like add_event or add_gateway, which also add elements to the diagram.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., a diagram must be open) or exclusions (e.g., not for adding events or gateways).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an event to the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name of the event | |
| attachTo | No | ID of activity to attach to (for boundary events) | |
| position | No | Position of the event (optional) | |
| eventType | Yes | Type of event to add | |
| eventDefinition | No | Event definition type (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Add', implying mutation, but provides no details about side effects, required permissions, or what happens if required fields are missing. No annotations are present to supplement, so the description fails to disclose important behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks structure. While it earns its place by being brief, it does not provide enough information for a tool with 5 parameters and nested objects. A bit more detail would improve usability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 params, enums, nested position object, and no output schema), the description is incomplete. It does not mention event types, definitions, or the optional nature of position and attachTo. An AI agent would need to rely entirely on the schema, which may not be sufficient for correct invocation in all scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any information about parameters beyond what the schema already provides. It is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Add an event' and the context 'to the current diagram'. It distinguishes from sibling tools like add_activity or add_gateway by specifying 'event', though it could be more explicit about BPMN event types. Overall, it's clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like add_activity or add_gateway. No prerequisites are mentioned (e.g., an open diagram is implied but not stated). The description offers no instructions on when not to use or what conditions must be met.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a gateway to the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name of the gateway (optional) | |
| position | No | Position of the gateway (optional) | |
| gatewayType | Yes | Type of gateway |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It only states the action without disclosing side effects (e.g., modifies current diagram, requires open diagram, or behavior if gateway already exists). Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded and concise. No wasted words; it captures the essential action efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (including an enum and nested object) and no output schema, the description is too minimal. It omits context like needing an open diagram, interpretation of position, or list of gateway types.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all three parameters have descriptions). The description adds no additional parameter meaning beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('add') and resource ('gateway to the current diagram'), but does not distinguish it from similar sibling tools like add_event or add_activity, which have the same pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., add_event or add_pool). The description implies usage when adding a gateway, but lacks context on prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a lane to an existing pool in the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the lane | |
| poolId | Yes | ID of the pool to add lane to | |
| position | No | Position relative to existing lanes | bottom |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It only states the basic action without revealing side effects, required context (e.g., pool must exist), or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and object, containing no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with full schema coverage and no output schema, the description minimally covers the purpose but lacks completeness on conditions like pool existence or position semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'lane to an existing pool in the current diagram', distinguishing it from siblings like add_pool that add pools instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding lanes to existing pools but provides no explicit guidance on when to use versus alternatives, nor any conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a pool to the current collaboration diagram
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the participant/pool | |
| size | No | Size of the pool (optional) | |
| position | No | Position of the pool (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the basic action. It does not mention whether the tool is destructive, if it requires an open diagram, what happens if the pool already exists, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the key information. However, it might be too terse, lacking additional context that could fit without much increase in length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of nested objects in parameters and no output schema, the description is incomplete. It does not explain the pool's role in the collaboration diagram, nor does it mention that it might contain lanes, which is relevant given the sibling add_lane tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the input schema, so the description adds no additional meaning beyond what is already provided. The baseline score of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Add) and the resource (a pool) and specifies the context (current collaboration diagram). It is straightforward, but does not differentiate from sibling tools like add_event or add_lane.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like add_event, add_gateway, or add_lane. The agent has no context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply automatic layout to the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| algorithm | No | Layout algorithm to use | horizontal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral transparency. It only states the action without disclosing side effects (e.g., whether the layout is deterministic, reversibility, or impact on existing element positions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 6 words, front-loading the purpose with no wasted words. It is appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema), the description covers the basic action. However, it lacks behavioral context such as whether the layout replaces or adjusts the existing arrangement, and how the algorithm parameter affects the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full coverage (100%) for the single parameter, including an enum and default. The description adds no additional parameter information, so it meets the baseline but adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies automatic layout to the current diagram, using a specific verb and resource. It distinguishes from sibling tools as no other sibling performs layout, though it could be more precise about rearranging elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool, prerequisites, or alternatives, leaving the agent to infer its purpose without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the current diagram and clear the context
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full responsibility. It states the tool closes and clears context, but doesn't reveal whether changes are saved, if confirmation is required, or if the action is reversible. This leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy. Every word adds meaning: 'Close', 'current diagram', 'clear the context'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description is minimal but covers the core action. However, lacking details about save behavior or state changes, it is only partially complete for a tool that modifies the application state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100% (empty object). The description adds no parameter information, but none is needed. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'close' and specifies the resource 'current diagram', which is clear and unambiguous. It also adds 'clear the context', which might be slightly vague but doesn't mislead. No sibling tool has a similar purpose, so differentiation is adequate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., save before close). It doesn't mention prerequisites or consequences of closing without saving. The description is purely declarative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect two elements in the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Label for the connection (optional) | |
| sourceId | Yes | ID of the source element | |
| targetId | Yes | ID of the target element | |
| condition | No | Condition expression for the flow (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only says 'Connect two elements'. It does not disclose that the tool likely creates a sequence flow or message flow, whether it is destructive (e.g., overwrites existing connections), or if it requires source/target to be compatible types. The behavior is assumed but not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it could be slightly more detailed without sacrificing conciseness, e.g., noting that the tool creates a flow between existing elements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (2 required, 2 optional) and no output schema or annotations, the description is insufficient. It does not explain the purpose of optional parameters like 'label' or 'condition', nor does it provide context for when to use this tool in a diagram editing workflow. More completeness is needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with descriptions for all 4 parameters, so the baseline is 3. The description adds no additional parameter information beyond what the schema provides. For a simple connection tool, this is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'connect' and the resource 'two elements in the current diagram'. It is specific enough to distinguish from sibling tools like 'add_event' or 'add_activity', which focus on creating individual elements. However, it could be more precise about what 'connect' entails (e.g., flow, relation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not mention that elements must already exist or that the connection represents a flow in BPMN. There is no explicit when-not or context for using optional parameters like 'label' or 'condition'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It states 'get information' which suggests a read operation, but does not explicitly confirm it is non-destructive, safe, or describe any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence with no extraneous words. Every word is necessary and adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what type of information is returned (e.g., properties, elements). It lacks details like return format or content, leaving the agent unsure of the tool's utility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema description coverage is 100%. The description adds meaning beyond the schema by clarifying the tool returns information about the current diagram, which is not obvious from the name 'current' alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a verb 'Get' and a resource 'information about the current diagram', clearly indicating the tool retrieves data. However, it does not specify what kind of information (e.g., metadata, element list), leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when information about the current diagram is needed, but provides no explicit guidance on when to use or not, nor references to alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a saved BPMN diagram file
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Filename of the diagram to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden for behavioral disclosure. It only states 'Delete' (destructive action) but fails to specify effects (permanent deletion, permissions needed, behavior if file is open or nonexistent). Should detail side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. It could be slightly more efficient but is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and a single parameter, the description omits critical context: confirmation, recovery, impact on open files, and error scenarios. Not complete enough despite low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds no value beyond the schema's property description ('Filename of the diagram to delete'). No extra meaning like format, path, or case sensitivity is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a saved BPMN diagram file' uses a specific verb ('Delete') and resource ('saved BPMN diagram file'), clearly distinguishing it from sibling tools like open_bpmn, new_bpmn, list_diagrams, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., close, list_diagrams) or what prerequisites exist (e.g., file must exist, permissions). The lack of when-not or context makes usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an element from the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| elementId | Yes | ID of the element to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the action without disclosing any behavioral traits such as permanence, undoability, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is efficient and front-loaded with the action and resource, containing no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool, the description is minimally viable, but it lacks mention of the current diagram requirement and return values. Given no output schema, the agent may benefit from more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the elementId parameter. The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete an element from the current diagram' clearly states the action (delete) and the resource (element), and it distinguishes from sibling tools like update_element or add_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deletion but does not provide explicit guidelines on when to use this tool versus alternatives, nor does it mention prerequisites like having an open diagram or the element existing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the current diagram as BPMN XML
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Export format | xml |
| formatted | No | Whether to format the output (for XML) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior, but it only states the action without describing side effects (e.g., file creation, download initiation), return values, or state changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the key action. However, it omits important details, trading off completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params, no output schema), the description is insufficient; it does not explain the export process, output format behavior, or how the result is delivered (e.g., download, string return).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and parameter descriptions are provided in the schema. The description adds no additional meaning beyond the schema fields, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Export the current diagram as BPMN XML', which clearly identifies the action and resource, but is misleading because the schema includes an SVG format option, implying the tool can also export as SVG.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings like save, save_as, or other export-related tools. The description does not specify prerequisites, context, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the path where BPMN diagrams are saved
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It does not disclose whether the tool is read-only, what side effects (if any) occur, whether it requires certain diagram to be active, or how the path is returned (absolute/relative). The description merely states the action without behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence of 9 words. It is front-loaded with the verb and resource, containing no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description is minimally adequate. However, it lacks details about the return value format, potential conditions (e.g., empty path if no diagrams saved), and platform-specific behavior, leaving some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and the description correctly states the tool's purpose. Since there are no parameters to document, the description is adequate and meets the baseline score of 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and references a clear resource ('the path where BPMN diagrams are saved'). It is distinct from sibling tools like 'list_diagrams' (which lists diagram files) or 'open_bpmn' (which opens a diagram), making its purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when the path is needed for file operations vs. other diagram interactions. There are no hints about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific element in the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| elementId | Yes | ID of the element |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only says 'get details' without specifying what details are returned, whether the operation is read-only, or any side effects. Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, concise sentence with no waste. Could be improved by front-loading more information, but it is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema and does not explain what 'details' entails. Given the complexity of sibling tools and lack of annotations, the description is incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's simple 'ID of the element'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get details) and the resource (specific element in the current diagram). It is specific but does not differentiate from sibling tools like list_elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as list_elements or update_element. The description does not mention any prerequisites or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all saved BPMN diagrams
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond the obvious read-only nature implied by the verb 'list'. No mention of side effects, authentication requirements, or rate limits. With no annotations, the description carries the full burden but provides minimal context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is appropriately sized and front-loaded. Every word is necessary and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema, no annotations), the description covers the basic purpose. However, it could be more complete by hinting at the output format or any filtering capabilities, but it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds no parameter info, but this is adequate since no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all saved BPMN diagrams' uses a specific verb and resource, clearly indicating the tool's function. It distinguishes itself from siblings like open_bpmn, new_bpmn, and delete_diagram_file which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, limitations, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all elements in the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| elementType | No | Filter by element type (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only indicates a non-mutating read operation. It does not specify return format, pagination, error handling, or whether the result includes all properties of elements. This leaves significant ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous information. It is concise and to the point, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, the description is adequate but incomplete. It omits details about the output format (e.g., list of names or full objects) and any implied constraints (e.g., returns all elements or only those matching filter). Given no output schema, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single parameter 'elementType' has a description). The tool's description does not add any further meaning beyond the schema, so a baseline of 3 is appropriate. No additional parameter guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all elements') and the scope ('in the current diagram'). It uses a specific verb and resource, and distinguishes itself from sibling tools like 'get_element' (single element) and 'add_element' (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives like 'get_element' or when filtering is needed. The description does not mention any prerequisites, context, or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new BPMN diagram and set it as current context
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the diagram | |
| type | No | Type of diagram to create | process |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It states that the diagram becomes current context, which is a key behavior. However, it does not disclose side effects like overwriting behavior, permission requirements, or limit constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 11 words, front-loaded with action verb. No wasted words; each word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should clarify return value or state changes. It mentions setting current context but lacks details on validation, name uniqueness, or diagram initialization. For a creation tool, it is somewhat incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds no additional meaning beyond what the schema provides for name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new BPMN diagram and set it as current context', specifying verb and resource. It distinguishes from siblings like open_bpmn (opens existing) and new_from_mermaid (creates from mermaid).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Sibling tools like new_from_mermaid are not compared, and there is no mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new BPMN diagram from Mermaid code and set it as current context
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new diagram | |
| mermaidCode | Yes | Mermaid flowchart code to convert |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the behavioral trait of setting the diagram as current context, which is important for understanding its impact. However, without annotations, it fails to mention other behaviors like whether the diagram is saved automatically, error handling, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of 12 words, front-loaded with the primary action. Every word is necessary and directly contributes to understanding the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity (2 params, no output schema), the description omits important context: the expected format of 'mermaidCode', whether the diagram is saved, what happens to previous context, and error handling. It is too minimal for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters ('name' and 'mermaidCode'). The tool description adds no additional meaning beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create', the resource 'BPMN diagram', and the unique input 'from Mermaid code', and also mentions the side effect 'set it as current context'. This distinguishes it from siblings like 'new_bpmn' (likely creates empty diagram) and 'open_mermaid_file' (opens existing file).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., 'new_bpmn' for empty diagrams, 'open_mermaid_file' for files). It does not specify when not to use it or its prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an existing BPMN file and set it as current context
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Filename of the BPMN diagram to open |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It states the tool opens a file and sets context but does not disclose error behavior (e.g., if file not found), effect on unsaved changes, or whether the file is loaded into memory. Behavioral details are insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description is largely complete. It states the action and outcome (set as current context). However, it could briefly mention what happens to the previous context or that the diagram is loaded for editing. Still, it covers the essential behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with filename described as 'Filename of the BPMN diagram to open'. The description adds no additional semantic meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool opens a BPMN file and sets it as current context. The verb 'open' and resource 'BPMN file' are specific, and it distinguishes from sibling tools like 'new_bpmn' (creates new) and 'open_mermaid_file' (opens mermaid files).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to open an existing BPMN file, but it does not provide explicit guidance on when to use it versus alternatives (e.g., versus 'new_bpmn' or 'open_mermaid_file'). No when-not-to-use or exclusion criteria are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a Mermaid file, convert it to BPMN, and set as current context
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Filename of the Mermaid file to open and convert |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses three actions: open file, convert to BPMN, set as current context. However, it does not explain side effects (e.g., overwriting current context) or error conditions. For a simple tool this is acceptable but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's core purpose with no extraneous words. It is front-loaded with key actions and perfectly sized for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description should clarify what 'set as current context' means and what the user can expect after execution. It is adequate for a simple state mutation but lacks detail on outcomes or return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter 'filename' with a clear description. The tool description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool opens a Mermaid file, converts it to BPMN, and sets it as current context. The verb 'open' combined with specific resource 'Mermaid file' and explicit conversion step distinguish it from siblings like 'open_bpmn' which opens existing BPMN files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., 'new_from_mermaid' or 'open_bpmn'). The description does not specify prerequisites, scenarios, or when not to use it. Usage context is only implied by the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the current diagram to its file (error if no filename set)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the error condition for missing filename, which is a key behavior. However, it doesn't mention if saving overwrites without confirmation, what happens on success, or any side effects. The transparency is minimal but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no redundant information. Every word adds value, specifying the action, resource, and an important caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and a simple action, the description covers the essential context: what it does and when it errors. It could briefly mention the success outcome (e.g., 'returns nothing on success'), but the current level is sufficient for most agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema coverage is 100% (trivially). Per the rubric, 0 parameters yields a baseline of 4. The description does not need to add parameter info, and it correctly avoids extraneous details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it saves the current diagram to its file, and adds the critical condition that it errors if no filename is set. The verb 'save' matches the tool name and the resource 'current diagram' is specific. This distinguishes it from sibling tools like 'save_as' or 'new_bpmn'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a filename is already set (since it errors otherwise), but does not explicitly state when to use this over 'save_as' or other siblings. It provides no context about prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the current diagram with a new filename
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | New filename for the diagram |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose important behaviors like whether it overwrites an existing file, requires confirmation, or keeps the original file. The description is too terse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. However, it could be slightly more informative without losing brevity. It is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's nature (save as) and lack of output schema or annotations, the description should explain side effects like overwriting or confirmation. It does not, making it incomplete for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for the only parameter. The description adds no extra meaning beyond what the schema already provides (filename with description 'New filename for the diagram'). Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb 'Save', resource 'current diagram', and the unique aspect 'with a new filename'. This distinguishes it from siblings like 'save' (same filename) and 'delete_diagram_file'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs. alternatives. The description only states what it does, not when it is appropriate or when not to use it. No mention of fallback or context such as ensuring the diagram is open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update properties of an element in the current diagram
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name for the element | |
| elementId | Yes | ID of the element to update | |
| properties | No | Properties to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavior. It only says 'update properties' without clarifying whether it merges or overwrites properties, side effects, permissions, or idempotency. This is too vague for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy. Efficiently conveys the core purpose, but the brevity sacrifices necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters (one nested object), no output schema, and no annotations, the description is insufficient. It lacks details on required parameters, return value, or update semantics, which are critical for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter, so the description adds limited value. The 'properties' parameter lacks detail about its structure, and the description does not explain how 'name' relates to 'properties' or update behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update properties of an element in the current diagram' is specific with a clear verb (update) and resource (element in current diagram). It distinguishes from sibling tools like 'add_activity' (creation) and 'delete_element' (removal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'get_element' or 'delete_element'. The description implies usage for modifying an existing element but does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate the current diagram for BPMN correctness
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | Validation level | full |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the tool validates for correctness but does not mention that it does not modify the diagram, any authorization requirements, rate limits, or what the output format is (e.g., errors/warnings). This is insufficient for a mutation-free validation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 8-word sentence that clearly communicates the tool's purpose. It is front-loaded with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should explain what the tool returns (e.g., validation errors, success status) or how to interpret results. It fails to do so, leaving an agent without enough information to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (level) with a description 'Validation level' and an enum. Schema coverage is 100%, so the description does not need to add much. It adds no additional meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Validate the current diagram for BPMN correctness' uses a specific verb ('validate') and resource ('current diagram') with clear scope ('BPMN correctness'). It distinguishes itself from sibling tools, which include diagram creation, editing, and export operations, none of which perform validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool or provide alternatives, but the purpose is straightforward: validation for correctness. Usage is implied (e.g., after editing), but lack of explicit context or exclusions makes it minimally adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0add_activityadd_eventadd_gatewayadd_laneadd_poolauto_layoutcloseconnectcurrentdelete_diagram_filedelete_elementexportget_diagrams_pathget_elementlist_diagramslist_elementsnew_bpmnnew_from_mermaidopen_bpmnopen_mermaid_filesavesave_asupdate_elementvalidateEach tool has a clearly distinct purpose, targeting specific operations like adding different BPMN elements, file management, or validation. Overlap is minimal and descriptions clearly differentiate similar tools like new_bpmn and new_from_mermaid.
All tools use snake_case with a verb_noun pattern, which is consistent. The only minor deviation is 'current' as a noun instead of a verb (e.g., get_current), but overall the naming is predictable.
With 24 tools, the count is on the higher side but still reasonable for a comprehensive BPMN editor. Each tool serves a specific function, and the set covers the full workflow without being overwhelming.
The tool set covers core CRUD operations for diagram elements, lifecycle management, validation, export, and layout. Missing features like text annotations or image export are minor gaps, but the overall coverage is solid.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Give your AI agents the tools to build, manage, and run automation workflows.
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Create, read and live-edit visual boards, Kanban plans, Gantt timelines and diagrams with AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/oisee/mcp-bpmn'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
