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 states what it extracts but does not mention side effects (though analysis likely implies read-only), return format, error conditions, or any limitations. The description gives some insight but falls short of full transparency.

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

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

The description is a single, well-structured sentence with no redundant information. It efficiently conveys the primary function and key outputs without wasting words.

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

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

While the description lists expected outputs, it omits essential context such as input path format, any prerequisites or constraints, and how the results are returned. The output schema exists but is not referenced, and the 0% parameter schema coverage compounds the incompleteness. An agent would need additional information to use the tool reliably.

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 description coverage for its only parameter 'input_path', and the description does not mention or explain this parameter at all. The agent is left to guess what input_path should refer to (file path, diagram ID, etc.). This is a critical gap in a single-parameter tool.

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's purpose with a specific verb 'Analyze' and resource 'diagram topology', and enumerates concrete outputs (entry points, sinks, feedback cycles, bottlenecks, critical execution paths). This distinguishes it from sibling tools focused on generation, editing, or conversion.

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?

Usage context is implied through the verb 'analyze' and the nature of outputs, but there is no explicit guidance on when to choose this tool over similar analysis-oriented siblings like parse_diagram or validate_diagram. No when-not conditions are provided.

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?

No annotations are provided, and the description does not disclose side effects such as whether the input file is modified in place, if output_path is required for safety, or if the operation is reversible. The description only lists the actions performed (auto-layout, link resolution, theming) without addressing impact on the source diagram.

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, focused sentence that lists the core actions concisely. It has no fluff or redundant phrasing, making it easy to parse quickly.

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?

While the description covers the primary purpose, it leaves out critical context such as output format, return value, error conditions, and parameter constraints. The output schema is present but not elaborated, and the description does not clarify how this tool integrates with the diagram lifecycle (e.g., whether it produces a new file or updates an existing one).

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 0%, and the description does not explain any of the three optional parameters (theme, output_path, layout_direction). It mentions applying themes and auto-layout but does not specify valid values for theme or layout_direction, nor clarify the role of output_path. The description fails to compensate for the lack of schema-level documentation.

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 ('beautify') and the object ('any existing diagram'), which is distinct from generation or analysis siblings. However, 'any existing diagram' is somewhat generic and could apply to multiple diagram types, but it is still precise enough for basic routing.

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 like patch_diagram, resolve_diagram_collisions, or generate_smart_diagram. It does not mention prerequisites, typical use cases, or when not to use it.

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

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 only states the conversion action without revealing any side effects, error conditions, file handling (e.g., overwriting), or requirements for input validity. This is a minimal disclosure that leaves important behaviors unspecified.

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, which is concise. However, it lacks structure or front-loading of key details; it is merely a statement of functionality. While concise, it doesn't organize information for quick scanning.

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 tool with two required parameters and a conversion task, the description is incomplete. It does not explain the expected format of mermaid_code, the behavior of output_path (e.g., overwriting), or any error handling. Given the many sibling tools, it also fails to provide context for selection. The presence of an output schema is not referenced, so the agent gets no help on 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 schema has 0% description coverage, so the tool description must explain the parameters. The description mentions 'Mermaid JS graph definition string' and 'native .drawio XML' but does not explicitly map these to the two required parameters (mermaid_code and output_path). It implies that mermaid_code is the input string and output_path is the destination, but this is not explicit or detailed enough.

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 action: converting a Mermaid JS graph definition string into native .drawio XML. This identifies the resource and result, making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like generate_er_diagram or parse_diagram, though the conversion aspect is distinctive enough.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing valid Mermaid syntax, nor does it suggest scenarios where this tool is preferred over other diagram-related tools. The agent must infer usage entirely.

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 mentions file creation but does not disclose whether it overwrites existing files, what return value is provided, or error handling behavior. No annotations are present to supplement this information.

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, direct sentence that efficiently conveys the core functionality without unnecessary words or repetition. It is well-structured and 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?

