Server Quality Checklist

Tool Scores

• show_ai_cursorB
  3.1/5.0
  Behavior2/5

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

  With no annotations provided, the description bears the full burden of behavioral disclosure. It does reveal one important requirement—the companion VS Code extension must be connected—which adds some context about the execution environment. However, it does not explain what happens if the extension is not connected, whether the cursor persists, updates, or requires explicit removal, or any side effects of calling this tool.

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

  Conciseness5/5

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

  The description is exceptionally concise, consisting of a single purpose statement and one critical requirement. Every word earns its place, with no redundancy or filler. It is front-loaded with the core functionality, making it easy to scan.

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

  Completeness3/5

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

  The description is adequate for a relatively simple visual-indicator tool, but misses some contextual information that would be helpful given the sibling tools. It does not mention how this cursor interacts with the diagram or whether it's transient. The schema covers parameters well, so the description's brevity is not a critical flaw, but it could benefit from a note on behavior when the extension is unavailable or when the cursor should be cleared.

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

  Parameters3/5

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

  The input schema provides 100% coverage for all five parameters, each with a clear description. The tool description does not add extra meaning beyond the schema, but because the schema is fully descriptive, a baseline score of 3 is appropriate. The description's mention of 'specific position' aligns with the required x and y parameters but adds no additional semantic over what the schema already provides.

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

  Purpose4/5

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

  The description clearly states the tool's function: showing an AI cursor indicator at a specific position in a draw.io diagram. It uses a specific verb and resource, making the core purpose unambiguous. However, it does not explicitly distinguish this tool from siblings like show_ai_selection (which likely highlights a selection) or highlight_element, leaving some room for confusion in tool selection.

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

  Usage Guidelines2/5

  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. The only contextual hint is the requirement for a companion VS Code extension, but this is a prerequisite rather than a usage guideline. There are no stated exclusions, alternatives, or scenarios that would help an agent decide between this tool and its siblings.

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

• add_pageB
  3.2/5.0
  Behavior1/5

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

  No annotations are provided, so the description carries the full responsibility for behavioral disclosure. It only states the action without mentioning side effects such as file modification, prerequisites like the file existing, or behavior on duplicate page names, leaving significant ambiguity.

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

  Conciseness5/5

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

  The description is a single, direct sentence with no filler, front-loaded with the verb 'Add'. It is as concise as possible while communicating the core purpose.

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

  Completeness2/5

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

  For a tool with no output schema and no annotations, the description omits return behavior, error conditions, and side effects. This makes it under-specified for an agent to fully understand the tool's impact, though the simple purpose is clear.

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

  Parameters3/5

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

  The input schema already documents both filePath and pageName with 100% coverage, so the description adds no additional parameter semantics. It doesn't clarify path formats or naming constraints, but the schema provides basic definitions, placing this at the baseline.

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

  Purpose5/5

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

  The description 'Add a new page (tab) to a draw.io diagram' uses a specific verb and resource, clearly distinguishing it from sibling tools like add_node and add_edge. The mention of 'page (tab)' clarifies the target object and differentiates this from tools that operate within a page.

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

  Usage Guidelines3/5

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

  The description implies the tool is for adding a new tab to an existing diagram, but it does not explicitly state when to use it over alternatives like create_diagram. No exclusions or conditions are provided, leaving the agent to infer context from the tool name and schema.

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

• show_ai_selectionA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of disclosing behavior. It states that a colored overlay is shown and that a companion extension is required, which adds useful context beyond the tool name. However, it does not elaborate on side effects, persistence, or the nature of the overlay beyond the basic effect.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the primary action, and contains no filler. Every sentence contributes useful information about purpose or requirements.

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

  Completeness4/5

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

  For a simple visual tool with a well-covered schema and no output schema, the description includes purpose, behavior, and a prerequisite. It could be enhanced by mentioning alternatives, but overall it is complete enough for an agent to invoke correctly.

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

  Parameters3/5

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

  Schema coverage is 100% and each parameter has a clear description (cellIds, color, filePath). The tool description does not add additional meaning to these parameters, so the baseline score of 3 is appropriate.

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

  Purpose4/5

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

  The description clearly states the tool highlights specific cells in a draw.io diagram as being selected/edited by AI, which is a specific verb+resource+scope. It distinguishes itself from generic highlighting by tying it to AI selection, though it does not explicitly name sibling alternatives like 'highlight_element'.

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

  Usage Guidelines3/5

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

  The description notes a prerequisite (requires companion VS Code extension) but does not explicitly state when to use it versus alternatives. The purpose implies usage for showing AI selection, but there is no direct guidance or exclusion criteria.

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

