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

Annotations provide no substantive behavior (readOnlyHint=false, destructiveHint=false, etc.). The description does not disclose side effects, return values, or whether the diagram must be open. For a tool that mutates state, this is a major 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?

The description is one short phrase, but it adds little beyond the tool name. For a tool with six parameters and nested objects, this is under-specification rather than appropriate conciseness. Important context is missing.

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 complex schema (activityType enum, properties, multiInstance, position), the description is woefully incomplete. It explains nothing about activity types, property usage, or how this fits into the diagram editing workflow. An agent gets no contextual help beyond the 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%—every parameter has a description in the input schema. The tool description adds nothing about parameters, so the baseline of 3 applies. No additional semantic value is provided 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 states a clear verb-resource pair: 'Add an activity to the current diagram'. It is specific enough to distinguish from siblings like add_event or add_gateway, though it relies partly on the tool name. It is not a tautology.

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 given on when to use this tool instead of alternatives such as add_event or add_gateway. There are no prerequisites, exclusions, or context clues beyond the bare action. An agent must infer usage solely from the name and schema.

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 provide no hints (all false), so the description carries the full burden. It states the action ('Add') but does not disclose side effects, such as whether both elements must exist, what happens if they are incompatible, or whether the association is reversible. The description mentions 'compatible' but never explains what that entails, leaving the agent to guess.

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, front-loaded sentence with no redundancy. 'Add a BPMN association artifact' immediately conveys the purpose, and the scope is appended succinctly. 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 tool's mutation nature (readOnlyHint=false) and lack of annotation support, the description is too sparse. The critical notion of 'compatible' is undefined, and there is no mention of where associations fit in the BPMN model or how they differ from other connections. An agent without deep BPMN domain knowledge would struggle to use this tool 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 baseline is 3. The description adds no additional parameter context beyond what the schema already provides ('ID of the source BaseElement', etc.). The direction parameter is documented in the schema with its default, so the description does not need to repeat it.

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 a specific verb ('Add') and resource ('BPMN association artifact') with a scope ('between two compatible BaseElements'). It distinguishes itself from other add_* tools by naming the association artifact. However, the term 'compatible' is ambiguous and does not specify what types of elements are compatible, slightly diminishing clarity.

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 given on when to use this tool versus alternatives like 'connect' (which likely handles sequence/message flows) or other add_* tools. The description does not mention exclusions, prerequisites, or when an association is appropriate. An agent must infer context from the sibling names, which is insufficient.

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 are all false (not read-only, not idempotent, not destructive) but provide no positive behavioral signals. The description adds the key fact that it creates both a visible reference and a non-rendered backing object, which is useful. However, it does not disclose side effects, whether it can overwrite, or any other behavioral traits beyond that.

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, compact sentence that front-loads the core action and the dual-artifact nature. It is appropriately sized with no wasted words, though it could add a brief usage note without becoming 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?

Given the tool has 6 parameters, a nested object, and an output schema, the description is adequate but not rich. It explains the core purpose but omits guidance on collaboration edge cases (e.g., when ownerId is needed) or any preconditions. The schema and output schema compensate partly, but the description could do more.

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 parameter-level meaning beyond the schema, but the dual-artifact framing helps understand how name/position relate. Since the schema already documents every parameter, no further compensation is needed.

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 a specific verb ('Add') and a specific resource ('BPMN data object reference and its non-rendered backing data object'), clearly identifying what the tool does. It distinguishes this from other add_* tools by focusing on data objects, though it does not explicitly name alternatives.

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 data objects but does not provide explicit when-to-use or when-not-to-use guidance relative to sibling tools like add_event, add_activity, or add_gateway. The schema hint about ownerId being required in collaborations is useful but lives in the schema, not the description.

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?