Given the tool has four parameters including nested arrays and a default value, the description and schema lack essential details such as node/edge format, coordinate semantics, page_name usage, and output behavior. The absence of annotations compounds the incompleteness, making the tool difficult to use correctly without external knowledge.

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 lists parameters with titles only, and no descriptions are provided. The description mentions 'nodes and edges at specified coordinates' but does not explain the structure or how coordinates are specified, leaving the agent without sufficient parameter detail.

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 creates a new .drawio XML diagram file with nodes and edges at specified coordinates. The verb 'Create' and the format specification make the purpose unambiguous, and it distinguishes from sibling tools that generate specific diagram types.

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

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

The description implies usage when a new generic diagram is needed, but it does not explicitly state when to prefer this tool over siblings like generate_er_diagram or generate_sequence_diagram. There is no guidance on prerequisites or selection criteria.

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?

No annotations are provided, so the description must carry the full behavioral disclosure. It mentions using a desktop CLI, which hints at an external dependency, but does not describe side effects, safety, or what happens on failure. This is insufficient for a tool with no annotation support.

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 action and formats. Every word contributes to the core purpose with no 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?

For a tool with four parameters and an output schema, the description is sparse. It does not mention the output file behavior, page selection, or any constraints. While an output schema exists, it is not enough to make this description complete for effective agent use.

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

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

Schema description coverage is 0%, and the description only mentions output formats. It does not explain input_path, output_path, format, or page_index beyond what the schema already shows. The description adds no meaningful parameter semantics and fails to compensate for the coverage 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 clearly states the action (export), the input resource (.drawio XML diagram), and the output formats (PNG, SVG, PDF, JPEG). It distinguishes itself from sibling tools that generate, patch, or parse diagrams.

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 this tool is for converting diagrams to images, but it does not explicitly state when to use it versus alternatives, nor does it mention any preconditions or exclusions. It is clear enough for a single-purpose tool but lacks explicit routing.

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?

No annotations are provided, so the description carries the full burden. It only says 'generate', implying creation, but does not disclose that it writes to output_path, whether it overwrites, what the output format is, or any side effects. This is a significant gap for a tool with zero annotation coverage.

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

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

A single, efficient sentence with no fluff. The key action and resource are front-loaded, and every word contributes to the purpose.

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 a complex nested spec object, but the description gives no guidance on how to structure the spec or what the return value represents. An agent would likely need examples or additional details 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 0% and the description does not explicitly explain the parameters. However, the phrase 'with actors, systems, and boundaries' hints at the content of the spec object, and output_path is self-explanatory. Still, spec is a free-form object with additionalProperties true, so more guidance would be beneficial.

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 ('Generate') and a specific resource ('C4 architecture diagram') with the three view types and elements, clearly distinguishing it from sibling tools like generate_er_diagram or generate_sequence_diagram.

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

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

The description implies usage for C4 diagrams but does not explicitly compare with alternatives or state when not to use this tool. There is no guidance on choosing between C4 and other diagram types, leaving the agent to infer 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?

The description only states 'generate' without detailing side effects like whether it overwrites existing files, creates new ones, or requires specific permissions. The lack of annotations places full burden on the description, which remains generic.

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 concise sentence, front-loaded with the action ('Generate') and structured to list key components, achieving high clarity with minimal words.

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

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

Given the complexity of an ER diagram tool and the presence of a nested 'spec' object, the description lacks essential context about how to construct the spec, what output format is produced, or how the tool integrates with sibling tools. This leaves significant gaps for an agent trying to use it.

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

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

The schema provides only parameter names and types (spec as object, output_path as string) with no descriptions. The tool description does not explain what 'spec' should contain or how 'output_path' is used, offering no semantic clarity beyond the bare schema.

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

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

The description clearly states the tool generates a relational database ER schema diagram with specific elements (tables, primary/foreign keys, types, cardinalities), distinguishing it from sibling diagram generators like sequence or C4.

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 ER diagrams but lacks explicit conditions or comparison to alternatives such as generate_smart_diagram or generate_c4_diagram. No 'use this when' guidance is provided.

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?