• add_edgeA
  3.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description must disclose behavioral effects. It only says 'Add a connection' and discusses layout tips, but omits critical details such as file modification, error handling, or validation of node IDs. The layout tips are about visual configuration, not about the tool's operational behavior.

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

  Conciseness4/5

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

  The description is appropriately sized: a clear one-sentence purpose followed by a structured 'LAYOUT TIPS' section. Each tip is actionable and specific, though the section is somewhat lengthy. The overall structure is logical and front-loaded.

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

  Completeness4/5

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

  Given 10 parameters and no output schema, the description covers the core purpose and offers substantial guidance on edge styles, connection points, and bidirectional flows. It doesn't address error conditions or file-level behavior, but for a tool that primarily adds an edge with visual parameters, it is fairly complete.

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

  Parameters4/5

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

  Schema covers all params, so baseline is 3. The description goes beyond the schema by providing concrete guidance on edgeStyle (e.g., 'curved' for multiple edges, 'orthogonal' for architecture diagrams) and exitPoint/entryPoint (e.g., offset variants to prevent overlap). This adds significant practical meaning to the schemas descriptions.

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

  Purpose5/5

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

  The description states a specific action and resource: 'Add a connection (edge/arrow) between two nodes in a draw.io diagram.' This clearly distinguishes it from sibling tools like add_node (which creates nodes) and other operations.

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

  Usage Guidelines3/5

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

  The description provides extensive layout tips (curved vs orthogonal, exitPoint/entryPoint offsets) but these are guidance for parameter choices, not for when to use this tool versus alternatives like batch_add_elements or check_connection. There is no explicit when/when-not guidance, so it only implies appropriate usage.

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

• create_diagramA
  3.7/5.0
  Behavior2/5

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

  The description discloses that the file becomes immediately visible, which is a useful behavioral detail. But it omits critical behaviors such as what happens if the file already exists (overwrite vs. error) and whether the operation is undoable. With no annotations, this ambiguity creates a safety gap for an agent.

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

  Conciseness5/5

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

  The description is concise and front-loaded, using two sentences to state the action and a key behavioral outcome. Every word earns its place, with no redundancy.

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

  Completeness3/5

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

  For a simple create operation with two well-documented parameters, the description covers the core purpose and a key side-effect. However, it lacks information about error handling and existing-file behavior, making it slightly incomplete, especially without annotations to fill the gaps.

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

  Parameters3/5

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

  Both parameters (filePath and pageName) are fully described in the input schema with clear documentation, so schema coverage is 100%. The tool description itself adds no additional parameter meaning, which is acceptable given the baseline of 3 for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the action ('Create') and the resource ('new empty draw.io diagram file'), which distinguishes it from sibling tools like add_node or add_page. The additional note about immediate visibility in VS Code reinforces its unique role.

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

  Usage Guidelines4/5

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

  The description implies usage context: use this when you need to create a new diagram file for the VS Code extension. However, it does not explicitly mention exclusions or alternative tools, so it's clear but not exhaustive.

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

