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 declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, lowering the bar. The description adds a genuinely useful side-effect disclosure ('Opens in browser by default') that the annotations do not convey, though it omits where the report file is written or returned.

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 core capability, then the behavioral default, then the prerequisite pointer. Zero 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?

There is no output schema, so the description should carry the return-value burden, but it only says the report 'opens in browser by default'. For a tool that produces a file artifact, the missing output location/path leaves the agent unable to report where the report lives.

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 each parameter is already documented, giving a baseline of 3. The description lightly reinforces 'source blocks' (include_source) and browser opening (open) but adds no syntax or precedence detail beyond the schema, which already explains palette behavior better.

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 polished HTML report') and enumerates the distinguishing output features (multiple DGMO diagrams, table of contents, optional source blocks). This clearly separates it from single-diagram siblings like render_diagram and preview_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?

Provides one explicit routing pointer ('For DGMO syntax call get_language_reference') that resolves the likely prerequisite. However, it does not state when to choose this over render_diagram or preview_diagram, so usage context is clear but incomplete.

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 declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so safety is partly covered. The description usefully adds that the tool opens a browser window (an observable side effect consistent with openWorldHint) and that source display is optional, which is real context. It stops short of saying whether a browser window is spawned on every call, whether the page persists, or any auth/environment requirements.

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, purpose front-loaded, with no padding. The middle sentence lists features that are largely already enumerated in the schema, which is mild redundancy, so it is efficient but not flawless.

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 preview tool with no output schema and full schema coverage, the description covers what the tool does and the browser-based output. It leaves unaddressed whether diagrams render inline, how multiple diagrams are laid out, and how the browser preview is surfaced to the agent, so it is nearly but not fully 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 schema already documents theme, palette, diagrams, include_source and the nested dgmo/title fields, making the baseline a 3. The description's mention of 'theme toggle and optional source display' loosely maps to two parameters but adds no formatting or override semantics beyond what the schema states; palette is not mentioned at all.

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?

Names a specific verb+resource ('Render one or more DGMO diagrams and open an HTML preview in the browser'), which is concrete and actionable. It does not, however, distinguish itself from the sibling render_diagram, which an agent must infer from the 'HTML preview' phrasing. Without that explicit sibling contrast, it stops short of a 5.

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 at a supporting tool rather than saying when to choose preview_diagram over render_diagram or share_diagram. Usage is only implied by the phrase 'preview'. No when-not conditions or alternatives are 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds value beyond them by disclosing the return form (SVG text vs base64 PNG) and the non-obvious png side effect of writing a temp file and returning its path. It does not mention rate limits or error behavior, so it stops short of a 5.

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 front-loaded sentences with no filler, leading with what it renders and what it returns. The syntax pointer is duplicated verbatim in the schema's dgmo description, which is a minor redundancy rather than a flaw.

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 compensates by explaining exactly what comes back (SVG text or base64 PNG, plus a temp path for png). Combined with the fully documented input schema, an agent has enough to call it correctly, though sibling routing remains unaddressed.

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 width/height/palette semantics are already richly documented in the schema (including the content-sizing caveats). The description only adds meaning for the format parameter via its png temp-file note; theme and palette get nothing extra. Baseline 3 is appropriate when the schema carries the 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?

States a specific verb and resource ('Render DGMO markup to SVG or PNG') plus the exact return forms, so the agent knows precisely what the tool produces. It differentiates from get_language_reference for syntax help, but does not distinguish itself from siblings like preview_diagram, validate_diagram, or share_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?

It tells the agent the practical route for syntax ('call get_language_reference') and when a side effect occurs (png also saves a temp file), which is useful context. However, it never states when to choose this over preview_diagram or validate_diagram, leaving the main sibling-selection decision to inference.

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.