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, idempotentHint, and openWorldHint. The description adds valuable behavior beyond annotations: API key requirement in the server environment, 401/403 and 404 error conditions, case-insensitive title matching, and the returned JSON shape.

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 dense passage with no waste, front-loading the core action, lookup modes, return shape, auth, and error behavior. Every sentence carries operational 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 naming the returned JSON fields. It also covers authentication, error cases, matching behavior, and where to look when nothing matches.

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 adds meaningful semantics beyond the schema: title matching is case-insensitive, and it frames lookup as by id or by title in a folder. It could have tied `space_id` more explicitly to the API key, but it is still helpful.

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: "Read a diagram from a Diagrammo Cloud space, by `id` or by `title` in `folder`." It clearly distinguishes this lookup tool from write-oriented siblings such as put_space_diagram and from discovery via list_space_diagrams.

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

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

It gives clear selection logic between `id` and `title` and points to list_space_diagrams when the caller does not know what exists. It does not explicitly spell out when-not-to-use this tool, but the retrieval context is 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 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 already declare readOnly/idempotent/non-destructive, and the description adds meaningful context beyond that: the exact JSON return shape, the sort order (folder then title), and the auth requirement (DGMO_API_KEY in the server environment).

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 tight sentences: purpose first, then return shape/sorting, then auth requirement. No wasted words.

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

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

Even without an output schema, the description fully specifies the return structure and ordering; combined with annotations covering the safety profile, 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?

Schema coverage is 100% and the single parameter is already documented in the schema, so the baseline is 3. The description reinforces that the key is space-scoped but adds no new syntax or format detail.

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

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

States a specific verb (List), resource (diagrams), and scope (every diagram in a Diagrammo Cloud space), which clearly distinguishes it from the singular get_space_diagram sibling.

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 use case (enumerating all diagrams in a space) is implied by the description and contrasted against sibling get_space_diagram by plurality, but there is no explicit when-to-use/when-not guidance or named alternative.

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 behavior beyond the annotations: macOS-only operation, browser-preview fallback, autosaving in-app edits back to the exact `filePath`, and deep-link copy creation when `filePath` is omitted. These details are consistent with `readOnlyHint=false`, `destructiveHint=false`, and `openWorldHint=true`.

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 front-loaded with the core action and platform, then explains the saved-file path and ephemeral alternative. It is dense but every sentence carries useful operational 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?

It covers the main behavior, platform constraint, fallback, and both parameter paths thoroughly. Since there is no output schema, it could have said more about the tool's return value or failure behavior when the app is unavailable, but the core invocation guidance 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics for `filePath`: it opens that exact saved file, enables autosave back to it, and is the preferred path, while omission creates an ephemeral copy. The `dgmo` parameter is not elaborated beyond the schema description.

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: opening a DGMO diagram in the Diagrammo desktop app. It also distinguishes the app path from browser preview and from ephemeral deep-link opening, so an agent can tell what this tool is for 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?

It gives clear usage conditions: pass `filePath` to open a saved .dgmo source as the preferred path when the app is installed, and omit `filePath` for an ephemeral diagram. It also mentions fallback to browser preview, but it does not explicitly name sibling alternatives such as `check_app_installed` or `preview_diagram`.

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?

Adds substantial context beyond the annotations: idempotent no-op on identical source, created-private default, the exact return envelope, an auth requirement (DGMO_API_KEY in the server environment), and a mapped error-code table with a retry instruction for 409. That is exactly the extra behavioral detail 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?

Front-loaded with the core action, then semantics, return shape, auth, and errors in descending priority. Dense but nearly every clause carries information; the error-code enumeration is the one slightly chunky element.

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, yet the description spells out the return object fields (action, id, title, folder, version) and the failure modes. Combined with 100% schema coverage, an agent has everything needed to call and interpret the result 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 still adds meaning by explaining that (folder, title) is the lookup key and that the key/space relationship is loose ('the space the API key belongs to' is echoed in the schema). It stops short of describing the dgmo payload's format beyond 'markup'.

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 ('Write a DGMO diagram into a Diagrammo Cloud space') plus the exact addressing scheme (folder + title) and the upsert semantics. An agent can distinguish this from get_space_diagram or render_diagram 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 a clear precondition and names the alternative: 'Call validate_diagram first; this does not validate.' It also explains the create-vs-update selection rule, which functions as usage guidance. It stops short of explicitly stating when not to use it (e.g., versus preview or list tools), so it sits just below the top.

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 and non-destructive, so the safety profile is covered. The description does add a genuine side effect the annotations miss: with format=png it writes a temp file and returns its path. It says nothing about size limits (4096 cap) or failure modes, so credit is moderate rather than high.

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?

Four short sentences, front-loaded with the core action and output, then the png caveat, then the syntax escape hatch. Nothing is 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?

With no output schema, the description carries return-value disclosure and does so adequately (SVG text, base64 PNG, temp path). The remaining gaps — width/height interaction and palette precedence — are already fully documented in the schema's own parameter text.

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 bar is baseline 3. The description goes beyond the schema by explaining what the format parameter actually yields (SVG text vs base64 PNG plus a temp-file path), which the schema only labels "Output format".

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

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

States a specific verb and resource (

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 routes the agent to get_language_reference for DGMO syntax and implies usage for producing a final artifact. It gives no guidance about when to prefer preview_diagram over render_diagram, nor any prerequisites beyond the syntax reference.

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.