• get_change_historyA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool returns (operation type, description, timestamp, affected elements) but does not explicitly confirm read-only nature, permissions, or limitations. The verb 'Get' suggests a safe operation, but that is not clearly stated.

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

  Conciseness5/5

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

  The description is two short sentences, front-loaded with the main purpose and no unrelated details. Every word contributes to understanding what the tool does.

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

  Completeness4/5

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

  The tool is simple with one optional parameter and no output schema. The description explains the returned fields and the basic functionality, which is sufficient for a history retrieval tool. It does not mention ordering or diagram scope, but these are not critical gaps.

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

  Parameters3/5

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

  Schema coverage is 100% for the single parameter 'limit', and the schema already documents its default value. The description adds no additional parameter semantics, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb 'Get' and resource 'history of recent MCP operations', clearly identifying the tool's function. It distinguishes itself from sibling tools like undo_last_operation and redo_last_operation by focusing on viewing history rather than performing actions.

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

  Usage Guidelines3/5

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

  No explicit guidance is given on when to use this tool versus alternatives. The description implies it is for reviewing past operations, which could be useful before undoing or redoing, but it does not explicitly mention any relationship to sibling tools or exclusions.

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

• add_nodeA
  3.9/5.0
  Behavior2/5

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

  No annotations are present, so the description must disclose behavioral traits. It mentions the shape/style usage, but does not explain side effects such as whether the file is modified in place, how duplicates are handled, or reversibility. As a mutation tool, this lack of disclosure is a significant gap.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose and a parameter tip. There is no filler or redundant information; every sentence earns its place.

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

  Completeness3/5

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

  With 10 parameters and no output schema, the description is adequate but not comprehensive. The schema covers all parameters, and the description gives the essential purpose and shape/style hint, but it doesn't provide context about defaults, return values, or behavioral side effects, making it a minimally viable description.

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

  Parameters4/5

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

  Schema description coverage is 100%, giving a baseline of 3. The description adds value by clarifying the relationship between the shape and style parameters (predefined shapes vs. custom style string), which goes slightly beyond the schema's individual descriptions.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Add a new node (shape/vertex) to a draw.io diagram.' It uses a specific verb and resource, and distinguishes the tool from siblings like add_edge and add_page by focusing on adding nodes (shapes/vertices).

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

  Usage Guidelines4/5

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

  The description provides clear context: this tool is for adding a single node to a diagram. It does not explicitly mention alternatives like batch_add_elements for adding multiple nodes, but the purpose is unambiguous, so it meets the 'clear context, no exclusions' bar.

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

• highlight_elementA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and partially succeeds: it discloses the dual-mode behavior (overlay vs. style modification) and emphasizes temporariness. However, it does not explicitly state whether the file is modified on disk or that the highlight reverts automatically, leaving some ambiguity.

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

  Conciseness5/5

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

  The description is two sentences, with the first sentence front-loading the purpose and the second explaining the conditional behavior. Every word earns its place; no redundancy.

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

  Completeness4/5

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

  For a tool with 4 parameters, no output schema, and no annotations, the description provides adequate context including the key distinction of behavior based on companion extension presence. It lacks explicit persistence/error details but overall is complete enough for straightforward use.

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

  Parameters3/5

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

  Schema description coverage is 100%, with each parameter having a clear description. The tool description adds no parameter-specific details beyond the schema, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses specific verb 'highlight' with resource 'elements in the draw.io diagram' and 'flash effect', clearly distinguishing it from siblings like update_element or show_ai_selection which serve other purposes. It immediately conveys the tool's primary function without ambiguity.

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

  Usage Guidelines3/5

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

  The description implies usage for temporary highlighting but does not explicitly contrast with alternatives such as update_element for permanent style changes or show_ai_selection for UI feedback. It lacks explicit when-to-use/when-not-to-use guidance.

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

