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

Beyond the readOnly/non-destructive annotations, it discloses three non-obvious traits: detection is macOS-only with other platforms always reporting not installed, the result is stable within a session so caching is safe, and the return is a prose sentence plus a JSON object with named keys.

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 sentences, front-loaded with the core purpose, then output shape, then the platform caveat and decision rule. No filler and every clause carries actionable 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 compensates by naming the return shape (sentence plus { installed, paths, platform }), and it supplies the decision context the agent needs. Nothing required to call it correctly is missing.

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

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

This tool takes zero parameters, so there is nothing to document and the baseline is 4. The mention of `filePath` refers to open_in_app's parameter, not this tool's, so it neither helps nor hurts.

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

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

The description states a specific verb and resource ('Check whether the Diagrammo desktop app is installed') and immediately distinguishes itself from sibling tools like open_in_app and share_diagram by naming them as the consumers of its result.

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?

It gives explicit when-to-use guidance ('one call is enough before deciding how to show a diagram') and a complete decision rule: installed → open_in_app with `filePath`, otherwise → share_diagram. When-not-to-use is implied by the session-stable note, which tells the agent not to call repeatedly.

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 cover safety (readOnlyHint=false, destructiveHint=false) and open-world behavior, but the description adds specific context: the tool opens the report in a browser by default and produces an HTML report with optional source blocks. This goes beyond the generic openWorldHint, though it doesn't detail file persistence or permissions.

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 sentences, front-loaded with the core action, followed by a key behavioral note and a helpful cross-reference. Every sentence earns its place with no redundancy.

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

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

For a report-generation tool with no output schema, the description covers the output format (HTML report with TOC and diagrams), key behavior (opens in browser), and points to syntax reference. It lacks details on return value (e.g., file path) or file saving location, but the rich schema compensates sufficiently.

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 schema fully documents all parameters. The description mentions multiple diagrams, table of contents, and optional source blocks, which loosely map to sections and include_source, but adds no syntax or format details beyond what the schema already provides.

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 resource (HTML report) with key features (multiple DGMO diagrams, table of contents, optional source blocks). It clearly distinguishes this tool from sibling diagram tools like render_diagram or preview_diagram by focusing on multi-section report generation.

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 only points to get_language_reference for DGMO syntax, which is a sub-task aid rather than guidance on when to use this tool versus alternatives. Usage is implied (for creating reports) but no explicit when/when-not or alternative selection criteria 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?

With no annotations, the description carries the full burden. It states it returns real-world examples, but does not mention behavior when the parameter is omitted (lists all names) or any read-only implications. Adequate 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?

Two short, front-loaded sentences with no redundancy. Every phrase earns its place.

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

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

For a tool with one optional parameter and no output schema, the description fully explains purpose, return content, and usage context. Complete for its complexity.

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 description does not need to add much. It provides example values and tells to omit for listing names, which adds slight value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('get'), the resource ('example DGMO diagrams for a chart type'), and the purpose ('few-shot references'). It is specific and distinguishes from siblings like generate_report or validate_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 explicitly says 'Use these as few-shot references when generating new diagrams,' indicating when to use. It does not explicitly state when not to use or mention alternatives, but the context makes it clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral context: the no-argument call returns a very large payload (hundreds of KB), an error occurs for undocumented types, and the returned content includes universal rules (color set, titles, categorize-and-color). This is exactly the kind of cost/error/redundancy disclosure annotations cannot carry.

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 dense sentences, front-loaded with the core action before the conditional behavior and the sibling-avoidance note. Every clause carries information; it is slightly long but no sentence is 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?

