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

Annotations only supply readOnlyHint=false and openWorldHint=false; the description adds substantial behavior the agent could not otherwise infer: auto-layout runs after chaining, chains stop auto-connecting past a gateway, setting an anchor turns auto-layout off unless autoLayout=true, subprocesses expand by default, and IDs are auto-generated from names. It even notes response nextSteps for compensation wiring, which is well beyond annotation coverage.

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 purpose and default chaining behavior are front-loaded, and the length is justified by the tool's complexity (7 top-level params plus a large nested element object). The single dense paragraph is somewhat heavy and could be broken into shorter units, but nearly every sentence carries distinct rules.

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 complex mutation tool with no output schema and 100% schema coverage, the description covers side effects, placement overrides, boundary-event hosting, subprocess expansion, and points to bpmn://guides/modeling-elements for conventions. It only partially describes the return value (mentioning nextSteps for one case), which is a minor gap given the absence of an output schema.

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, but the description contributes cross-parameter interaction semantics the per-field schema does not state: which anchor parameters disable auto-layout, the mutual exclusion of flowId vs afterElementId, and the pairing requirement of fromElementId + toLaneId. This meaningfully exceeds restating individual fields.

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?

States a specific verb ("Add") and resource ("elements ... to a BPMN diagram") and enumerates the concrete element categories (tasks, gateways, events). It also distinguishes itself from connect_bpmn_elements by explaining that gateway branches must be wired with that sibling, so an agent can tell the two apart without opening a schema.

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?

Gives explicit operating modes (connect "chain" vs "none"), the gateway exception with a named alternative ("wire branches with connect_bpmn_elements"), and the rule that an entry setting its own anchor/position opts out of chaining and auto-layout. It lacks broader selection guidance against siblings such as move_bpmn_element or batch_bpmn_operations, but the core when/when-not is present.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true, but the description adds crucial destructive-behavior context beyond them: the `alignment: middle` collapse of parallel branches onto a single Y row and the resulting horizontal overlaps. It also prescribes a mitigation (compact=true) and a safer alternative, which is exactly the disclosure a mutation tool needs.

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?

Front-loaded with the core purpose, then numbered operations, then the warning. The warning paragraph is long but each sentence (risk, safer alternative, mitigation) earns its place; minor redundancy in re-explaining compact.

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 6-parameter mutation tool with no output schema, the description covers the operations, preconditions, parameter interactions, failure modes, and the fallback tool. Nothing needed to invoke it correctly is missing.

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, but the description adds operational meaning: it ties `compact` to the align operation, ties `gap` to distribute and recommends ~50px, and maps the enum values to the align/distribute operations. It goes beyond restating 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?

States a specific verb ('Align or distribute') and resource ('selected elements'), then enumerates the two operations with their axes. It is clearly distinguishable from siblings like move_bpmn_element or layout_bpmn_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?

Explicitly states the preconditions for each mode (align needs ≥2 elements, distribute needs ≥3) and names the alternative ('Use layout_bpmn_diagram instead to re-arrange the full diagram while preserving branch separation') with the condition that selects it.

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

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

The description declares 'Read-only', consistent with readOnlyHint=true, and goes beyond the annotations by disclosing what each mode returns (lane names, coherence score, reasoning; issues with fix suggestions; recommendation with confidence). It does not discuss auth, rate limits, or failure modes, but the safety profile is fully covered.

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 purpose is front-loaded, then the three modes are enumerated compactly with their return shapes, ending with the sibling routing. It is longer than most descriptions but nearly every clause carries distinct information; only the repeated mode naming is slightly redundant.

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 compensates by describing the return payload for each mode. Three parameters, full schema coverage, and read-only annotations are all accounted for, leaving nothing an agent needs in order 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?

