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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this by stating 'This tool does NOT modify the diagram or the code.' Beyond that, it discloses the heuristic, text-based nature, the 5,000-file scan cap, truncation behavior, confidence level, and the distinction between reliable/experimental/generic analyzers. This exceeds what annotations alone convey.

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

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

The description is lengthy, but it is well-structured with clear sections (overview, args, returns, examples, error handling) and front-loads the purpose and key non-modifying constraint. Every section adds value, though the inline return schema is verbose. Slightly overlong but organized enough to earn a 4.

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

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

The description is exceptionally complete for a heuristic check tool: it covers the return schema in detail, error handling, edge cases (entities_found=0, truncation), and the confidence level. Despite having no output schema annotation, the description fully specifies the expected JSON structure and all relevant failure modes, leaving no ambiguity for an agent.

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

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

Schema coverage is 100% and the only parameter (relative_path) is already described as 'Path to the diagram to check, relative to the diagrams root.' The description adds example paths and clarifies the root relative interpretation, but these are marginal additions beyond the schema. The baseline of 3 applies since the schema carries the semantic load.

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

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

The description clearly states the tool compares entity names in diagrams against code identifiers to catch documentation drift. It names the specific resource (PlantUML/Mermaid diagrams vs codebase) and distinguishes itself from sibling tools like diagrams_get or diagrams_render by focusing on consistency checking, not creation, retrieval, or rendering.

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

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

Provides explicit when-to-use scenarios ('Is this class diagram still accurate?', PR review) and a concrete don't-use condition (pure sequence diagram with no declarations, where entities_found=0 is expected). Also clarifies that an empty issues array with entities_found=0 means no checkable entities, not a pass, preventing misinterpretation.

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

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

Annotations only indicate non-readOnly, non-idempotent, non-destructive behavior. The description goes far beyond this by disclosing that it refuses to overwrite, creates intermediate directories automatically, performs a basic non-validating syntax check, rejects invalid/empty sources without creating files, prevents path escape, and logs unexpected errors safely without leaking secrets.

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 well structured: purpose first, then extension rules, overwrite policy, validation behavior, arg definitions, return shape, examples, and error handling. It is long but every section earns its place and the most decision-relevant information is front-loaded.

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

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

For a creation tool with no output schema, the description fully compensates by specifying the exact return JSON structure, listing all expected error messages, and providing concrete usage examples. An agent has everything needed to invoke it correctly and anticipate failure modes.

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

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

The input schema already describes both parameters fully (100% coverage). The description adds value by clarifying the extension-to-type mapping, the meaning of a recognized extension, automatic creation of intermediate directories, and the syntax-check behavior, which give the agent practical context for constructing valid parameter values.

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 ('Create'), a specific resource ('PlantUML or Mermaid diagram file under the diagrams root'), and the inference rule from the file extension. It clearly distinguishes this tool from diagrams_update by explicitly saying it refuses to overwrite existing files.

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 explicit usage context: use for creating new diagrams, and explicitly says not to use it when the file exists and needs changing, naming diagrams_update as the alternative. The included examples of when and when not to use it make the decision easy for an agent.

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

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

Beyond the destructiveHint=true annotation, the description discloses that deletion is physical and irreversible ('file is removed from disk'), details error responses for missing files and path traversal attempts ('Refused to access path outside the diagrams root'), and clarifies how internal failures are logged without leaking sensitive data. This is rich behavioral context that annotations alone do not provide.

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 longer than average, but every section earns its place: purpose, destructiveness warning, alternatives, args, return shape, examples, and error handling. The most critical facts (destructive, irreversible) are front-loaded, and the structured sections make the content easy for an agent 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?

For a destructive one-parameter tool with no structured output schema, the description is fully complete. It includes the return JSON shape, all relevant error cases, path safety constraints, and sibling-tool alternatives, so an agent has everything needed to invoke it correctly and predict consequences.

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

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

Schema coverage is 100%, so the baseline is 3; the description's Args section largely repeats the schema. However, the error-handling section and examples add meaning beyond the schema by clarifying that paths must come from diagrams_list and that escaping the diagrams root is refused, giving the agent a better model of valid and invalid 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 opens with a specific verb and resource: 'Delete a single PlantUML or Mermaid diagram file from the diagrams root.' It clearly distinguishes the tool from siblings by explicitly naming diagrams_update and diagrams_create as alternatives for different goals, so an agent can select it correctly without opening schemas.

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 explicit when-to-use and when-not-to-use guidance: replace content -> use diagrams_update; remove and recreate -> delete then create. It also provides concrete examples ('Remove the outdated order-flow diagram') and a 'Don't use when' clause, making the decision boundary unambiguous.

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, destructiveHint=false. The description adds substantial behavioral detail beyond this: it explains the windowing behavior with is_partial/has_more flags, guarantees no silent truncation, and provides a comprehensive error-handling list (file not found, path escape, invalid window, out-of-range offset). This far exceeds annotation coverage and fully discloses behavior.

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

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

While long, the description is modularly structured with clear sections (Args, Returns, Examples, Error Handling) and front-loads the core purpose. Every sentence serves a purpose—there is no fluff or repetition. The length is justified by the tool's windowing and error complexity, and the structure makes it easy 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?