No annotations are supplied, so the description carries the full burden of behavioral disclosure. It only states the generation action without describing side effects like file creation, overwriting behavior, error handling, or the structure of the return value. The agent cannot anticipate what happens when the tool runs.

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 redundancy. It is front-loaded with the primary action, but the brevity sacrifices necessary detail, making it more under-specified than effectively concise.

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 spec object with no schema definition and an output schema that is not described. The description fails to mention the spec format, required parameters, output behavior, or any dependencies. It is entirely inadequate for a tool with this complexity, even with the presence of an output schema.

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

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

The schema has 0% description coverage and the description does not explain the 'spec' object or the 'output_path' string. With no parameter details in either the schema or the description, the agent has no idea what the spec should contain or how to construct it, making correct invocation impossible.

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 action ('Generate a UML sequence diagram') with concrete elements (lifelines, sync/async call arrows, return messages), which distinguishes it from sibling tools like generate_er_diagram or generate_c4_diagram. It clearly identifies the resource type and the key features, though it omits the output_path and spec parameters from the sentence.

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

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

No guidance is provided on when to use this tool versus alternatives such as generate_c4_diagram or generate_smart_diagram. There is no mention of scenarios, prerequisites, or exclusions, leaving the agent to infer the appropriate context from the name alone.

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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It mentions auto-layout and professional theming, but it does not explain what happens at the output_path, whether existing files are overwritten, how containers affect layout, or what the generated output looks like. For a tool with no annotation safety profile, this is under-disclosed.

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 is concise, but it is also under-specified relative to the tool's seven parameters and the rich sibling context, so the brevity comes at the cost of necessary guidance.

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?

This is a seven-parameter tool with no annotations and zero schema description coverage, so the description needs to carry significant weight. It leaves the node/edge/container formats, output behavior, and selection criteria unexplained. The presence of an output schema helps with return values but not with how to invoke the 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 description coverage is 0%, so the description must compensate for the undocumented parameters. It hints that nodes and edges do not require manual pixel coordinates, but it does not explain output_path, nodes, edges, containers, theme, title, or layout_direction. This adds only minimal parameter-level meaning beyond the raw 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 specific verb ('Generate') and a clear object ('diagram') with distinctive traits: professionally themed, auto-laid-out, and no manual pixel coordinates. It is clear about what the tool does, but it does not explicitly distinguish itself from sibling tools like create_diagram or beautify_diagram, so it falls short of full differentiation.

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 phrase 'without calculating manual pixel coordinates' implies this tool is for auto-layout diagram generation, which gives some usage context. However, it provides no explicit when-to-use guidance, no exclusions, and no mention of alternatives among the many sibling diagram 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?

There are no annotations to describe side effects or error behavior. The description is straightforward but does not disclose what happens if the file is missing, whether the app launch is synchronous, or any potential side effects on the file system.

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 unnecessary words or repetition, providing exactly the essential information about the tool's purpose.

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, the description covers the core action, but it lacks details about the output schema, error handling, or any prerequisites. Given the tool's simplicity, this is adequate but not fully 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?

The schema has no description for input_path, and the tool description only indirectly implies it is the path to the .drawio file. While the name and context make it likely, the description does not explicitly define the parameter's meaning or expected format.

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 explicitly states the tool's action ('Open a .drawio diagram file') and the target application ('local Draw.io Desktop GUI app'), making it clear and distinct from sibling tools that create, parse, export, or validate diagrams.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention any conditions or preferences, leaving the agent without clear selection criteria.

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?

With no annotations, the description carries the burden of behavioral disclosure. 'Parse' and 'extract' imply a non-mutating read operation, which is helpful, but the description does not mention prerequisites, error behavior, or whether the input file is left unmodified.

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 filler. It states the action, the input, and the output in one pass, making it easy for an agent to scan.

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 required parameter) and an output schema exists, so the description does not need to enumerate return fields. It covers the essential input and extraction scope, though it omits edge cases like invalid XML or missing files.

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 0%, so the description must compensate for the bare 'input_path' parameter. It adds that the value is a '.drawio XML file', which gives useful type context, but it does not clarify path formats, existence requirements, or supported file locations.

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 ('Parse') and resource ('.drawio XML file') and names the extracted outputs: nodes, edges, and page metadata. It is clear about what the tool does, though it does not explicitly differentiate itself from the sibling analyze_diagram.

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

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