Schema coverage is 100%, so the enum values and diagramId/participantId are already documented, giving a baseline of 3. The description adds meaning the schema lacks: that 'suggest' keys off roles (camunda:assignee/candidateGroups) or human-vs-automated element types, and that participantId scopes 'suggest' and 'validate'.

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?

States a specific verb and resource ('Analyze lane organization in a BPMN diagram') and enumerates the three distinct modes with what each produces. It explicitly separates itself from the sibling create_bpmn_lanes, so an agent can route correctly without opening a schema.

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?

Each mode carries an explicit condition for use ('suggest' for assignment proposals, 'validate' for checking current organization, 'pool-vs-lanes' for the pool/lane decision). It also names the alternative for mutation ('to assign or redistribute elements use create_bpmn_lanes'), giving both when-to-use and when-not-to-use.

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

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

Goes well beyond the sparse annotations (readOnlyHint=false, openWorldHint=false) by disclosing sequential execution order, the stop-on-first-error default, the opt-out flag, and the transactional rollback mechanism via the bpmn-js command stack — exactly the failure semantics an agent needs before batching writes.

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?

Four short sentences, zero filler, with the core purpose front-loaded and the execution/rollback semantics following in priority order. Every sentence carries distinct 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?

Covers invocation and failure semantics well for a mutation tool with no output schema, but is silent on the response shape — e.g. whether per-operation results/errors are returned and what a partial run looks like when stopOnError is false.

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, but the description adds real meaning the schema does not: stopOnError's default value and, critically, that rollback behavior is tied to it, which changes how an agent should set the flag.

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?

States a specific verb and resource ('Execute multiple BPMN operations in a single call') plus the benefit (reducing round-trips), which cleanly distinguishes this meta-tool from the individual operation siblings like add_bpmn_elements or connect_bpmn_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?

Gives a clear context for use (batching multiple operations to cut round-trips) and an explicit constraint ('Nested batch calls are not allowed'), but never states when to prefer individual calls over batching or any prerequisites/call-order limits.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries the rest and does so well: it names the underlying command-stack mechanism, notes multi-step support, and warns that a specific class of operations (boundary-event repositioning and the normaliseOrigin fallback) is not undoable. It does not say what happens when the stack is empty or exhausted.

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?

Three tight sentences: purpose first, mechanism second, exception third. Every sentence earns its place and nothing is repeated from the schema.

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 3-parameter mutation tool with no output schema, the description covers action semantics, step handling, and the important incompatibility with layout operations. It leaves some gaps around empty/failed history behavior and whether it targets the currently loaded diagram, but nothing essential to invocation is missing.

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 each parameter already has a description, so the schema does the heavy lifting. The description's mention of multi-step undo/redo mirrors the 'steps' parameter without adding format or boundary detail (e.g., max steps, behavior past the stack depth).

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?

States a specific verb pair (undo/redo) and resource (BPMN diagram changes) and explains the mechanism (bpmn-js command stack). No sibling among the ~20 list does history reversal, so the agent can distinguish it immediately.

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?

Makes clear this is the tool for reversing or re-applying prior edits, and adds a valuable boundary condition: changes made by layout_bpmn_diagram are outside the command stack and cannot be undone. It stops short of stating explicit when-not conditions (e.g., what to do if there is no history).

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description must carry the behavioral load, and it does: it discloses automatic connection-type detection (SequenceFlow/MessageFlow/Association/DataAssociation), support for condition expressions and isDefault on gateway flows, and the existence of a waypoint-update path. It does not mention undo/permission semantics for the create path, leaving a small gap.

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?