• read_diagramA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden. It clearly states the tool reads and parses the file and returns a structured overview, making the read-only nature and primary output behavior evident. It does not detail error handling or edge cases, but for a simple read operation, the transparency is good.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that begins with the action verb and immediately specifies the resource and return contents. Every word contributes meaning, with no filler or redundancy.

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

  Completeness4/5

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

  The description provides a clear high-level summary of the return value ('overview of all pages, nodes, and edges') despite lacking an output schema. For a read-only tool with one well-defined parameter, this is sufficient for an agent to select and invoke it correctly, though more granular return-field details could be added.

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

  Parameters3/5

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

  The sole parameter filePath is fully described in the schema ('Path to the .drawio file'), and schema description coverage is 100%. The tool description reinforces this by mentioning the .drawio file format. Since the schema handles the parameter semantics, the description adds no extra parameter detail, warranting the baseline score.

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

  Purpose5/5

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

  The description is specific and action-oriented: 'Read and parse a draw.io diagram file' clearly identifies verb and resource, and 'returning a structured overview of all pages, nodes (shapes), and edges (connections)' defines the scope. This distinguishes it from sibling tools like create_diagram, add_node, or screenshot_diagram, which serve different purposes.

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

  Usage Guidelines3/5

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

  The description implies use when a structured overview of a diagram's content is needed, but it offers no explicit 'when to use vs. alternatives' guidance. It does not mention exclusions, such as preferring screenshot_diagram for visual output or check_layout for layout analysis, so the usage context is only implied.

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

• remove_elementA
  4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses a key side-effect – removing connected edges – which goes beyond the basic 'remove' action, but does not mention persistence, error behavior, 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.

  Conciseness5/5

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

  Two concise sentences, front-loaded with the primary action and immediately followed by a relevant side-effect, with no redundant wording.

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

  Completeness4/5

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

  For a two-parameter tool with no output schema, the description covers the main action and the only notable cascading effect. It omits details like error handling or whether changes are saved, but the simplicity keeps this from being a major gap.

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

  Parameters3/5

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

  The input schema already provides 100% parameter descriptions, and the tool description adds no additional parameter-specific semantics, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description clearly identifies the action (remove), the resource (node or edge from a draw.io diagram), and the selection method (by ID). This distinguishes it from sibling tools like add_node or update_element.

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

  Usage Guidelines3/5

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

  The description implies usage when an element needs to be removed by ID, but provides no explicit guidance on when to choose this tool over alternatives or any exclusions. It does not mention prerequisites like file existence or how to obtain an element ID.

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

• show_statusA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It discloses the prerequisite 'Requires the companion extension,' which is valuable, but it does not describe other behavioral traits such as whether the message replaces the previous status, how it behaves if the extension is missing, or whether it is transient.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the action, and includes practical context and a prerequisite without any fluff. Every sentence earns its place.

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

  Completeness4/5

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

  For a simple one-parameter tool with no output schema, the description covers purpose, use case, and a requirement. It is nearly complete, though it could briefly mention whether the status message is persistent or overwrites previous messages.

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

  Parameters3/5

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

  The input schema describes the only parameter (message) with a clear example, and schema coverage is 100%. The description does not add extra parameter meaning beyond restating 'status message,' so the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb ('Display') and resource ('status message in the draw.io editor status bar'), making the tool's purpose immediately clear. It also implies a distinct role from sibling tools like show_spinner or show_ai_cursor, which target different UI feedback mechanisms.

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

  Usage Guidelines4/5

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

  It states the tool is 'useful for showing what the AI is currently doing,' which gives clear context for when to use it. However, it does not explicitly mention alternatives or cases where this tool should not be used, so it stops 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.

• show_spinnerA
  4.1/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool toggles the spinner, but does not elaborate on potential side effects (e.g., whether it overlays the UI, affects editor state, or if repeated calls stack). The basic behavior is transparent, but additional context about the spinner's lifecycle or interaction with other UI elements is missing.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the action, and every phrase earns its place. The first sentence conveys the purpose, and the second sentence provides actionable usage guidance. No wasted words or redundant repetition of schema information.

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

  Completeness5/5

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

  For a simple tool with only two parameters and no output schema, the description covers all essential aspects: what it does, how to trigger each behavior, and when to use it. No further context is necessary for an agent to invoke it correctly.

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

  Parameters3/5

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

  Schema coverage is 100%, with both 'show' and 'message' parameters documented in the schema. The description adds minimal parameter detail beyond the schema, only implicitly linking 'show=true' and 'show=false' to starting/finishing operations. Since the schema already provides full parameter definitions, a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's action ('Show or hide a loading spinner') with a specific resource ('in the draw.io editor'). It distinguishes itself from sibling tools like show_status and show_ai_cursor by focusing on the loading spinner specifically, leaving no ambiguity about its function.

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

  Usage Guidelines4/5

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

  The description provides explicit context for when to use the tool: 'Use show=true when starting a long operation and show=false when done.' This gives clear operational timing. It does not explicitly mention alternatives or when not to use it, but for a simple spinner control, the guidance is sufficient.

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