All annotations are false, providing no safety or mutation hints, so the description carries the full burden of behavioral disclosure. The description only says 'Add', implying a mutation, but does not disclose side effects, required permissions, or failure modes (e.g., invalid eventType or BPMN constraints). This is inadequate for a complex modeling 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, concise sentence with zero wasted words. It is front-loaded and efficiently states the core purpose. However, given the tool's 9 complex parameters and nested objects, the description could arguably be slightly more informative, but it remains appropriately brief for a schema that is self-documenting.

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 the presence of an output schema and detailed parameter descriptions, the tool description provides no high-level context about event types (start, end, boundary, etc.), parameter interrelations, or common usage patterns. It fails to synthesize the schema's information into a usable mental model, leaving an agent without guidance on selecting appropriate configurations.

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 detailed descriptions for each parameter (e.g., `eventType` enum, `attachTo` conditions, `cancelActivity` rules). The description adds no parameter-level information, so it relies entirely on the schema, which is the baseline when coverage is high. No extra value 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 tool adds an event to the current diagram, specifying the verb (add), resource (event), and context (current diagram). This is distinct from sibling add_* tools because 'event' is a specific BPMN element type, though the description does not explicitly contrast with `add_activity` or `add_gateway`.

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 tool versus alternatives like `add_activity`, `add_gateway`, or `add_pool`. The description simply states the action without mentioning exclusions, contexts, or alternative tools, leaving the agent to infer usage from the name and context.

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 indicate this is a mutating operation (readOnlyHint=false) with no idempotency or open-world implications. The description adds minimal behavioral context by specifying it adds to the current diagram, but does not disclose potential side effects, required context (e.g., existing diagram), or behavior when called without a current diagram. Since annotations don't carry detailed behavioral information, the description should have done more.

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, which is good. However, it is extremely short for a tool with five parameters and a nested object, leaving out any useful structural information. It is appropriately compact but borderline under-specified, so it earns a middle score.

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 complexity (5 parameters, enum gatewayType, nested position object, and no output schema explanation), the description is far too minimal. It doesn't explain the gatewayType choices, the meaning of ownerId and scopeId, or how positioning works. An agent would have to rely entirely on the schema, and even then some context (e.g., relationship to current diagram) 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 description coverage is 100%, so all parameters are documented in the schema. The description itself adds no parameter semantics; it doesn't mention gatewayType, name, ownerId, scopeId, or position. With high schema coverage, the baseline is 3, and the description provides no extra 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 action (add) and the resource (gateway) and specifies the target (current diagram). It distinguishes from sibling add_* tools by resource type, though it doesn't mention the gatewayType parameter that differentiates gateway kinds. It is specific enough to identify the tool's purpose but lacks a mention of the required type parameter.

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 instead of alternatives like add_event, add_activity, or add_pool. There is no mention of prerequisites, context, or conditions for use. The description simply states the action without any usage context or exclusions.

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 discloses a key behavioral trait beyond annotations: 'Existing assignments are moved from their previous lane.' This adds specific context about mutation and potential data relocation, complementing the destructiveHint annotation without contradicting it.

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 with no fluff. The first sentence front-loads the core action, and the second delivers a critical side-effect. Every word earns its place, making it highly efficient 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?

Beyond the schema and annotations, the description covers the essential purpose and the move-behavior. It doesn't mention prerequisites (e.g., pool existence) or error conditions, but with an output schema present and a well-covered input schema, this is adequate for correct invocation in most cases.

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 already provides full descriptions for all parameters (coverage 100%). The description does not add new meaning about params like position or flowNodeIds beyond what the schema states, so the 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 states a specific verb and resource: 'Add a lane to a white-box pool and assign flow nodes to it.' It also notes the side-effect of moving existing assignments, which distinguishes it from simple add operations like add_pool. This makes the tool's purpose unambiguous.

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 context (adding lanes to a white-box pool) but does not explicitly contrast with siblings like add_pool or add_activity. There is no 'use this when' or 'instead of' guidance, leaving the agent to infer from the resource type.

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 are all false (readOnlyHint: false, idempotentHint: false, etc.), so the description carries the full burden of behavioral disclosure. 'Add' implies a state mutation, but the description does not explain side effects, whether the current diagram must be open, or what happens to existing elements. It offers no additional behavioral context beyond the bare 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, concise sentence with no filler or redundancy. It is front-loaded with the main action and delivers exactly the necessary information. No unnecessary details or repetition, making it a model of conciseness.

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?

