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

No annotations exist, so the description carries full burden; it discloses the return type (Markdown) and the lifecycle trait 'A reference stays valid for the rest of the conversation', which prevents redundant re-fetches. It stops short of stating read-only status or the reference's size, but the caching/timing guidance is genuine behavioral value beyond structured fields.

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-loads the purpose, then segments cleanly per format value with a closing lifecycle note. Dense but every clause (content list, trigger condition, validity) carries information; no wasted sentences.

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 single-parameter lookup tool with no output schema, the description fully explains what is returned (Markdown reference), what each format contains, when to invoke it, and how long it stays valid. Nothing needed 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?

Schema coverage is 100%, so the enum values are already documented as 'xml'/'mermaid'. The description adds meaning beyond the schema by explaining what each value's content covers and when each is warranted, exceeding the terse 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?

States a specific verb+resource ('Returns a full draw.io diagram generation reference as Markdown') and immediately distinguishes itself from siblings by naming open_drawio_xml and open_drawio_mermaid as the tools this reference supplements. An agent can tell this is a documentation-lookup tool, not a diagram generator.

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 conditions per format: 'call it once before the first Mermaid diagram in a conversation' for mermaid, and 'only needed when a diagram uses those' for xml, listing the exact features (layers, tables, grids, etc.) that trigger it. The exclusions are as clear as the inclusions.

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 carries the full burden, and it does disclose a genuine behavioral trait: the page is decompressed first if the file stores it compressed. It also specifies the return format (raw mxGraphModel XML). It omits error behavior (missing page index, unreadable file) and any permission considerations, keeping it 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?

Two sentences, zero filler. The what-and-returns statement is front-loaded and the prerequisite follows naturally, with no redundant restatement of the tool name or schema.

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 must describe the return value, and it does ('raw mxGraphModel XML'), along with the decompression nuance and the list_pages prerequisite. For a two-parameter read tool this is close to complete; only failure modes are 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 both parameters (page, path) are already fully documented in the schema, including the index/name/id options and the .drawio/.xml extension rule. The description adds no syntax or format detail beyond that, which is the correct baseline-3 outcome.

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 (reads one page/diagram from a local .drawio file) plus the exact return shape (raw mxGraphModel XML). It implicitly narrows scope against whole-file siblings like open_drawio_xml by stressing 'one page', but never names those alternatives, so differentiation is partial.

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 an explicit prerequisite workflow: 'Use list_pages first to find the index, name, or id of the page you need.' That tells the agent when this tool is callable and what must precede it, though it offers no when-not guidance or comparison to the other open_drawio_* readers.

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 and does disclose real behavior: it does not load full page content, and it returns index, id, name, and approximate stored size. It stops short of stating failure behavior for bad paths or how 'approximate' size is computed, so it is strong but not exhaustive.

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, each earning its place: purpose, return shape, and sequencing guidance. The ordering is front-loaded with the purpose statement.

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, and the description compensates by enumerating the returned fields (index, id, name, approximate size) plus the lightweight-loading guarantee. For a one-parameter read tool, nothing an agent needs 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?

Schema coverage is 100% and the single path parameter is fully documented in the schema, so the baseline is 3. The description adds no format or constraint 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?

Specific verb+resource ('Lists the pages (diagrams) in a local .drawio file') with an explicit scope qualifier ('without loading full page content'). It is clearly distinguishable from siblings get_page/set_page, which it names directly.

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 states when to call it ('first on large multi-page files') and what it precedes ('before get_page/set_page'), with the rationale ('so only the page you actually need gets loaded into context'). This routes the agent correctly relative to the sibling tools.

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 are provided, so the description carries full burden. It only states 'Opens the draw.io editor' without disclosing side effects, permissions, rate limits, or whether it is read-only or mutating. The lightbox parameter hints at read-only but is not explained.

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 sentences with no wasted words. First sentence states purpose, second adds format context. Front-loaded with primary action.

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 no output schema and no annotations, the description could elaborate on return behavior or errors. It adequately covers purpose and parameter context but lacks guidance on what the tool returns or how it behaves.

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% (all 3 parameters have descriptions). The description adds value by referencing 'draw.io's CSV import specification' for the content parameter, providing context beyond the schema. The lightbox and dark parameters are standard.

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 'Opens the draw.io editor with a diagram generated from CSV data', providing a specific verb and resource. It also distinguishes from siblings like open_drawio_xml or open_drawio_mermaid by specifying CSV data.

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

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

The description implies use for tabular data via CSV, saying 'allows creating org charts, flowcharts, and other diagrams from tabular data'. This gives context but does not explicitly mention when to use or avoid compared to siblings.

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

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

With no annotations present, the description carries the full burden and does reasonably well: it discloses that the editor opens with an editable diagram, and warns that a misspelled header keyword yields a blank diagram, which is a real failure mode an agent needs. It does not discuss permissions, side effects on existing pages, or whether the edit persists, leaving some behavioral gaps for a mutation-like tool.

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 tight paragraphs, front-loaded with the core purpose and supported types, followed by the reference-call prerequisite. Every sentence is load-bearing, though the '28 in all' enumeration is slightly padded.

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 4-parameter tool with 100% schema coverage and no output schema, the description supplies the missing context an agent needs: the supported type list, the get_drawio_reference prerequisite, and the blank-diagram pitfall. Absence of persistence/authorization details is the only meaningful gap.

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

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