• update_elementA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description must convey safety and side effects. It does disclose partial-update behavior ('Only specified properties are changed'), but it doesn't mention whether changes are persisted to the file, required permissions, or error handling for missing elements.

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

  Conciseness5/5

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

  Single concise sentence, no filler.

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

  Completeness3/5

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

  With 8 parameters and no annotations/output schema, the description covers the core purpose and partial-update behavior, but lacks context about file persistence, failure modes, and prerequisite conditions, leaving some gaps for a mutation tool.

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

  Parameters4/5

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

  Schema covers all parameters with descriptions. The tool description adds the key semantic that only provided parameters are updated, implying optionality and non-reset behavior for omitted properties, which goes beyond schema.

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

  Purpose5/5

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

  The description clearly states the action ('Update') and the resource ('existing node or edge in a draw.io diagram'), and distinguishes from sibling add/remove tools by specifying 'existing' and partial update.

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

  Usage Guidelines4/5

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

  The description implies usage for modifying existing elements through 'existing node or edge' and 'Only specified properties are changed', but it does not explicitly name alternative tools like add_node or remove_element or state 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.

• batch_add_elementsA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses key behavior: 'performs only one file read and one file write regardless of how many elements are added' and mentions automatic white background on edge labels. However, it does not specify whether elements are appended to or replace existing content, file-creation behavior, or error handling, leaving notable gaps.

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

  Conciseness4/5

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

  The description is front-loaded with a clear purpose and efficiency statement, followed by a clearly labeled 'LAYOUT BEST PRACTICES' section. It is longer than minimal, but each sentence provides actionable guidance for layout quality, justifying the length.

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

  Completeness3/5

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

  The description provides good context for purpose and usage, but for a complex nested-object tool with no output schema, it omits critical details: whether edges can reference nodes created in the same batch, how existing diagram content is handled (append vs overwrite), and what the return value indicates (success/failure). These gaps make it incomplete for fully reliable use.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds valuable guidance beyond the schema, such as 'Space nodes at least 200px apart horizontally and 150px vertically', 'Use "curved" edgeStyle when multiple edges connect the same nodes', and 'Use exitPoint/entryPoint to separate parallel edges.' These best practices help an agent choose appropriate parameter values, exceeding what the schema alone provides.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Add multiple nodes and edges to a draw.io diagram in a single operation.' It also distinguishes this from sibling tools add_node/add_edge by highlighting efficiency and batching, 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.

  Usage Guidelines5/5

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

  The description explicitly advises when to use this tool: 'Much more efficient than calling add_node/add_edge individually' and 'Use this for building entire diagrams or adding multiple components at once.' It names alternatives and provides a clear use case, satisfying the when-to-use criterion.

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

• get_diagram_stylesA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. 'List' implies a read-only operation, but the description does not disclose return format, pagination, or potential side effects. It is minimally viable but lacks explicit behavioral context.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the action and resource, conveying all necessary information without unnecessary words.

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

  Completeness4/5

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

  The tool is simple with no parameters and no output schema. The description clearly states what the tool lists and its purpose. It does not describe the exact return structure, but this is inferable from the context. Overall, it is sufficiently complete for an agent to use the tool correctly.

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

  Parameters4/5

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

  There are zero parameters, so the baseline is 4. The description adds context about the purpose of the output (styles for add_node/add_edge), which is helpful despite the absence of parameters.

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

  Purpose5/5

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

  The description uses the specific verb 'List' and names the resource 'predefined shape and edge styles'. It also explicitly states the styles are for use with add_node and add_edge, giving clear context and distinguishing it from sibling action tools.

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

  Usage Guidelines4/5

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

  The description implies this tool should be used before add_node or add_edge to obtain valid styles. It clearly communicates the intended usage context, though it does not explicitly state when not to use it or mention alternative tools.

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