The description gives no guidance on when to prefer this tool over siblings like analyze_diagram or validate_diagram. It states the action but provides no context, exclusions, or alternative routing.

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?

No annotations are provided, so the description carries full behavioral burden. It lists the operation types (add/delete/update nodes, rewire edges, group, highlight) and implies surgical modification, but does not disclose whether it modifies in place or requires an existing file, side effects, error handling, or the nature of the return value. This is a moderate disclosure but not comprehensive.

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

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

A single, densely packed sentence that conveys the purpose and scope efficiently. It is front-loaded with the primary action and lists specific operation types, avoiding unnecessary words.

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

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

Despite having an output schema, the description does not explain the operation format, the relationship between input and output paths, or the expected response. For a tool with a complex operations array, this is insufficient for an agent to construct valid calls. The description lacks critical parameter details and behavioral constraints.

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 0%, so the description must compensate. It mentions 'operations' conceptually (listing possible actions) but does not explain the structure of the operations array, the meaning of drawio_path and output_path, or how they interact. Only minimal semantic value is added beyond the parameter names.

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 strong verb ('patch') and specifies the resource (existing diagram) and the scope of modifications (add/delete/update nodes, rewire edges, group, highlight). It clearly differentiates from siblings like create_diagram (new diagram) and generate_* tools (from scratch), and from read-only analyze_diagram.

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

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

The description implies this is for modifying an existing diagram, but does not explicitly state when to choose it over alternatives (e.g., 'use create_diagram for new diagrams' or 'use analyze_diagram for inspection'). The purpose is clear enough for an agent to infer, but no explicit when/why-not guidance 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?

With no annotations, the description carries the full burden of disclosing side effects. It reveals that coordinates are shifted, but it does not state whether the input file is modified in place, what output_path controls, or what the operation returns. For a mutating tool, this is a significant transparency 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 a single focused sentence with no filler, and the core action and mechanism are front-loaded. It is concise, though it achieves this by omitting important operational details penalized in other dimensions.

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

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

For a mutating tool with no annotations, the description is too thin to support confident invocation. It omits output_path semantics, in-place editing behavior, and any guidance about choosing this over related diagram tools. An agent can grasp the purpose but not the full call contract.

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 0%, and the description does not map input_path or output_path to their roles. It only implies a .drawio file is involved, leaving the agent to guess which path is required and what happens when output_path defaults to null.

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 ('resolve'), a specific resource ('node collisions in a .drawio diagram'), and a mechanism ('shifting overlapping coordinates'). It is clear and distinct from sibling tools in topic, though it does not explicitly name an alternative to differentiate against.

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 siblings like patch_diagram, beautify_diagram, or analyze_diagram. The agent must infer applicability solely from the name and brief action phrase.

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?

No annotations are provided, and the description uses 'audit' which implies a read-only operation but does not explicitly state side effects, return values, or whether the file is modified. The behavior is reasonably clear 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.

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

The description is a single, concise sentence with no redundant words. It directly and efficiently communicates the tool's purpose.

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 validation tool, the description covers the main purpose, but it omits details such as whether the tool returns a report, throws exceptions, or writes output. Given the lack of an output schema or annotations, the description is adequate but not fully 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?

The only parameter 'input_path' is documented in the schema as a string, but the description does not explicitly link it to the .drawio file path. While this is a reasonable inference from the description, the description adds minimal semantic detail beyond the schema itself.

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 ('audit') and a specific resource ('.drawio diagram file') and enumerates the exact checks performed ('node collisions and text boundary overflows'). This fully conveys what the tool does without ambiguity.

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

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

The description does not mention when to use this tool versus alternatives such as 'analyze_diagram' or 'resolve_diagram_collisions'. There is no guidance on conditions that would make this tool preferable over others, leaving the agent to infer the appropriate context.

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