The tool has an output schema and full parameter documentation, so return values and parameter details are covered. However, the description does not provide usage context such as whether a diagram must be active, or how this relates to 'add_lane' (a common alternative). Given its simplicity and the availability of structural information, a 3 reflects a minimally adequate description with a notable gap in contextual guidance.

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% parameter coverage, so each parameter is documented in the schema itself. The description adds no extra meaning to parameters like 'name', 'size', 'blackBox', or 'position'. Given high schema coverage, the baseline is 3, and the description does not raise it.

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', the object 'pool', and the context 'current collaboration diagram'. It distinguishes the tool from siblings like add_association, add_event, and add_lane by naming a specific BPMN element and its scope. A 4 rather than 5 because it lacks any elaboration on what a 'pool' means in this domain, though the sibling set implies a BPMN context.

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 tool versus alternatives such as add_lane or add_participant (if any exist). The description does not mention prerequisites, constraints, or situations where one would choose this over a sibling. Completely absent, earning a 2.

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=false, indicating mutation. The description adds the behavioral fact that an association may be created, which is beyond the annotation's binary mutation flag. However, it does not disclose side effects on the existing element (e.g., whether it modifies the element) or any failure modes. Given annotations carry the core mutation trait, this is adequate but not rich.

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 with no filler. It is front-loaded with the core action and resource, and the optional clause adds value without bloat. 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?

The tool has 5 parameters (including nested objects) and an output schema. The description covers the fundamental action but omits any mention of context, such as that the annotation is added to the current diagram or any error conditions. However, given the schema fully documents parameters and the output schema exists, the description is minimally sufficient but not comprehensive.

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%, meaning all parameters have descriptive text. The tool description adds no parameter-specific details beyond highlighting the optional association, which is already captured in the associatedElementId description. Thus the description does not meaningfully augment the schema, warranting the baseline score of 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 clearly states the verb 'Add' and the specific resource 'BPMN text annotation', and notes the optional association. This distinguishes it from sibling tools like add_event or add_activity, which target different element types. The purpose is unambiguous.

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 gives no explicit guidance on when to use this tool versus alternatives. It mentions 'optionally associated' but does not explain when linking is appropriate or when to use add_association instead. There are no stated prerequisites, exclusions, or conditions for choosing this over other add-* 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?

The description discloses specific behavioral traits beyond annotations: it explains that pool/lane sizes act as lower bounds, manual coordinates are replaced, disconnected nodes stay with their owner, and message flows route after pool placement. These details align with the destructiveHint and idempotentHint annotations, adding value by clarifying exact effects. No contradiction exists.

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, information-dense sentence that front-loads the core action ('Apply deterministic automatic layout') before listing behaviors. It is concise, with no filler, though the list of clauses is a bit packed but still readable.

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 layout tool with one optional parameter and an output schema, the description thoroughly covers the essential behaviors and constraints. It explains deterministic behavior, rank ordering, size bounds, coordinate replacement, and routing logic, leaving no ambiguity about what the operation does. The output schema handles return values, so nothing critical 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?

The schema fully documents the single parameter 'algorithm' with an enum and default, achieving 100% coverage. The description adds no additional meaning about the parameter or its values. Since the schema already covers it, a 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 'Apply deterministic automatic layout' with a specific verb and resource. It goes beyond a simple statement to enumerate key behavioral rules (e.g., collaboration processes ranked independently, manual coordinates replaced), making its purpose precise and unambiguous. It is easily distinguishable from siblings, none of which perform layout operations.

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. It does not mention any conditions, prerequisites, or exclusions. While it implies use for automatic layout, it fails to explicitly state the scenario or contrast with manual layout or other 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 already declare idempotentHint=true and destructiveHint=false, so the description doesn't need to restate those. It adds the side effect of clearing the context, which is beyond the annotations, but does not clarify whether changes are saved or discarded, or if the action is reversible. Given the annotations, a 3 is appropriate; more detail would be better for a state-changing operation.

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 that front-loads the primary action and includes the secondary effect. No unnecessary words or repetition. 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?

With no parameters and an output schema present, the description covers the essential behavior. However, given the large set of sibling tools, it lacks context about when to use 'close' versus alternatives like 'save' or 'delete'. The description is functional but not rich enough for an agent to confidently choose it in all relevant 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?

The tool has zero parameters and the input schema is empty with 100% coverage. As per the baseline for 0-parameter tools, the description does not need to elaborate on parameters, and it doesn't. This is fully adequate.

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 ('Close the current diagram and clear the context'), which is specific and unambiguous. It identifies the resource (diagram) and the extra behavior (clearing context). However, it does not explicitly differentiate from sibling tools like 'save' or 'delete', though the action is distinct enough that the purpose is 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?