Schema description coverage is 100% and the schema already documents dark, lightbox, and the detailed postLayout heuristics. The description adds only the pointer to get_drawio_reference for header syntax, so per the baseline rule a 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 ('Opens the draw.io editor with a diagram generated from Mermaid.js syntax') and explicitly distinguishes itself from siblings by contrasting the Mermaid input path with the csv/xml alternatives. The enumeration of supported diagram types makes the scope unambiguous.

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?

Clearly positions itself as 'the recommended default for flowcharts, sequence, class, state and ER diagrams...' and gives an explicit prerequisite ('Call get_drawio_reference with format "mermaid" once before your first Mermaid diagram'). It lacks an explicit when-NOT-to-use statement versus open_drawio_xml or open_drawio_csv, which keeps it short of a 5.

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 provided, so the description carries the full burden. It discloses that postLayout and routing are applied server-side before the diagram opens, describes their effects in detail (ELK places vertices and routes edges; libavoid keeps vertex positions and recomputes connectors), and warns never to set both. It does not mention authentication or persistence side effects, but given the tool opens an editor with provided content, the behavioral disclosure is strong.

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

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

The description is long but organized with clear headings and bullet points. Every rule appears necessary for correct XML construction, and purpose/usage are front-loaded. However, some detail might be overwhelming for a tool description and borders on reference material.

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 complex XML content parameter and six parameters with enums, the description provides comprehensive XML rules, usage routing to siblings (open_drawio_mermaid, search_shapes, get_drawio_reference), and behavioral notes. No output schema is needed since it opens an editor. Complete for an agent to invoke correctly.

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

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

Schema descriptions for parameters like `content` are minimal ('draw.io XML content in mxGraphModel format'), while the description provides extensive XML syntax rules (skeleton, vertex, edge, labels, shapes, containers, lanes, etc.) that define what valid content looks like. It also gives usage context for `postLayout` and `routing` beyond the schema's technical descriptions, adding substantial meaning.

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

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

States a specific verb and resource: 'Opens the draw.io editor with a diagram from draw.io XML.' It clearly distinguishes from siblings by saying 'prefer open_drawio_mermaid for flowcharts, sequence, class, ER and the other types Mermaid covers.'

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 states when to use this tool ('custom styling, precise positioning and stencil-based diagrams') and when to use the alternative ('prefer open_drawio_mermaid for...'). Also says when to call search_shapes and get_drawio_reference, and when to use postLayout vs routing (never both).

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 and does well: it discloses coverage (~10,000 stencils, named domains), the fallback behavior to the icon service when stencils are sparse, and that returned style strings can be pasted directly into mxCell style attributes. It omits any mention of rate limits, ordering, or what an empty result looks like, keeping it 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?

Front-loaded with purpose and return shape, then usage constraints, then the downstream tip about style strings. It is fairly dense but every sentence earns its place; the catalog list of domains is slightly listy but useful for routing.

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, and the description compensates by describing return fields and their use. Combined with the explicit usage boundaries and the fallback behavior, an agent has everything needed to decide to call it and to use the results.

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 both query and limit are fully documented in the schema (including the default and max for limit). The description adds no syntax or formatting guidance beyond what the schema already provides, so the 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?

States a specific verb and resource ('Search the draw.io shape library by keywords') and immediately describes what comes back (style strings, dimensions, titles). It clearly carves out a niche distinct from the sibling reference/page tools.

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 says when to use ('ONLY for diagrams that need industry-specific, branded, or pictorial icons') and when not to (flowcharts, UML, ERD, org charts, mind maps, basic-shape requests, or when the user says not to search). It even points to where basic shapes live instead (the XML 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?

With no annotations, the description carries the full burden and does disclose the two behaviors that matter most for a destructive write: the blast radius is limited to one page, and compression state is preserved to match the page's original encoding. That is genuine information beyond the schema. It omits failure/error behavior (missing path, file absent, malformed XML) and whether the operation is reversible, which keeps it out of 5 territory.

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, front-loaded with the operation and its scope, followed by the compression guarantee and the discovery prerequisite. Nothing is repeated from annotations or schema descriptions and 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?

For a three-required-parameter local file mutation with no output schema, the description covers the essential agent-facing facts: what is changed, what is preserved, and how to locate the target. It does not say whether the call reports success or how errors surface, which is a modest gap rather than a blocking one.

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 three parameters are already fully documented, including the accepted identifier forms for 'page' and the 'no <diagram> tags' constraint on 'content'. The description only restates that content is mxGraphModel XML, adding no syntax or edge-case semantics beyond the schema; 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?

States a specific verb and resource - replacing the content of exactly one page (diagram) in a local .drawio file - and immediately bounds the scope with 'leaving every other page in the file untouched.' An agent can distinguish this from read-oriented siblings like get_page and list_pages 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?

'Use list_pages/get_page first to find the target page' names the prerequisite tools and the intended workflow order, which is exactly the routing knowledge an agent lacks otherwise. It stops short of stating when not to use this tool (e.g. creating a new page vs. editing an existing one), so it falls just below the explicit when/when-not bar.

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