• redo_last_operationA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden for behavioral disclosure. It transparently states that the tool re-applies changes to the diagram file, indicating a write/mutation operation. However, it does not disclose edge-case behavior such as what happens if there is no undone operation or if a conflict occurs. Given the mutation risk, more detail would improve transparency.

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

  Conciseness5/5

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

  The description is a single, concise sentence that front-loads the action and resource. Every word contributes meaning, with no fluff or repetition.

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

  Completeness4/5

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

  For a simple tool with no parameters and no output schema, the description is largely sufficient. It conveys the operation and its effect. However, it could mention prerequisites (e.g., an undo must have occurred) or failure modes, which are minor gaps given the tool's simplicity.

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

  Parameters4/5

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

  The tool has 0 parameters, so no parameter semantics are needed. The baseline of 4 applies because the description does not need to compensate for any parameter documentation gaps.

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

  Purpose5/5

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

  The description clearly states the action ('Redo the last undone MCP operation') and the affected resource ('the diagram file'). It distinguishes itself from sibling tools like 'undo_last_operation' by explicitly mentioning 'redo' and 'last undone'.

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

  Usage Guidelines4/5

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

  The description implies usage after an undo operation by referring to 'the last undone MCP operation'. This gives clear context, though it does not explicitly state when not to use it or mention alternatives. The sibling list includes 'undo_last_operation', providing implicit contrast.

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

• screenshot_diagramA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses that the tool captures the current diagram as it appears in the editor, returns a PNG image, and requires a specific runtime prerequisite (open in VS Code with extension connected). These are useful behavioral details beyond the basic action, though it doesn't cover error cases or exact viewport scope.

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

  Conciseness5/5

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

  The description is two sentences long and front-loads the core action ('Capture a screenshot'), then explains the purpose and prerequisite. Every sentence earns its place; there is no redundancy or fluff.

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

  Completeness4/5

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

  For a simple screenshot tool with three parameters fully described in the schema, the description covers the purpose, output, and prerequisite. It could add more detail about error conditions or what exactly is included in the screenshot (e.g., entire canvas vs. visible area), but it is adequate for selecting and invoking the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the parameters are already well-documented (filePath, scale, border). The description adds minimal semantic value beyond the schema, and the baseline 3 is appropriate per the rubric.

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

  Purpose5/5

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

  The description opens with a specific verb-resource pairing: 'Capture a screenshot (PNG image) of the current draw.io diagram as it appears in the editor.' It clearly distinguishes the tool from siblings like read_diagram by emphasizing visual layout, styling, and readability, making the purpose unmistakable.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool: 'so a vision-capable model can analyze the visual layout, styling, and readability.' It also states a prerequisite: 'Requires the diagram to be open in VS Code with the companion extension connected.' However, it does not explicitly mention alternatives or when not to use it, 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.

• check_connectionA
  4.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of disclosing safety and behavior. It explains that the tool reports server running status and client count, but does not explicitly state it is read-only or describe behavior when the sidecar is disconnected. For a diagnostic tool this is acceptable but not fully transparent.

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

  Conciseness5/5

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

  The description is three concise sentences: first states the main action, second details the output, third gives usage context. No redundancy or fluff; every sentence earns its place.

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

  Completeness5/5

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

  For a simple parameterless tool without an output schema, the description fully covers what the agent needs to know: what it does, what it returns, and when to use it. No gaps for this complexity level.

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

  Parameters4/5

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

  The tool has zero parameters, and the schema coverage is 100% (empty properties). The description adds meaning by explaining what the tool checks, which is all that is needed for a parameterless tool. Baseline 4 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's function: checking WebSocket sidecar connection status. It specifies the resource (WebSocket sidecar) and the action (check), and distinguishes it from sibling tools like check_layout or show_status by focusing on connection state and live-edit diagnostics.

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

  Usage Guidelines4/5

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

  The description explicitly says the tool is 'useful for diagnosing live-edit features,' providing a clear when-to-use scenario. It doesn't mention alternatives or exclusions, but for a status-check tool this context is sufficient.

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

