DrawArch MCP

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds behavioral context by specifying that it measures coverage and reports missing editable elements, which clarifies the operation's output. No contradiction with annotations.

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

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

The description is a single sentence with no unnecessary words, front-loaded with the action verb. It is concise and structurally clear, maximizing information density.

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 core purpose is clear, and the presence of an output schema covers return-value expectations. However, the description does not explain what 'structural coverage' means, what input parameters are required, or how they relate to the operation, leaving a significant completeness gap.

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

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

Schema description coverage is 0%, meaning the schema provides no property descriptions. The description does not mention or explain any of the three parameters (planId, fileName, revision), failing to compensate for the missing schema details. The user is left without guidance on how to supply these inputs.

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 ('Measure') and clearly identifies the resource ('structural coverage against the approved absolute scene graph') and outcome ('report missing editable elements'). This distinguishes it from sibling tools like get_reference_plan (retrieval) and validate_drawio (format validation).

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

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

The title and description imply the use case (comparing a recreation to its reference plan), but the description itself provides no explicit guidance on when to use this tool versus alternatives. No exclusions or alternative tool names are mentioned.

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

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

Annotations provide no safety hints (all false), so the description must disclose side effects. It mentions 'self-contained' and 'real SVGs' but omits critical behavior like writing to an output file, handling the 'overwrite' flag, or the distinction between online and local assets. It does not state that this is a non-idempotent file-writing operation.

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

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

The description is a single concise sentence with no filler. It packs several useful features, but the adjective-heavy stack ('real SVGs', 'deterministic layout', 'animated colour-coded datapaths') could be streamlined to mention file output explicitly. Still, it earns its place without redundancy.

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

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

For a 9-parameter creation tool with no parameter descriptions and no visible output schema in the provided definition, the description is incomplete. It does not cover file creation, overwrite behavior, asset prerequisites, or how this tool relates to the reference diagram tools. The description is too minimal to be fully actionable.

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 explains none of the 9 parameters directly. It hints at theme, layout, animation, and editability, but does not clarify required parameters like 'outputFile', 'nodes', or the 'overwrite' flag. The schema provides structural type/enum information but not semantic guidance.

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

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

The description uses the specific verb 'Generate' with a clear resource ('self-contained native .drawio architecture') and lists distinctive features such as 'deterministic layout' and 'animated colour-coded datapaths'. However, it does not explicitly differentiate from sibling tools like create_reference_drawio, so it misses full sibling distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives such as create_reference_drawio, validate_drawio, or prepare_reference_recreation. There is no 'when to use' or 'use this rather than' information, leaving the agent to infer usage 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?

The description discloses key behaviors beyond annotations: it resolves and embeds real assets, produces an 'exact absolute-coordinate editable' artifact, and rejects stale approvals. Annotations already signal non-read-only, non-idempotent, non-destructive, and the description adds process detail without contradicting them. It does not mention failure modes or side effects beyond rejection.

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 two short sentences, front-loaded with the main action and the output type, and contains no unnecessary words. It is appropriately sized and efficiently structured.

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

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

The tool is complex, with multiple steps and sibling tools like prepare_reference_recreation and validate_reference_drawio, but the description does not mention prerequisites, relationship to siblings, or error handling. An output schema exists, so return value details are not required, but the missing workflow context leaves the description only partially complete.

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

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

The schema has 0% description coverage, and the description does not explain planId, revision, or approvalToken. The agent must infer from parameter names alone, which may lead to incorrect invocation. The description's mention of 'approved real assets' does not map to these specific parameters.

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 function: 'Resolve approved real assets, embed them, and render an exact absolute-coordinate editable .drawio artifact.' The verb 'render' plus the specific resource (approved reference recreation) and the distinguishing behavior 'Rejects stale approvals' make it stand apart from siblings like create_drawio.

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

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

The description provides clear context: it is for rendering approved reference recreations and rejects stale approvals, implying it should be used when current approval exists. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by noting the revision is 'immutable' and that it retrieves the 'latest' scene-graph revision, which is beyond what annotations alone convey. It also implies the operation is safe due to the read-only wording.

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 leads with the verb and packs in the resource, immutability, and intended use context. There is no redundant information or filler.

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

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

For a simple read operation with one parameter and an output schema present, the description is adequately complete. It conveys the purpose and timing, and the annotations cover safety traits. The only minor gap is the lack of clarity on how planId relates to 'latest', but overall it is sufficient.

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 for planId, and the description does not mention the parameter at all. While the name 'planId' suggests it identifies the plan, the description's phrase 'latest immutable scene-graph revision' introduces ambiguity about whether this is a global latest or per-plan, and no additional semantics are supplied.

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

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