No output schema exists, so the description must describe return values, and it does: the type section plus universal rules, or the full reference. Error behavior, alternatives, and payload-size trade-offs are all covered, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the effect of the parameter (returns that type's section plus universal rules), the consequence of omitting it (entire reference, very large), and the failure mode (errors for undocumented types, ids via list_chart_types). Only the absence of example id syntax keeps it from a 5.

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?

States a specific verb and resource ('Get the DGMO language reference') and precisely scopes the two modes of operation (with vs. without chart_type). It explicitly distinguishes itself from siblings suggest_chart_type and list_chart_types, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use guidance ('pass chart_type whenever the type is known'), a when-not ('suggest_chart_type already appends the chosen type's section, so a call here is only needed after the user picks a type or when switching types'), and names the fallback tool for error recovery (list_chart_types for valid ids).

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 minimal behavioral context beyond stating the content (chart types with descriptions). It does not contradict annotations, but it also does not elaborate on traits like return format or error states.

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 of 6 words, conveying the essential purpose without any extraneous information. It is front-loaded and 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?

Given the simplicity of the tool (no parameters, annotations present, no output schema), the description is largely complete. It informs the agent what the tool does and what content to expect. However, it could hint at the output structure (e.g., 'returns an array of chart type objects with name and description'). Still, it is sufficient for an agent to understand the tool's purpose.

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?

No parameters exist, so schema coverage is 100%. The description adds context by specifying that the list includes descriptions, which adds meaning beyond the empty schema. Baseline for 0 params 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 'List all supported DGMO chart types with descriptions' clearly states the verb (list), the resource (chart types), and the scope (all supported, with descriptions). It distinguishes from sibling tools like 'suggest_chart_type' which is for recommendations, not listing.

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 is implied: use to get a list of chart types. However, there is no explicit guidance on when to use versus alternatives such as 'suggest_chart_type', nor any exclusions or prerequisites, so the description lacks clear context for selection.

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

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

Annotations are minimal (readOnlyHint, destructiveHint, openWorldHint). The description adds critical behavior: macOS only, fallback to browser preview, filePath autosaving and live re-render, and the distinction between ephemeral and persistent modes.

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?

Five sentences, front-loaded with the main action and platform. Every sentence adds essential information without redundancy or filler.

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

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

No output schema, but the description explains the two modes and fallback. It covers platform restriction and file persistence. Could mention installation requirement more explicitly, but 'preferred path when app is installed' implies 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?

Schema coverage is 100% with descriptions. The description adds value by explaining that filePath opens the exact file for live editing (source of truth) and that dgmo is the markup. This enriches the basic schema definitions.

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 specifies the verb 'open', the resource 'DGMO diagram', and the platform 'macOS only'. It distinguishes from sibling tools like 'preview_diagram' by noting fallback behavior and file handling.

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 guidance on when to use filePath (for saved files with live editing) vs omit (ephemeral diagram). It implicitly contrasts with preview_diagram as fallback, but does not explicitly list when not to use.

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

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

Annotations already declare readOnlyHint false and openWorldHint true, signaling a non-read-only, external-interacting operation. The description adds that it opens an HTML preview in the browser, which aligns with openWorldHint, but does not clarify permissions, temporary file side effects, or rate limits. It offers modest 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?

Two sentences plus a routing pointer, front-loaded with the primary action and output medium. Every sentence earns its place; the syntax pointer prevents misuse and is not redundant.

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 preview tool with full schema coverage and no output schema, the description covers the essential behavior and optional features. It omits usage comparisons, but overall it is complete enough for correct 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 description coverage is 100%, so all four parameters are fully documented in the schema. The description mentions theme toggle and optional source display, mapping to theme and include_source, but adds no format or syntax detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb ('Render') and resource ('DGMO diagrams'), and names the output medium ('open an HTML preview in the browser'). It does not explicitly distinguish from siblings like render_diagram or open_in_app, but the scope is clear enough for selection.

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 a pointer for syntax ('call get_language_reference'), which is a prerequisite note rather than when-to-use guidance for this tool. There is no explicit comparison to alternatives like render_diagram, share_diagram, or open_in_app; usage is only implied by the tool name and purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the return shape (SVG text vs base64 PNG) and the side effect that PNG format writes a temp file and returns its path. It still doesn't mention failure behavior for invalid markup.

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, front-loaded with the primary action and output formats, with no filler. The final syntax-pointer sentence is somewhat redundant with the schema's own note but still earns its place as a routing hint.

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 correctly shoulders the return-value burden (SVG text or base64 PNG, plus temp file path). Given six parameters and a rendering operation, the main remaining gap is error/validation behavior, which is minor for a read-only render tool.

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

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

Schema description coverage is 100%, including detailed notes on width/height sizing and palette options, so the schema carries the parameter burden. The description only marginally extends this by tying the 'png' format value to the temp-file side effect. Baseline 3 is appropriate.

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

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

States a specific verb (Render) and resource (DGMO markup) plus the output formats (SVG or PNG), so an agent knows exactly what the tool produces. It does not, however, differentiate itself from close siblings like preview_diagram or validate_diagram, which an agent might reasonably confuse it with.

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 only routing guidance is 'For DGMO syntax call get_language_reference', which points to a dependency rather than explaining when to pick this tool over preview_diagram or validate_diagram. Usage context is implied by the name but never stated.

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 annotations (readOnly/idempotent/non-destructive/closed-world), it discloses that the source is compressed into the URL fragment, nothing is uploaded, the link works for anyone, the return is plain text, and the failure mode reports both sizes. That is substantial behavioral context the annotations alone do not 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?

Three tightly packed sentences with no filler; the purpose, behavior, failure mode, and prerequisite are all front-loaded in a logical order.

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 still covers the return value ('returns the URL as text'), the error behavior, and the validation prerequisite, so an agent has everything needed to call it correctly.

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

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

Only one parameter (dgmo), and schema description coverage is 100%, so the schema already documents it. The description refers to 'the source'/'compressed source' but adds no format, encoding, or size-limit specifics beyond what the schema and error text imply — baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Generate a shareable diagrammo.app URL for a DGMO diagram.' This is clearly distinct from siblings like validate_diagram, render_diagram, and open_in_app, and the agent can identify the operation without opening the schema.

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

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

Explicitly names alternatives and the conditions selecting them: on size-limit errors, 'split or simplify the diagram, or use open_in_app / render_diagram instead,' and it directs the agent to 'call validate_diagram first' since the source is not validated here. This is genuine when/when-not 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?

With no annotations present, the description carries the full behavioral burden and does so well: it discloses the hidden side effect of appending the language-reference section, defines both possible return shapes including the '⚠️ ASK THE USER' outcome, and prescribes agent behavior on that outcome. This is well beyond what structured fields 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?

Content is front-loaded with the core purpose and the when-to-call rule, and the result-shape and ASK-THE-USER guidance are placed last where they belong. Slightly dense, but essentially every sentence carries decision-relevant 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?

There is no output schema, and the description compensates by spelling out the two return shapes and the required agent action for each. Combined with the explicit when/when-not guidance, an agent has everything needed to call and act on 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 description coverage is 100% for the single 'prompt' parameter, so the schema already documents it as the user's plain-English diagram request. The description adds no syntax, format, or length guidance beyond that, so baseline 3 applies.

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

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

The description states a specific verb and resource (suggest the best DGMO chart type) and scopes it to a plain-English diagram request. It clearly distinguishes itself from siblings like get_language_reference and list_chart_types by describing what it returns and why a separate reference call is unnecessary.

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?

It gives an explicit call-first rule for new diagrams, states the negative case (not needed when editing an existing diagram, whose first line declares its type), and names the alternative it subsumes (get_language_reference). It also tells the agent what to do on an ambiguous result: present candidates and wait for the user.

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 exist, so the description bears full responsibility. It discloses that the tool does not render and returns structured errors/warnings, and that it is faster. While it doesn't discuss auth or rate limits, these are less critical for a validation tool. A minor omission: it could explicitly state that it does not modify data, but 'without rendering' implies no side effects.

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, front-loads the purpose, and contains no extraneous information. Every sentence adds value.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description fully covers what the tool does, when to use it, and what it returns. No gaps remain.

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

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

Schema description coverage is 100%: the parameter 'dgmo' is described as 'DGMO diagram markup to validate'. The description adds no additional parameter-level detail beyond the schema. Per guidelines, baseline is 3 when schema coverage is high.

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

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

The description clearly states the verb 'validate' and the resource 'DGMO markup', and specifies it returns structured parse errors and warnings. It effectively distinguishes from sibling tools like render_diagram by noting it does not render.

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 explicitly says to use this tool to check syntax before rendering and mentions it's much faster than render_diagram. This provides clear when-to-use guidance and contrasts with an alternative.

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