• undo_last_operationA
  4.3/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden. It discloses that the tool restores the file to its previous state and operates independently of the draw.io editor undo, providing some behavioral context. However, it does not mention what happens when there is nothing to undo, whether the undo is reversible, or any side effects beyond the state restoration.

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

  Conciseness5/5

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

  The description is two concise sentences, front-loaded with the primary action and scope. Every sentence adds meaningful information: the first defines the operation, the second clarifies its independence from the editor. No unnecessary words.

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

  Completeness5/5

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

  For a zero-parameter tool with no output schema, the description is sufficiently complete. It defines what the tool does, the scope (MCP operations), and clarifies the relationship to the editor undo. No critical information is missing for an agent to select and invoke this tool correctly.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema is vacuous. The description does not need to explain parameters. Baseline for 0 params is 4, and there is no parameter-related information that would require elaboration.

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

  Purpose5/5

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

  The description clearly states the tool undoes the last MCP operation on a draw.io diagram and restores the file to its previous state. It uses a specific verb ('undo') and resource ('MCP operation'), and distinguishes itself from the draw.io editor undo and the sibling redo_last_operation.

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

  Usage Guidelines4/5

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

  The description provides clear context that this tool is for undoing MCP operations, not editor actions, which implies when to use it. However, it does not explicitly mention alternatives like redo_last_operation or get_change_history, so it lacks explicit when-not or alternative guidance.

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

• apply_layoutA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses key traits: the necessity of an open editor/extension, and that positions are automatically saved back to the .drawio file. This is valuable context beyond the schema, though it does not mention undo potential or error cases.

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

  Conciseness5/5

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

  The description is well-structured and front-loaded with the core action, followed by a prerequisite, a list of layout options, and a post-condition. Each sentence serves a purpose and the layout list is essential for tool selection. No wasted words.

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

  Completeness4/5

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

  Given the tool's complexity (multiple layout algorithms, prerequisite conditions) and no output schema, the description covers the essential contextual elements: what it does, when it can be used, what options exist, and the side effect on the file. It lacks detail on potential errors or return behavior, but that is not critical for a layout-triggering tool.

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

  Parameters4/5

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

  Although schema coverage is 100%, the description adds significant semantic value for the 'layout' parameter by detailing each enum option's use case (e.g., 'hierarchical' for flowcharts, 'organic' for force-directed). This goes beyond the schema's minimal 'Layout algorithm to apply' and helps the agent choose correctly.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Trigger a draw.io built-in automatic layout algorithm on the diagram.' It uses a specific verb ('trigger') and resource ('draw.io layout algorithm'), distinguishing it from siblings like check_layout, which checks rather than applies a layout.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool, including a prerequisite (diagram must be open with companion extension) and guidance on which layout to choose for different diagram types. However, it does not explicitly mention when not to use this tool or name alternative tools, so it stops short of full when/when-not guidance.

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

• check_layoutA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full responsibility for disclosing behavior. It clearly indicates this is a read-only analysis tool ('Analyze', 'Returns warnings'), details the specific output categories, and explains that suggestions consider cascading conflicts. This goes beyond basic annotations.

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

  Conciseness5/5

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

  The description is well-structured with a clear opening sentence, a bulleted list of warning types, and a closing usage paragraph. Every section provides necessary information without superfluous text, and it is front-loaded with the core purpose.

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

  Completeness5/5

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

  The tool has no output schema, so the description must explain what is returned. It does so comprehensively, listing warning categories and detailing suggestion types. It also provides usage context and references sibling tools, making it complete for an analysis tool with low parameter complexity.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the input schema fully documents both parameters (filePath and pageIndex). The description does not add parameter-specific details beyond the schema, 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.

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb and resource: 'Analyze a draw.io diagram for layout issues.' It enumerates four concrete warning types, distinguishing it from sibling tools like apply_layout (which applies layout) and update_element (which fixes issues).

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use the tool: 'Call this after building/modifying a diagram to detect readability problems.' It also names the follow-up action, 'Use the suggestions to fix issues via update_element,' clarifying its role relative to sibling tools.

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