Despite lacking an output schema, the description provides a full inline JSON return schema with all fields explained. It covers error cases, examples, and parameter usage. For a tool with this complexity (character windows, partial returns), the description leaves nothing an agent needs to call it correctly; it is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces each parameter and adds usage nuance: it explains that omitting offset/max_chars returns the full source, demonstrates a windowing example (offset=0, max_chars=2000, then offset=2000), and clarifies the zero-based offset. This goes beyond the schema's basic type/range descriptions, though it does not introduce entirely new semantics.

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

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

The description opens with a precise verb+resource statement: 'Retrieve the raw source text of a single PlantUML or Mermaid diagram, in full or as an explicit character window.' It clearly distinguishes itself from siblings, explicitly noting the alternative diagrams_list for listing diagrams. No ambiguity about what this tool does.

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

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

The Examples section explicitly states 'Use when' scenarios (e.g., 'Show me the order-flow diagram') and 'Don't use when' (e.g., when needing to list diagrams first, use diagrams_list). It also instructs that relative_path should come from diagrams_list, giving clear routing to the correct sibling.

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

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

The annotations already indicate readOnly, idempotent, and non-destructive behavior, and the description adds substantial context: recursive scanning, no create/modify/render side effects, explicit pagination semantics, empty-directory behavior, out-of-range offset behavior, and error message shapes. There is no contradiction with 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 long but well-structured and front-loaded with the core purpose. Every section (args, return schema, pagination, examples, error handling) earns its place since there is no output schema or separate documentation to carry that 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?

With no output schema, the description fully specifies the return JSON structure, pagination flags, field meanings, and error behavior. It also covers the main sibling-tool distinction and edge cases like empty directories and invalid offsets, making it complete 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.

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

The input schema has 100% description coverage, so the baseline is 3. The description adds value beyond the schema by explaining the pagination contract (has_more, offset=offset+count, nothing silently dropped) and giving concrete examples for using limit and offset together. It somewhat restates the schema defaults, which prevents a higher score.

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 names a specific verb and resource: it scans the diagrams directory and lists PlantUML/Mermaid files. It also explicitly differentiates itself from siblings by stating it does NOT create, modify, or render diagrams, and by referring to diagrams_get when the exact path is already known.

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 concrete 'Use when' examples for all filters and pagination scenarios, and a 'Don't use when' case naming diagrams_get as the alternative. This is explicit routing guidance that leaves no ambiguity about when to select this tool over siblings.

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, destructiveHint=false. The description adds extensive behavioral context beyond these: exact rendering dependencies, remote fallback conditions with environment flags (ALLOW_REMOTE_PLANTUML, DISABLE_REMOTE_PLANTUML), detailed error messages, and a security note about logging without source/paths/secrets. This is rich, non-redundant 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 longer than average, but every section (rendering requirements, args, returns, examples, error handling) carries necessary information for a tool with complex dependencies and failure modes. It is well-structured with headings and front-loaded purpose. A small amount of redundancy exists (error messages are verbose), but overall it is efficient.

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 rendering tool with two distinct renderers, fallback behaviors, and CLI dependencies, this description leaves nothing unstated. It covers prerequisites, flags, error cases, output format (base64 + JSON summary), and security/privacy concerns. Without an output schema, the description fully compensates by explaining the return structure. Complete for an agent to use correctly.

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

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

Schema coverage is 100% and both parameters already have clear descriptions. The description reinforces relative_path's meaning (relative to diagrams root) and format's default, but more importantly adds example parameter values ('system/order-flow.puml', 'svg') that disambiguate real usage. It slightly exceeds the baseline by providing usage examples.

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

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

The description opens with a specific verb-resource pair: 'Render a PlantUML or Mermaid diagram to an image (SVG or PNG)' and clarifies the output is base64 content. It clearly distinguishes from siblings by stating when not to use it (use diagrams_get for raw source), which is explicit sibling 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?

Provides concrete when-to-use ('Show me what the order-flow diagram looks like') and when-not-to-use conditions (raw source -> use diagrams_get). Additionally details prerequisites (mmdc CLI, plantuml CLI), fallback flags, and even names the preferred alternative (diagrams_get) – no ambiguity left.

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 substantial behavior beyond the annotations: it discloses the pre-write syntax check, clarifies it is not full validation, states rejection conditions, and assures the original file is left unchanged on invalid input. This complements destructiveHint=true and idempotentHint=true without contradicting them.

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 long but well-structured with labeled sections, and the core behavior is front-loaded in the first paragraph. Every sentence serves a purpose, including the detailed error-handling list, which is practically useful for agents.

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

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

For a mutation tool with no output schema, the description is complete: it specifies the return shape, error cases, validation behavior, file-overwrite semantics, and sibling alternatives. An agent has enough information to invoke the tool correctly and anticipate failures.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the description mostly restates the parameter meanings. It does add mild context (e.g., 'pass the complete new diagram source' and create_if_missing behavior), but it does not uncover anything fundamentally beyond the schema.

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

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

The description states a specific verb ('Replace') and resource ('existing PlantUML or Mermaid diagram file'), and explicitly clarifies it is a full-content replace rather than a partial edit. It differentiates itself from diagrams_create by naming the sibling tool and the create_if_missing alternative.

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

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

Usage guidance is explicit: it says when to use this tool, when not to, and names alternatives. The 'Use when' and 'Don't use when' examples directly instruct agents to read current content with diagrams_get first and to prefer diagrams_create for new files unless auto-creation is desired.

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