There is no guidance on when to use this tool versus alternatives such as 'save', 'new_bpmn', or 'delete_diagram_file'. The description only states what it does, not the context in which it should be chosen. With many sibling tools, an agent is left to infer when closing is appropriate.

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 provide no positive hints (all false), so the description carries the full burden of behavioral disclosure. It fails to mention that this modifies the diagram, whether it validates element existence or compatibility, or any side effects. The agent has no idea what the operation actually does beyond a generic 'connect'.

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 extremely concise (one sentence), but it lacks the substance needed to be useful. It doesn't front-load key constraints or provide any structure that helps an agent parse intent quickly. While brevity is good, this is under-specification rather than efficient framing.

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 7 parameters including condition, isDefault, and language options, the description is grossly incomplete. An agent has no high-level understanding of how to use these together (e.g., when to supply a condition vs setting a default flow), or what the operation returns (despite an output schema, the description doesn't set context). The tool needs far more narrative to be safely invoked.

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 parameters are documented in the schema. The description itself adds no extra meaning beyond the generic notion of connecting, which is the baseline expectation for high coverage. It does not explain relationships between parameters (e.g., condition vs isDefault) outside 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?

The description states a clear verb+resource ('Connect two elements in the current diagram') that conveys the basic action. It does not differentiate from sibling tools like add_association, which might represent a similar connection operation, so it lacks explicit distinguishing context.

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 tool versus alternatives such as add_association, or on the prerequisites (e.g., elements must exist). With many sibling tools and complex connection semantics, the complete absence of routing information leaves an agent unable to choose correctly.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds nothing beyond the name about behavior—it doesn't mention output format, scope, or any side effects. With strong annotations, a 3 is appropriate because it adds minimal context beyond structured data.

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 wasted words. The core action and target are front-loaded. Perfectly sized for a zero-parameter read 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?

The tool has an output schema that presumably defines the return structure, so that gap is covered. However, the description doesn't clarify what 'information' means in practice—whether it returns the full diagram model, just properties, or a summary. Given the broad sibling set of read-like tools (list_elements, get_element, export), a slightly more explicit scope would make it self-contained. It's minimally complete but leaves ambiguity.

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 zero parameters, so schema description coverage is trivially 100%. With no parameters to explain, the baseline is 4. The description doesn't need to elaborate on parameters; it correctly avoids redundant parameter 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 states a clear verb ('Get') and a resource ('current diagram'), but 'information' is vague—it doesn't specify whether this returns metadata, elements, or both. It's distinguishable from get_element (which targets a specific element) but not precisely from list_elements or export. The purpose is understandable but under-specified.

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 given on when to use this tool versus alternatives like list_elements, get_element, or export. It does not state what kind of 'information' it returns or when a caller should prefer this over sibling read operations. The usage context must be inferred entirely from the tool name.

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 simply says 'delete', which is consistent with the destructiveHint annotation, but adds no extra behavioral context such as irreversibility, error handling for missing files, or side effects. Given the annotations already declare destructiveHint=true and idempotentHint=true, the description contributes no new information about the tool's 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, efficient sentence that states the action and object without extraneous details. It is front-loaded with the verb, and every word earns its place. There is no redundancy or 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 simple, one-parameter delete operation, the description is mostly sufficient, and the presence of an output schema means return values need not be explained. However, it lacks usage context (when to use vs. alternatives) and practical constraints (e.g., availability of the file), which an agent would benefit from. Given the sibling tool delete_element exists, the absence of any differentiation weakens completeness.

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 parameter 'filename' is fully described in the schema ('Filename of the diagram to delete'), and schema coverage is 100%. The description adds no further meaning beyond the schema; it only reiterates that the file is a BPMN diagram, which is already implicit. This meets the baseline but does not enhance understanding.

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 'delete' and the resource 'a saved BPMN diagram file', which distinguishes it from sibling tools like delete_element that target elements rather than files. It is specific and unambiguous, though it does not elaborate on what 'saved' means in context.

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 delete_element or close. It does not mention prerequisites (e.g., the file must exist) or situations where deletion is not appropriate, leaving the agent to infer usage solely from the name and description.

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 and idempotentHint=true, so the agent knows it is a destructive, repeatable operation. The description adds value beyond these by specifying that element deletion cascades incident connections while connection deletion preserves endpoints. This is crucial context not present in annotations. No contradiction with annotations.

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, compact sentence that front-loads the primary action and packs the two modes and their effects efficiently. Every word earns its place, with no redundancy or filler. It is optimally sized for the complexity of the 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?

For a one-parameter destructive tool with annotations covering safety and an output schema present, the description is largely complete. It explains the two deletion modes and their different implications. Minor omission: it does not explicitly state what happens to the endpoints of incident connections when deleting an element (beyond implying they are cascaded), which could be clarified. Overall, adequate for an agent to call 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 describes elementId as 'ID of the element to delete' with 100% coverage, but the tool description reveals that elementId can also refer to a connection, adding meaning beyond the schema. It clarifies that the ID serves double duty. However, it does not specify how an agent can distinguish an element ID from a connection ID, which is a minor gap.

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 a specific verb ('Delete') and resource ('an element or a connection'), and concisely differentiates the two modes with their distinct effects. It is clear what the tool does overall, though it does not explain how it determines which mode applies (which is left to the parameter value).

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 implicit usage guidance by explaining that it can delete either an element (cascading incident connections) or a connection (preserving endpoints), which helps an agent choose the appropriate action. However, it does not explicitly state when to prefer this tool over alternatives (no other element-deletion tool exists among siblings) or provide conditions for exclusion. The guidance is functional but not explicit about scenarios where deletion should not be used.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the output is 'rendered by bpmn-js', which is a behavioral detail beyond the annotations. It does not contradict any annotation; it is consistent. The description doesn't need to repeat safety hints since annotations carry that, and it adds value with the rendering detail.

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 front-loaded with the action ('Export') and resource ('current diagram'), followed by the output formats and rendering detail. There is zero filler or repetition. Every word contributes to clarity.

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 that the output schema exists (as indicated by context signals), the description does not need to explain return values. The tool has two optional parameters that are fully documented in the schema, and the description covers purpose and output formats. Annotations cover safety. Nothing needed for an agent to call this tool successfully 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?

The input schema describes both parameters: 'format' with enum values and a default, and 'formatted' with a description. Schema description coverage is 100%, so the schema already documents parameters thoroughly. The description does not add any extra meaning about parameter syntax, alternatives, or nuances beyond what the schema provides. 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 specific verb 'export' and the resource 'current diagram', and specifies the two possible output formats (BPMN XML or svg+xml). This distinguishes it from sibling tools like save and save_as, which persist files, while export produces a serialized representation. No ambiguity about what the tool does.

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 gives clear context that this tool is for exporting the current diagram in a specific format, which is implicitly distinct from saving or opening. It does not explicitly mention when not to use it or name alternatives, but the purpose is self-evident given the format and the 'current diagram' scope. A slight gap is the lack of explicit routing to save_as for persistence, but the context is adequate.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no additional behavioral context, such as what the returned path looks like or any side effects, which is minimal over the annotations.

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 concise sentence with no filler. The purpose is stated directly and 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?

For a trivial getter with no parameters and an existing output schema, the description is adequate. It doesn't provide context on typical use cases, but that's not necessary given its simplicity.

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 tool has zero parameters, so the description adds no parameter meaning. According to the rubric, 0 params has a baseline of 4, which is appropriate since there is nothing to explain.

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 retrieves the path where BPMN diagrams are saved. It is specific and distinguishes from siblings like open_bpmn or list_diagrams, as it returns the location rather than contents or list.

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 gives no guidance on when to use this tool versus alternatives, such as list_diagrams or current. It only states what it does, leaving the agent to infer usage from the name.

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 destructiveHint=false, covering the safety profile. The description adds the useful context that it operates on 'specific' elements and associations within the 'current diagram', which is not in the annotations. However, it does not disclose behavior on missing IDs or error conditions; the output schema likely covers return format.

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 zero redundancy. It states the action, scope, and resource type efficiently, making it easy to parse.

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?

The description covers the essential scope ('current diagram', 'element or association') and safety is fully provided by annotations. The presence of an output schema means return values are documented elsewhere. It omits potential error behavior for nonexistent IDs, but that is a minor gap for such a simple retrieval 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?

The input schema already provides a description for elementId ('ID of the element'), and the description ('Get details of a specific element or association') implies it is the target identifier. No additional semantic detail is added beyond the schema, and with 100% schema coverage the baseline is 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 clearly states the verb 'Get' and the resource 'details of a specific element or association', and scopes it to 'the current diagram'. It distinguishes from list_elements (which lists) and update_element (which updates) by emphasizing specificity, though it does not explicitly name alternatives.

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 its siblings, such as list_elements for enumeration or update_element for modification. The word 'specific' implies single-element retrieval, but no explicit selection criteria or alternative routing is given.

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 annotations already declare read-only, idempotent, and non-destructive behavior, so the description's job is lighter. It adds valuable context about stable ordering and pagination mechanics, going beyond what annotations provide. Does not contradict annotations.

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 starts with the core purpose, then compactly provides return structure and pagination instruction. No wasted words; everything is essential and immediately useful.

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 read-only list operation, the description covers the result format, pagination logic, and ordering guarantee. The output schema (if present) is not shown, but the description explicitly lists the response fields, making it self-contained. No missing information that an agent would need to call this tool 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% for both parameters (limit, offset), but the description enhances understanding by explaining offset in the context of 'stable filename order' and pagination, which is not fully captured by the schema. This adds functional meaning beyond parameter names and defaults.

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 a clear verb ('List') and resource ('diagrams') with the specific ordering definition ('stable filename order'). It also specifies the return shape, making it unambiguous what the tool does and how it differs from other diagram operations like open, save, or export.

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?

Provides explicit pagination usage ('request the next page with offset + returnedCount') which is key to correct invocation. It doesn't explicitly mention when not to use this tool, but no direct alternative exists among siblings for listing diagrams, so the guidance is sufficient for the use case.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral traits beyond annotations: it specifies the response envelope, the stable sort order, and the pagination mechanism (offset + returnedCount). This gives the agent expectations about ordering and data volume that structured metadata alone cannot convey.

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 compact sentence that front-loads the core purpose, then specifies the response format, and closes with pagination guidance. Every clause earns its place; there is no fluff or redundancy. It respects the token budget while delivering high-value details.

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 that an output schema exists (covering return values), the annotations cover read-only/idempotent safety, and the input schema fully documents all three parameters, the description is complete for an agent to call this tool correctly. It adds the crucial non-obvious detail of stable ordering and pagination, making it self-sufficient for both initial listing and subsequent page requests.

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 every parameter (limit, offset, elementType) has a description, so the baseline is 3. The description adds contextual semantics for offset by tying it to the stable ID order and the pagination rule (offset + returnedCount), which clarifies how offset behaves beyond the schema's 'Zero-based offset' note. This elevates it above baseline.

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 and resource: 'List elements and association artifacts'. It further specifies the ordering ('stable ID order') and the exact response shape. This clearly distinguishes list_elements from sibling tools like get_element (targeted retrieval) and delete_element (mutation), so an agent can select it without needing to inspect 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?

The description does not name alternative tools or give explicit when-not-to-use guidance, but it provides actionable usage context: it explains the pagination contract ('request the next page with offset + returnedCount'), which is the core operational detail. This is clear context, though it stops short of contrasting with siblings like get_element or export.

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 discloses that it creates a diagram and sets it as the current context, which is a side effect. Annotations are minimal (all false), so the description carries the burden. However, it doesn't mention whether the diagram is persisted, what happens to the previous current diagram, or any error conditions. This is adequate but lacks depth.

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 that front-loads the primary action and key side effect. No filler or redundant content. It efficiently conveys the essence.

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 creation tool with fully documented parameters and an output schema, the description is mostly adequate but lacks usage guidance and detailed behavioral context (e.g., where the diagram is stored, effect on existing state). It covers the minimum but leaves some gaps that an agent might need.

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% for all three parameters (name, type, extensionProfile), each with clear descriptions and enums. The description adds no extra meaning beyond what the schema provides. Baseline 3 applies since the 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?

The description clearly states the action (create) and resource (BPMN diagram) and an additional effect (set as current context). It distinguishes from siblings like open_bpmn (open existing) and new_from_mermaid (create from mermaid), making the tool's purpose unambiguous.

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 gives no explicit guidance on when to use this tool versus alternatives. It doesn't mention conditions, exclusions, or when to prefer other tools like new_from_mermaid for mermaid-derived diagrams. Usage context is only implied by the tool's 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.

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds the behavioral trait of setting the new diagram as the current context, which is not in annotations. This is useful context beyond the structured data, though it does not disclose error handling or prerequisites.

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 that states the action, the input, and the side effect without any redundancy. Every word contributes to the meaning, making it highly concise and structured.

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?

The tool is a straightforward creation operation with a side effect. The description states the core purpose and the current-context behavior. An output schema exists (as indicated), so return values are presumably covered elsewhere. The description is sufficient for an agent to understand how to invoke it correctly, though it does not mention potential failure modes or prerequisites.

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 descriptions fully cover all three parameters (name, mermaidCode, extensionProfile) with 100% coverage. The tool description does not add any further meaning beyond what the schema already provides, so the baseline score of 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 a specific verb ('Create'), a resource ('a new BPMN diagram from Mermaid code'), and a distinct side effect ('set it as current context'). It differentiates from siblings like new_bpmn (likely empty diagram) and open_mermaid_file (opens existing file) by emphasizing the conversion and context-setting behavior.

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 you have Mermaid code and want to convert it to BPMN, but it does not explicitly state when to use this tool versus alternatives such as new_bpmn or open_mermaid_file. There is no 'use this when' or 'prefer this over' guidance, leaving the agent to infer context from the purpose.

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 disclose idempotency (idempotentHint: true) and non-destructiveness (destructiveHint: false). The description adds the key behavioural trait of switching the current context, which is not captured by annotations. It does not discuss failure modes, but given the annotations and the simple nature of the tool, this is sufficient.

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, front-loaded sentence states the action and effect with zero filler. Every word adds value, and the structure is optimally compact for a tool with one parameter.

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 one parameter, an output schema, and annotations that cover safety, this description is complete. It explains what the tool does (opens and sets context), and nothing else is needed for an agent to invoke it correctly. The existence of the output schema relieves the description from explaining 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 fully describes the single parameter ('filename': 'Filename of the BPMN diagram to open') with 100% coverage. The description does not add any extra meaning about the parameter (e.g., path patterns, extensions, or constraints), so it merely echoes the schema. A baseline of 3 is appropriate when the schema carries the semantic load.

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 ('Open'), a clear resource ('existing BPMN file'), and an explicit effect ('set it as current context'). This distinguishes it from siblings like new_bpmn (create), open_mermaid_file (different format), and save (persist), making the purpose unambiguous.

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 clearly implies usage: open an existing BPMN diagram to make it the working context. It does not explicitly name alternatives or conditions for when not to use it, but the resource type ('existing BPMN') implicitly rules out new files or other formats. A named alternative would be stronger, but the core context is clear.

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 mark the tool as non-read-only and non-destructive, and the description adds the key side effect of setting current context. It does not disclose potential impacts on unsaved work or file modifications, but given the annotation coverage, the provided behavioral details are adequate and non-contradictory.

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, efficient sentence that front-loads the primary action (open, convert, set context). Every word adds value with 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?

The description covers the core purpose and the side effect of setting current context, while an output schema exists and all parameters are fully described. It does not explicitly mention the extensionProfile's role, but that is a minor omission given the schema's clarity.

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?

Both parameters (filename and extensionProfile) have full descriptions in the schema, including the enum for extensionProfile. The tool description itself adds no extra parameter context, which is acceptable because schema coverage is 100%.

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 a clear verb-resource-action: open a Mermaid file, convert it to BPMN, and set it as current context. This distinguishes it from siblings like open_bpmn (which opens BPMN files) and new_from_mermaid (which creates new BPMN 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?

The context where this tool should be used is implied: when an existing Mermaid file needs to be converted and made the active diagram. However, it does not explicitly mention alternatives or conditions for selection, leaving the agent to infer from tool names and sibling descriptions.

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 and idempotentHint=true, covering the safety profile. The description adds the error condition (error if no filename set), which is useful behavioral context, but little else about side effects. It does not contradict annotations.

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 that front-loads the primary action and immediately notes the key error condition. Every word earns its place, with no filler or repetition of schema 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?

Given the tool has no parameters and an output schema exists, the description adequately covers what the tool does and a critical edge case (missing filename). It does not discuss permissions or asynchronous behavior, but these are minor for a save operation with existing annotations.

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?

This tool has zero parameters, so the description does not need to explain parameter semantics. The baseline of 4 applies because there is nothing to elaborate on; the description correctly avoids adding irrelevant 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 states the exact action (save), the resource (current diagram), and the destination (its file), which immediately distinguishes it from save_as. The error condition adds precision. This is a clear, unambiguous purpose for an agent.

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 that a filename must already be set to avoid an error, which indirectly suggests using save_as when no filename is set, but it does not explicitly name save_as or other alternatives. This leaves usage guidance implicit rather than explicit.

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=false (write operation) and destructiveHint=false. The description adds the key 'new filename' behavior but does not disclose side effects such as whether the current diagram's internal file reference changes to the new filename, or what happens if a file with the same name already exists (overwrite vs. error). The description adds minimal behavioral context beyond the annotations.

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, succinct sentence with no extraneous words. It front-loads the verb and directly conveys the essential action and differentiator. There is zero waste.

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?

The tool is simple (one parameter) and has an output schema, so return values are likely covered. However, the description omits important behavioral nuances: what happens to the current diagram's file association after save_as, and whether existing files are overwritten. Given the presence of a sibling 'save' tool, an explicit clarification of when to use save_as versus save would improve completeness.

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 'filename' parameter has a clear description: 'New filename for the diagram'). The tool description essentially repeats this information without adding further meaning. The baseline of 3 applies since the schema fully documents the parameter.

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 'Save the current diagram with a new filename' clearly states the action (save), the resource (current diagram), and the key differentiator (with a new filename) that distinguishes it from the sibling 'save' tool. An agent can immediately understand what this tool does and how it differs from the alternative.

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 context (use when you want to save under a different name) but does not explicitly state when to prefer this over 'save' or mention any exclusions. The differentiation is implicit via the phrase 'with a new filename' rather than an explicit 'use this when you want to keep the original file intact'.

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 indicate destructiveHint=true and idempotentHint=true, so the description does not need to restate that it mutates. However, the description adds no additional behavioral context, such as whether updating is partial (only provided properties change), whether null clears fields, or what happens if the element does not exist. Given the sparse description, the agent must rely on the schema for these nuances. The description is consistent with annotations but adds minimal value.

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 wasted words. It clearly communicates the action and target. This is exemplary conciseness.

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?

The tool has a complex schema with nested properties and an output schema, and the description is very brief. While the schema carries detailed parameter semantics and annotations indicate destructive behavior, the description does not explain the partial-update semantics (unchanged properties remain) or that certain fields apply only to specific element types. An agent would need to read the schema carefully. For a mutation tool with this complexity, the description could provide more context, making it adequate but not 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% – each parameter (elementId, name, defaultFlow, and the properties object) already has a detailed description in the schema, including notes on clearing fields and restrictions. The tool description itself adds no semantic information about parameters, so it does not compensate beyond what the schema provides. 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 states a clear verb ('Update') and a specific resource ('properties of an element in the current diagram'). This distinguishes it from sibling tools like get_element, delete_element, and add_* tools. The mention of 'current diagram' adds context. It is specific and unambiguous.

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 gives no explicit guidance on when to use this tool versus alternatives, such as save (which persists the whole diagram) or get_element (to read). Usage is implied by the name and description, but there is no directing of the agent to consider alternatives or exclusions. It is acceptable but not explicit.

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, idempotentHint, and destructiveHint, establishing the safety profile. The description adds valuable behavioral context by detailing what each validation level actually does—syntax parsing and reference resolution, semantic rules for events/flows/subprocesses/lanes/collaborations, and executable-profile guidance for full. This goes beyond the annotations and helps the agent understand what the validation entails, without contradicting the annotations.

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, but it is well-structured with semicolons to separate the levels, and it front-loads the primary action ('Validate the current diagram'). It avoids unnecessary words while conveying all key information. The length is appropriate for the complexity of the tool's levels, and it doesn't repeat what the schema already states.

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 required params), the description adequately covers the validation levels and what they involve. An output schema exists, so the return value is documented elsewhere. The description is complete for an agent to understand how to invoke the tool and what to expect from each level, with no missing critical details.

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 covers the 'level' parameter with enum values and a description, but the tool description provides much richer semantics by explaining exactly what each level checks. For example, 'syntax parses XML and resolves references' adds meaning beyond the schema's simple cumulative statement. Since schema coverage is 100%, a baseline of 3 is appropriate, but the elaboration justifies a 4.

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 'Validate' and the resource 'current diagram', making the tool's purpose unambiguous. It also distinguishes itself by explaining the cumulative levels, which is specific and not redundant with the name. Since sibling tools are all editing/IO operations, this is clearly the validation tool, and the description highlights its unique functionality.

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 clear context on when to use the tool (to validate the current diagram) and explains the different validation levels, implicitly guiding the agent on choosing the appropriate level. It doesn't mention alternatives because there are none among the siblings that serve a similar purpose, so the absence of explicit exclusion is acceptable. The trigger condition is well-defined.

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