The description clearly states the verb 'Read' and the resource 'the latest immutable scene-graph revision' (the reference plan), with a specific use context ('before rendering or approval'). This distinguishes it from sibling tools that create, update, or validate reference drawings/plans.

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

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

The description provides clear context for when to use this tool ('before rendering or approval'), indicating it is the read operation to fetch the current plan state. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond annotations by specifying 'safe bundled' and 'real-world', indicating the tool returns a curated set rather than arbitrary results. It also hints at flexible search via aliases and tags, enriching behavioral understanding.

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 delivers the essential purpose and search dimensions efficiently.

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

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

Given the presence of an output schema (which covers return values) and strong annotations, the description is fairly complete for a simple search tool. It adds key search dimensions and safety context. However, it leaves some ambiguity around parameter combination semantics, slightly affecting completeness.

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

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

Schema coverage is only 33% (query has a description, category and provider do not). The description partially compensates by listing category and provider as search dimensions, but it does not explain their meaning, allowed values, or how they combine with query. The mapping between 'name, alias, tag' and the query parameter is ambiguous.

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 ('Search') with a clear resource ('safe bundled real-world SVG architecture assets') and enumerates search dimensions ('by name, alias, tag, category, or provider'). This distinguishes it from siblings like list_themes and resolve_asset, which target different resources.

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

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

The description clearly implies usage for searching bundled SVG assets, but it does not explicitly state when to use this tool instead of alternatives or mention any exclusions. The 'safe bundled' qualifier provides some context, but no direct comparison with sibling tools is offered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds context about themes being selectable, which implies they are options for other tools, but it does not contradict annotations and provides useful scope.

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 that is concise and front-loaded with the core action. Every word earns its place without unnecessary detail.

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

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

For a simple list operation with no parameters, an output schema, and strong annotations, the description provides sufficient context. It explains what is listed and for what purpose, making it complete for an agent to select and invoke correctly.

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

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

The tool has zero parameters, so the schema is fully sufficient. The description does not need to explain parameter semantics, and the baseline for zero-parameter tools is 4.

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

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

The description clearly states the tool lists selectable visual themes, with a specific verb 'list' and resource 'selectable visual themes'. It also provides context about the domain (editable animated diagrams.net architecture diagrams), distinguishing it from sibling tools like list_assets.

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 one needs to know available themes, but it does not explicitly state when to use this tool versus alternatives. There is no mention of scenarios where other tools would be more appropriate.

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

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

The description adds behavioral context beyond annotations: it persists state, and notably states that DrawArch does not call another LLM. It also discloses the approval condition. It doesn't mention overwriting or side effects, but no contradiction with annotations.

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

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