Front-loaded with the verb and the mode enumeration, and each subsequent sentence (auto-detection, condition/isDefault, alternative tool, waypoint mode) carries distinct information. It is dense but nearly every clause earns its place; only slight redundancy between the mode list here and the oneOf descriptions costs it a point.

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 12-parameter mutation tool with no output schema, the description covers modes, auto-detection behavior, gateway-flow options, and the alternative tool for edits. The one notable gap is that waypoint mode requires a connectionId from a prior call, and the description does not state how an agent obtains that ID from the create 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by mapping parameter groups to named modes and giving a concrete example (a gateway's branches with per-branch conditions) that clarifies the connections array's purpose. It stops short of documenting the individual field names beyond what the schema already states.

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?

States a specific verb+resource ('Connect BPMN elements') and immediately enumerates the four operating modes (pair, chain, batch, waypoint), which lets an agent distinguish the shape of call it needs. It also names the sibling it is not ('To modify an existing connection... use set_bpmn_element_properties'), so it is separable from set_bpmn_element_properties without opening either schema.

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?

Explicitly routes post-creation edits of label/condition to set_bpmn_element_properties with the connection ID, which is a genuine when-to-use-this-vs-alternative statement. It also explains which mode to pick via the source/target shape (pair vs chain vs batch vs waypoint), though it gives no explicit exclusions for the tool as a whole.

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

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

Annotations already declare the write/open-world nature, but the description adds substantial context beyond them: it returns a diagram ID for reuse, warns that forcing autoLayout:true may reposition elements and disturb boundary event placement, notes that xml/filePath imports start with an empty undo/redo history, and explains lint-feedback suppression semantics. This is exactly the kind of side-effect disclosure a mutation tool needs.

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?

Front-loads the three creation modes before the return value and caveats, so the primary decision is answered first. It is a dense single block of prose, though; the autoLayout warning and workflow tips could be more scannable, keeping it just shy of a 5.

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 9-parameter, zero-required creation tool with no output schema, the description covers the return value (diagram ID), the mode selection logic, and the major side-effect caveat. It is nearly complete, though it does not explain default naming or what a blank diagram contains.

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 and the schema carries most parameter documentation. The description still adds meaning on top: it clarifies the mutual exclusivity of cloneFrom vs xml/filePath, the auto-detection rule for autoLayout when omitted, and that hintLevel overrides draftMode. Marginal but real added value over 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?

States a specific verb (create) and resource (BPMN diagram) and immediately enumerates the three distinct modes: blank, cloned via cloneFrom, or imported from xml/filePath. An agent can tell this apart from add_bpmn_elements, create_bpmn_participant, and the other create-adjacent siblings without opening any schema.

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?

Explicitly routes between modes: cloneFrom is ignored-alternative to xml/filePath, autoLayout is only meaningful with xml/filePath, and draftMode vs hintLevel precedence is stated. It also names the concrete workflow (combine with export_bpmn filePath for open→edit→save) and the condition for each path, leaving little to inference.

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

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.

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.

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.

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.

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.

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.

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 real behavioral load: the Camunda 7 constraint that only one pool is executable and additional pools must be collapsed is genuine domain semantics an agent could not infer elsewhere. It stops short of stating permissions or what the call returns, keeping it out of 5 territory.

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?

Five short sentences, each tied to a distinct mode or constraint, with the primary use case front-loaded. No filler and no repetition of coordinate/default details that the schema already owns.

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 13-parameter, no-output-schema mutation tool, the description covers the mode-selection logic, the wrap-existing workflow, and the Camunda 7 constraint, which is most of what an agent needs. It omits any note on post-creation return or how the new pool interacts with existing collaboration state, a minor gap.

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 the schema already documents each parameter, including that participants ignores single-pool params and that wrapExisting requires name. The description's mode framing (name vs wrapExisting vs participants) is a useful synthesis but largely restates structured data, so the 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?

States a specific verb+resource ('Create participant(s) (pools) in a BPMN diagram') and immediately disambiguates against the sibling lane tool by prescribing lanes for intra-organization role separation. An agent can distinguish this from create_bpmn_lanes and add_bpmn_elements without opening a schema.

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?

Enumerates the three concrete invocation modes (single pool via name, wrapExisting=true, multi-pool via participants with min 2) and gives an explicit when-not: use lanes inside one pool rather than multiple expanded pools. Alternatives and conditions are spelled out rather than implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds one genuinely useful piece of context not in the annotations — that the store is in-memory — but says nothing about cascading effects on contained elements or irreversibility.

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?

One short, front-loaded sentence with no filler. Every word carries information and the verb leads.

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 one-parameter tool with full schema coverage and rich annotations, the description is minimally sufficient. It omits the one thing an agent would want to know about a destructive diagram-level delete — whether child elements are removed with it.

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 a single parameter whose description ('The ID of the diagram to delete') is already complete. The prose adds no format, source, or lookup detail beyond the schema, 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?

States a specific verb (remove) and resource (diagram) plus a scope qualifier (in-memory store), which separates it from the element-level sibling delete_bpmn_element. It does not explicitly name any sibling, but the resource noun makes the distinction inferable.

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?

There is no guidance on when to use this versus delete_bpmn_element or when to prefer re-creating versus deleting a diagram. No prerequisites, no exclusions, no mention of what happens to the diagram's elements.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the mode-selection rule but omits notable behavior such as whether deleting a node also removes its attached connections or how unknown IDs are handled. With annotations carrying the risk signal, a 3 is appropriate.

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?

Two tight sentences with the core action front-loaded and the mode distinction immediately after. No filler or 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?

There is no output schema, and the annotations cover the mutation risk, so the essentials are present. Still missing for a destructive tool: cascade behavior on connected elements, handling of nonexistent IDs, and whether the operation is atomic across a bulk array.

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 all three parameters including the elementId/elementIds precedence rule are already documented in the schema. The description merely restates that precedence rather than adding format, validation, or failure semantics, so the 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?

States a specific verb (remove) and resource (elements or connections in a BPMN diagram), which cleanly separates it from delete_bpmn_diagram by scope. It never explicitly names the sibling it differs from, so an agent must infer the distinction from the resource noun alone.

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 explains the two invocation modes (single via elementId, bulk via elementIds) and that bulk takes precedence, which is genuine usage guidance. It gives no when-to-use-vs-alternatives context, e.g. no mention of delete_bpmn_diagram for whole-diagram removal or how this interacts with move/layout tools.

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

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

Annotations only declare readOnlyHint/openWorldHint; the description carries substantial extra burden: lint gating and its bypass, the sentence-level note that PNG/animated/HTML always write to filePath, optional-dependency failures that name the missing package, and the size-threshold behavior where large xml/svg returns a bpmn:// resource_link plus summary while binary formats return only a confirmation. That is unusually rich 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?

A single dense paragraph, front-loaded with the core action and format list before secondary concerns. Every sentence carries information, though the wall-of-text format with many embedded parentheticals makes it less scannable than it could be for 12 parameters.

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 12-parameter tool with no output schema, the description explicitly covers return behavior (inline text, resource_link for oversized output, confirmation-only for binary), dependency failure modes, and lint interaction. Nothing an agent needs to invoke it correctly is missing.

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 descriptions already document fps, scale, inline, encoder, filePath, scenario, skipLint, etc. in detail, so the baseline is 3. The description reinforces and slightly extends this (e.g., 'both' writes the XML portion, elementId skips lint gating), but adds little the schema does not already state.

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 opens with a precise verb+resource ("Export a BPMN diagram") and enumerates every supported output format, immediately distinguishing it from the create/add/delete/list siblings. An agent can tell exactly what this tool produces without opening the schema.

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?

It gives clear in-tool decision guidance: default behavior runs bpmnlint and blocks on errors, skipLint=true bypasses, elementId is scoped to xml/svg/both, format 'both' bundles XML+SVG, and inline=true forces full text. It does not name any sibling alternative, but no competing export tool exists, so the when-to-use context is effectively complete.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantive context beyond that: what each mode returns (IDs/names/element counts, summary fields, diff additions/removals/changes). It doesn't cover pagination or limits for the list-all mode, but for a read-only inspection tool this is strong.

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?

Three sentences, one per mode, front-loaded with the no-arg behavior and progressively adding the optional parameters. No filler or redundancy; every clause conveys a distinct behavior.

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?

An output schema exists, so return-value documentation is not required, and the description still sketches each mode's payload. All three call patterns are covered, leaving nothing an agent needs 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?

Schema description coverage is 100%, so baseline is 3, but the description adds directional semantics the schema lacks: diagramId is the base and compareWith is the changed side of the diff, plus the mutual-dependency rule (compareWith only applies alongside diagramId). That is meaningful value beyond the schema text.

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?

States a specific verb (List) plus a resource (BPMN diagrams) and enumerates three distinct modes keyed to parameters. An agent can distinguish this overview/list tool from list_bpmn_elements and list_bpmn_process_variables without opening any schema.

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?

Explicitly maps each parameter combination to the mode it triggers (no args = list all, diagramId = summary, diagramId+compareWith = diff), giving clear when-to-use guidance. It stops short of naming sibling alternatives or stating when not to use this tool, so it is short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes well beyond by disclosing the large-diagram summarization behavior, the returned bpmn:// resource_link, the inline override, and the detail-expansion semantics of elementIds. These are non-obvious behaviors an agent must know before calling.

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?

Front-loaded with the primary behavior, then filters, then the large-diagram caveat, then the elementIds alternative. Dense and mostly waste-free, though the final sentence about elementIds packs several clauses that could be split for readability.

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 an output schema present, return-value detail is not required, and the description still covers the important non-obvious return behavior (summary vs full list plus resource_link). For a 6-param tool with nested objects, this is complete.

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, but the description adds real meaning: inline forces the full list on large unfiltered diagrams, and elementIds switches to a full-detail inspection mode that ignores the other filters. It slightly under-explains how the filters combine, but the added semantics are genuine.

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?

States a specific verb (List) and resource (BPMN diagram elements) plus what is returned: types, names, positions, connections, properties. It is clearly distinguishable from siblings like add_bpmn_elements, delete_bpmn_element, and set_bpmn_element_properties.

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?

Explicitly covers when to filter (by name pattern, type, property value), what happens without filters (all elements vs type-count summary for large diagrams), how to override that (inline: true), and when to use the elementIds mode instead, noting it ignores other filters. Alternatives and conditions are fully spelled out.

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

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

Beyond the readOnly/openWorld annotations, the description discloses a non-obvious behavioral trait: large diagrams return only variable names plus a bpmn://diagram/{id}/variables resource_link, and inline: true forces the full list. It also states the per-variable return shape (read/write access pattern plus referencing elements). This is exactly the kind of conditional behavior an agent cannot infer from annotations or schema.

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?

Three sentences, purpose front-loaded, and the long enumeration of extraction sources is genuinely load-bearing for predicting results. The final sentence is dense but carries the truncation rule and the escape hatch, so it earns its length; only minor trimming is possible.

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?

An output schema exists, yet the description still explains the conditional return behavior and how to defeat the summarization, which is what an agent actually needs to decide on inline. Nothing required to invoke or interpret this tool correctly is missing.

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, but the description adds real meaning by explaining the summarization path that inline overrides and by tying it to the resource_link fallback, which the schema text alone does not connect. diagramId still gets no added semantics beyond its schema entry.

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?

States a specific verb and resource ('List all process variables referenced in a BPMN diagram') and then enumerates the exact source constructs it scans (form fields, I/O mappings, condition expressions, script results, loop characteristics, call activity mappings, Camunda properties). This is clearly distinguishable from the sibling list_bpmn_elements, which enumerates structural elements rather than variables.

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 when the tool is useful (analyzing variable usage across a diagram) but never states when to prefer it over siblings such as list_bpmn_elements or bpmn_history, nor any exclusions or prerequisites. Usage is left to inference from the purpose statement.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, and openWorldHint=false, so the mutating-but-idempotent safety profile is already covered. The description adds genuine context beyond that: these are shared, cross-referenced definitions, implying a change can affect multiple event definitions. It does not, however, state update semantics (replace vs. merge) or what happens to omitted definitions.

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?

Two sentences, front-loaded with the action and resource, followed by the reference context. No filler; every clause 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 mutation tool with no output schema and full schema coverage, the description supplies the needed purpose and reference semantics. It stops short of explaining update behavior for existing definitions or whether omitted arrays are left untouched, which would make it fully complete.

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 schema already documents diagramId, messages, and signals with their id/name sub-fields. The description references messageRef/signalRef but adds no syntax or format detail beyond the schema, so the 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?

States a specific verb pair (create or update) and precise resource (shared root-level bpmn:Message and bpmn:Signal definitions). This clearly distinguishes it from element-level siblings like add_bpmn_elements and even names set_bpmn_element_properties as the consumer of these definitions.

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 makes the use case clear: define shared message/signal objects that multiple event definitions reference. It names the sibling mechanism (messageRef/signalRef via set_bpmn_element_properties) that consumes them, giving strong routing context. It lacks an explicit when-not-to-use exclusion, so it falls short of a 5.

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

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

Annotations already declare the mutation (readOnlyHint=false), idempotency, and closed-world scope. The description adds real behavioral context beyond that: resize preserves top-left, laneId auto-centers and ignores x/y, and batch moves are validated up front and collapse into one undo step.

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?

Two sentences, front-loaded with the core action, then the constraint, then the batch alternative. Every clause carries information; no filler.

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 mutating tool with annotations covering safety and idempotency and no output schema, the description covers operations, constraints, and batch behavior well. It could note failure modes (e.g., invalid laneId/elementId) but is largely complete.

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, but the description adds the combination semantics (any mix of coordinates/size/lane, at least one required) that the schema does not express, plus the top-left/auto-center behavior. It earns above baseline without duplicating schema text.

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?

States specific verbs (move, resize, reassign) plus the resource (BPMN element to a lane), and the sibling set (align_bpmn_elements, layout_bpmn_diagram) is clearly not this operation. An agent can distinguish it without opening the schema.

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?

Explains the constraint that any combination is allowed but at least one of x/y, width/height, or laneId is required, and explicitly routes to the batch `moves` form for several elements. It does not name competing siblings (align/layout), so it falls just short of a 5.

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

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.

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.

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.

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.

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.

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.

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

Annotations declare readOnlyHint=true, so safety profile is covered. The description adds significant behavioral detail: returns structured issues with rule names, severities, element IDs, documentation URLs, and fix suggestions as concrete MCP tool calls. This goes well beyond annotations, though it doesn't mention performance or determinism.

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?

Three sentences, front-loaded with the core action and engine, followed by return value details and configuration options. No filler, every sentence 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 the presence of an output schema, the description doesn't need to detail return values but still summarizes them helpfully. It covers default configuration, custom overrides, and validation severity behavior. An agent has everything needed to call and interpret the 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% – all parameters (diagramId, config, lintMinSeverity) are fully described in the schema. The description mentions 'config overrides' and 'bpmnlint:recommended by default', which slightly reinforces the schema but adds no new syntax or format details. Baseline 3 is appropriate when schema does the heavy lifting.

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?

States a specific verb+resource ('Validate a BPMN diagram') and the engine used ('bpmnlint rules'). No sibling tool performs validation, so the purpose is unambiguous from the name and description.

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?

Clear context: validating a BPMN diagram against bpmnlint rules. It mentions default config ('bpmnlint:recommended by default with tuning for AI-generated diagrams') and custom overrides, implying when to use defaults vs. custom. No explicit when-not-to-use or alternative, but the validation function is singular in the toolset.

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