Three short sentences, each providing distinct information: the action, a pipeline detail, and an approval rule. No unnecessary words, though the second sentence is slightly cryptic.

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 a large nested schema and no annotations, the description does not convey prerequisites, the exact structure needed, or how this step fits into the recreation workflow. It leaves the agent to infer what 'absolute editable scene graph' entails and doesn't mention the plan's required properties.

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, but the description does address the `approved` flag by specifying when it should be true. It only vaguely refers to the `plan` as a scene graph, leaving the extensive schema to carry the plan's structure.

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 action ('Persist') and a definite object ('the host vision model's absolute editable scene graph'), distinguishing it from sibling tools that list, validate, or create DrawIO files. The title reinforces this but the description doesn't explicitly contrast with update_reference_plan.

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

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

The description implies use for persisting the scene graph before generating the recreation, and it gives a clear approval rule ('Set approved only after...'). However, it doesn't state when to use this tool versus update_reference_plan or create_reference_drawio.

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

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

Annotations already declare the operation safe and idempotent. The description adds the specific behavior of trying bundled assets first and only using online Iconify-compatible assets when enabled (allowOnline). It also asserts 'safe' output, implying sanitization, which is useful beyond the readOnly/idempotent hints.

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 18-word sentence that front-loads the core action and adds key behavioral details. No filler or redundant information.

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

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

Although annotations and output schema exist, the description lacks explicit parameter semantics and usage guidelines. For a 4-parameter tool with 0% schema coverage, the description leaves ambiguity around query/category/provider, making it incomplete for reliable invocation.

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 carries the burden. It only implicitly references allowOnline via 'when enabled', but does not explain query, category, or provider. The agent must guess that query is the component name and category/provider are filters, which is not explicitly stated.

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 'Resolve' and specifies the resource 'architecture component' to an output 'safe embedded SVG', and mentions the resolution order (bundled vs online). This clearly distinguishes it from sibling tools like list_themes or validate_drawio, as none of those perform resolution.

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

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

The description implies usage (when you need an SVG for a component) but does not explicitly state when to use this tool vs alternatives, nor does it mention exclusions or the availability of list_assets for browsing assets. There is no 'instead of' guidance.

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?

Despite annotations already marking the tool as not read-only, not idempotent, and not destructive, the description adds valuable behavioral context: it creates an immutable new revision (no in-place mutation) and invalidates previous approvals ('Any earlier approval becomes stale'). This goes beyond what annotations convey by explaining the concurrency mechanism and the side effect on approvals, which is crucial for an agent to anticipate outcomes.

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 two concise sentences with no filler. It front-loads the core behavior (creating an immutable next revision) and follows with the key side effect (approval staleness). Every word contributes meaning, and it avoids restating the schema or annotations.

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

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

Given the tool's complexity (large nested plan schema, immutable revisioning, optimistic concurrency), the description covers the most critical behavioral aspects but leaves context gaps. It does not explain what happens on concurrency conflict, how the optional 'approved' parameter interacts with staleness, or the overall update workflow relative to other reference-plan tools. The detailed schema and output schema reduce the need to document return values or field structures, but the description still omits practical usage context.

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

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

Schema description coverage is 0% and the description provides almost no parameter-level semantics. It implies expectedRevision relates to optimistic concurrency, but does not explain planId, plan, or approved. Parameter names are somewhat self-explanatory, but the optional 'approved' field's role in the revision/approval lifecycle is ambiguous from the description alone. The verbose schema constraints help validate input but do not convey business meaning.

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 revision of a reference plan, which matches the 'update' name via immutable revisioning. It distinguishes this from sibling tools like get_reference_plan or create_reference_drawio by focusing on revision creation rather than retrieval or file generation. However, it does not explicitly mention the optional 'approved' parameter or frame the action as updating an existing plan, which would strengthen clarity.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention that this is the tool to call when modifying an existing reference plan, nor does it reference sibling tools like get_reference_plan for reading or prepare_reference_recreation for pre-update steps. The optimistic concurrency hint implies a precondition (expectedRevision must match current), but this is not elaborated or compared to other tools' workflows.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the safety profile is known. The description adds behavioral context by listing the specific validation categories and scoping to the output directory, which is not present in the annotations. There is no contradiction.

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 front-loads the action and includes only essential information. No filler or redundancy.

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

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

For a one-parameter validation tool with comprehensive annotations and an output schema, the description fully captures the tool's scope and behavior. It specifies what the tool validates and where, which is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, but the description compensates by indicating that the file is a .drawio file and located in the configured output directory, giving context to the fileName parameter. The schema provides the pattern, and the description clarifies the file's expected location and scope.

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

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

The description uses the specific verb 'Validate' with the resource '.drawio file inside the configured output directory' and enumerates the exact checks (structural errors, dangling references, duplicate IDs, unsafe images). This clearly distinguishes it from sibling validation tools such as validate_reference_drawio.

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

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

The description provides clear context by specifying the target location (configured output directory) and the types of issues it checks. However, it does not explicitly mention when to prefer this over the similar sibling validate_reference_drawio, so it lacks explicit exclusion or alternative guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe, non-destructive nature is known. The description adds value by specifying exactly what is validated (structure, IDs, references, embedded-image safety), providing behavioral context beyond the annotations.

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

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

The description is a single, tightly written sentence with no filler. It front-loads the verb and resource and lists the validation dimensions efficiently.

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

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

For a one-parameter validation tool with annotations covering side effects and an output schema presumably defining returns, the description sufficiently conveys the core function and validation targets. It does not clarify its differentiation from validate_drawio, but that is more a usage-guideline gap than a completeness gap.

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

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

The sole parameter, fileName, has no schema description (0% coverage) and is not mentioned in the tool description. The schema pattern gives format constraints, but the description adds no semantic explanation of what fileName represents or how it relates to the validation operation, leaving a 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 a specific action (Validate) applied to a specific resource (a generated reference recreation) and enumerates the validation focus (native Draw.io structure, IDs, references, and embedded-image safety). This distinguishes it from sibling tools like validate_drawio by targeting reference recreations specifically.

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 provide any guidance on when to use this tool versus alternatives such as validate_drawio or compare_reference_recreation. It lacks workflow context, prerequisites, or any explicit exclusions, leaving the agent to infer usage 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.