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

Annotations declare destructiveHint=false and openWorldHint=false, so safety is partly covered. The description adds real behavioral context beyond that: it preserves existing pages and unsaved changes, auto-adds root cells '0' and '1', and returns id/name/index. It does not discuss error cases (e.g. duplicate id), 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?

Front-loaded with purpose and sibling differentiation, then cleanly organized into Inputs and Returns sections. Every sentence carries information (defaults, id generation, root-cell behavior, return payload) with no 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, and the description compensates by stating the return payload ('the new page's id, name, and index') and the follow-up workflow ('so the caller can immediately target it with edit_diagram'). For a 3-param, zero-required mutation tool, an agent has everything needed to invoke 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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the default naming formula ('Page-N where N = existing-page-count + 1') and the fact that root cells '0' and '1' are injected when xml is supplied. That extra semantic detail raises it above baseline.

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 ('Append a new page (tab) to the current diagram') with a precise non-destructive scope ('WITHOUT touching existing pages or unsaved user changes'). It explicitly distinguishes itself from the sibling create_new_diagram, so an agent can choose between them without opening either 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 an explicit when-to-use trigger ('when the user wants "another diagram alongside" — e.g. "add a CNN page"') and names the alternative (create_new_diagram) along with the condition that selects it ('which wipes everything'). Nothing is left 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?

With only openWorldHint=false declared, the description carries the behavioral burden and does so richly: it discloses that the operation is destructive to the whole document and to unsaved changes, that the prior state survives in History, that it is recoverable, and that clearing the canvas is done by sending only the two root cells. It adds server-side transformations (auto-added <mxfile>/<root>, html=1 and whiteSpace=wrap) that the agent cannot infer from annotations.

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

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

Long but front-loaded: the destructive scope and the sibling alternatives occupy the first sentence, before any XML detail. The 'Accepted xml' and 'Rules' groupings make the density navigable, and every sentence carries an actionable constraint rather than 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 high-complexity XML-injection tool with no output schema, the description supplies the accepted input grammar, coordinate bounds (x 0–800, y 0–600), cell nesting rules, and what the screenshot flag returns. Nothing an agent needs to call this correctly and safely appears to be 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 description coverage is 100%, so the baseline is 3. The description clearly exceeds it by enumerating the three accepted XML input forms with a concrete example, the required root-cell preamble, the mxStyle definition pattern, and per-page id/parent constraints. The screenshot timing and cost ('adds 2 to 10 s') also extend the schema's terse note.

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 ('Create a NEW diagram') and immediately qualifies scope: it REPLACES the whole document, every page and unsaved changes. It names the two sibling alternatives (add_page, edit_diagram) so the agent can differentiate 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?

Explicit routing: 'To add a tab use add_page; to change cells use edit_diagram.' It also states prerequisites and sequencing (call get_shape_library before icon shapes, follow the guide from start_session, pass screenshot: true on the last call of a complex diagram). Both when-to-use and when-not-to-use are covered.

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

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

Annotations only declare openWorldHint=false, so the description carries the behavioral burden. It usefully discloses the guard rail ('refuses to delete the last remaining page'), which the annotations do not cover, but says nothing about irreversibility, confirmation, or what happens to page contents — significant gaps for a destructive operation.

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 action, then the requirement, then the constraint. No wasted text.

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

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

For a simple no-output-schema delete tool, the description covers targeting and the key refusal condition. It leaves out what the call returns and whether deletion is reversible, which for a destructive tool leaves a small 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%, so precedence rules are already documented in the schema (baseline 3). The description adds one thing the schema lacks — that at least one identifier is required (required parameters = 0 in the schema) — which is a genuine value-add.

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 ('Delete a page (tab) from the current diagram') and clarifies the resource is a tab, which distinguishes it from siblings like rename_page, add_page and list_pages.

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 clear operating conditions: at least one of page_id/page_name/page_index is required, and deletion is refused when only one page remains. It does not explicitly route the agent among alternatives (rename_page, add_page), but the preconditions are stated precisely.

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 provide only openWorldHint=false, so the description carries the burden and does so well: all-or-nothing transaction semantics, freshness detection against browser edits, the fact that a rejected call returns the current page XML, and the 2-10s latency plus preview-tab requirement for screenshots.

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 one-line purpose, then organized into short labeled blocks (all-or-nothing, freshness, multi-page, operations, examples). The length is justified by the semantic complexity of batch cell editing, and the JSON examples remove ambiguity without padding.

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 explaining the failure return (current XML for retry) and the optional screenshot output. For a mutation tool with openWorldHint=false, an agent has everything needed to call and recover from failures.

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

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

Schema coverage is 100%, so the schema already documents all five parameters including page precedence. The description still adds value beyond it: add requires one cell per operation, delete cascades to children and edges, and new_xml requires escaped quotes and compact mxCell form.

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 ('Edit a specific page in the current diagram') and names the exact operations (update/add/delete cells). It is clearly separable from read-side siblings like get_diagram, list_pages, and screenshot_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?

Explicitly states when get_diagram is needed ('only when you don't know the current diagram content') and when it is NOT needed ('You do NOT need to call get_diagram before every edit'), with the reasoning (rejected calls change nothing). It also routes multi-page discovery to list_pages.

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

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

Annotations only supply openWorldHint=false, so the description carries the behavioral burden and does so well: 20 px margin, white vs transparent PNG background, the exact multi-page semantics per format, and the user-visible flicker side effect of temporarily loading a page for SVG capture. These are non-obvious consequences an agent could not infer from the schema.

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 purpose in one sentence, then carefully sectioned into format behavior and a labelled 'Multi-page behaviour' bullet list. The length is justified by the genuine combinatorial complexity of format x page-selector; nothing reads as 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, and the description never states what the tool returns or whether it overwrites an existing file at the given path. Given the moderate complexity and otherwise thorough coverage of format and page semantics, this is a narrow but real 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 already 100%, so the baseline is 3. The description goes beyond it by explaining that format defaults to drawio when undetectable and, more importantly, by mapping page-selector combinations to concrete output behavior (full mxfile vs single-page mxfile vs active page). It does not restate the page_id > page_name > page_index precedence, which the schema already covers.

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?

Opens with a specific verb+resource ('Export the current diagram to a file') and enumerates the exact supported output formats (.drawio, .png, .svg, .drawio.svg), so the agent knows precisely what artifact this produces. It is readily distinguishable from read-oriented siblings like get_diagram, though it never explicitly contrasts itself with screenshot_diagram, which is the nearest alternative.

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

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

Gives clear selection logic for the format parameter (auto-detected from extension or specified explicitly) and a detailed decision matrix for when a page selector is used versus omitted. It stops short of naming when to prefer this tool over screenshot_diagram or get_diagram, so the sibling routing is left implicit.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious behavior — that it re-fetches from the browser so user's manual edits are included — plus what is actually returned (full <mxfile> by default vs. a one-page wrapper holding the page's <mxGraphModel>). It stops short of stating size/latency characteristics, so not 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 the core action, followed by the when-to-use clause, then return-shape detail. Three sentences, each carrying distinct information, with no filler or restatement of the tool name.

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 and only three optional params, the description carries the necessary burden and does so: it tells the agent what is returned in both default and page-scoped modes and warns that content may differ from conversation state. 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 baseline is 3 and the schema already documents precedence among page_id/page_name/page_index. The description still adds value the schema does not: it explains the output-shape consequence of supplying a page selector (single page embedded in a one-page <mxfile>), which is semantic behavior rather than a restatement of the property 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?

States a specific verb+resource ("Get the current diagram XML") and immediately qualifies what "current" means — a live fetch from the browser including manual edits. This distinguishes it from load_diagram, list_saved_diagrams, and edit_diagram without the agent needing to open 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?

Explicitly names the triggering conditions: when the current diagram content (cell IDs, pages, structure) is unknown, before editing a diagram not created in this conversation, or after edit_diagram was rejected because the user changed things in the browser. This is a textbook when-to-use clause that routes the agent away from stale-state assumptions.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the guide is normally supplied by start_session, and the output is scoped when a topic is given. It stops short of describing response size or format details, keeping it at a 4 rather than 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 tightly written sentences with no filler. The core purpose and the redirect to start_session come first, with the optional topic behavior last, which matches its lower priority.

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 read-only, zero-required-parameter tool with no output schema, the description covers what the guide contains and when the cached copy obviates the call. The only minor gap is that it does not characterize the size or structure of the returned XML, though the topic enumeration partially covers this.

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 single enum parameter is fully documented in the schema, so the baseline is 3. The description restates that topic yields a short XML reference for tables, layers or groups, which mirrors the enum values without adding syntax or format detail beyond it.

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 ('Return the drawing guide') and enumerates the guide's contents (XML format, layout, edge routing, style and editing rules). The optional topic variant is also distinguished, so the agent can tell it apart from sibling tools like start_session or get_shape_library.

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 when-to-use condition ('call this only if the guide is no longer in your context') and names the alternative path (start_session already returns it). The conditional topic usage is also explained, so no inference is required.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the empty-selection case ("Says when nothing is selected") and the preview-tab prerequisite. It stops short of describing the exact return envelope, but the empty-state and dependency disclosures are substantive.

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 return payload and then the trigger, prerequisite, and follow-up in three tight sentences with no filler. The middle enumeration of edge/shape fields reads as a run-on list, slightly hurting scannability, but every clause carries 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 present, the description correctly carries the burden of explaining what comes back, including the empty-selection case, and it flags the preview-tab dependency. Nothing an agent needs in order to call this correctly and interpret the result 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description's payload enumeration is about return values rather than inputs, and no input semantics are needed.

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 (return the cells the user has selected in the preview) and enumerates the payload: ids/labels, edge source and target ids, shape position and size, and page. This distinguishes it clearly from siblings like get_diagram or list_pages, which return whole-document state rather than the current selection.

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

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

Gives explicit trigger conditions with example user phrasings ("this box", "these arrows", "the selected shapes") and names the follow-up tool (edit_diagram) for acting on the ids. It also states the prerequisite that the preview tab must be open, so an agent knows when the call will fail.

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 and openWorldHint=false, so safety is covered; the description adds the return content (style syntax and shape names) and the behavioral rule that names must be exact and never guessed. It does not mention caching, rate limits, or whether results vary by version, but the added context is substantial.

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 critical instruction is front-loaded in the first sentence, and the library list is compactly grouped by category rather than prose. Every line is load-bearing reference data with no 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 carries the burden of explaining what comes back ('style syntax and shape names'), which it does. Combined with the enumerated library values and the timing instruction, an agent has everything needed to invoke this 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?

With 100% schema coverage the baseline is 3, but the description goes well beyond the schema's single example by enumerating every valid library value grouped by domain (aws4, azure2, cisco19, bpmn, etc.). Since the schema has no enum, this list is the only authoritative source of accepted inputs and directly prevents invalid calls.

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 style syntax and shape names of a draw.io icon library') and makes clear it is a lookup/discovery tool, not a drawing tool. An agent can distinguish it from siblings like get_drawing_guide or create_new_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 an explicit trigger and ordering constraint: 'Call this BEFORE drawing with cloud, network or other icon shapes, and use the exact names it returns; never guess them.' That is a clear when-to-use plus an anti-pattern to avoid, though it does not name an alternative tool for non-icon shapes or say when this call is unnecessary.

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 this is a safe, non-open-world read (readOnlyHint=true, openWorldHint=false). The description adds value beyond that by enumerating the exact return shape, including the 0-based index convention and cell count, which preempts off-by-one errors in downstream edit_diagram calls. It stops short of stating scope caveats (e.g., whether hidden or master pages are included).

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 sentences: the first states scope and output fields, the second gives the routing advice. Everything is front-loaded and every clause earns its place by either defining the resource or guiding downstream tool selection.

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 input parameters, no output schema, and annotations carrying the safety profile, the description is complete: it names the resource, enumerates the four returned fields, and tells the agent how the result feeds six sibling tools. Nothing an agent needs to call this 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?

Zero parameters, so the baseline is 4, and the description reinforces this by implying the tool is scoped implicitly to 'the current diagram' with no arguments. That scoping statement is useful context for an agent that might otherwise expect a diagram id argument.

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 ('List every page (tab) in the current diagram') and preempts the obvious terminology ambiguity by equating page with tab. The output field list (id, name, 0-based index, cell count) makes the resource unambiguous and distinguishes it from sibling listing tools like list_saved_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?

Provides explicit when-to-use guidance ('before targeting one with...') and names six specific downstream tools that consume the returned page identity. This is exactly the routing an agent needs to sequence page discovery before page-level mutations or exports.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: results are derived from auto-save files, are ordered newest first, and carry their pages. It does not disclose whether there is a cap or pagination, which keeps it at 4 rather than 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, no filler, and the identifying facts (auto-save, newest first, with pages) come before the continuation advice. Every clause carries information an agent needs.

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 stating what each entry contains and its ordering, and it explains how to act on the results. It omits anything about result volume or truncation, which is a minor remaining gap for a list tool.

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

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

The tool takes zero parameters, so the baseline is 4. The only parameter-like detail mentioned (session_id=<id>) belongs to start_session, and the description correctly frames it as the continuation mechanism rather than an argument to this call.

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 (List) + resource (saved diagrams), plus the qualifying scope that this is about auto-save files from earlier sessions, not live diagrams. It also names the ordering (newest first) and the returned unit (with their pages), which cleanly separates it from list_pages and get_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 routes the agent onward with concrete alternatives: continue a listed item via start_session session_id=<id>, or reach the same file through load_diagram. That is explicit next-step guidance with a named parameter. It stops short of stating when NOT to use this tool (e.g. to find the currently open diagram), so it falls just under 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?

Annotations only declare openWorldHint=false, so the description carries the behavioral burden and does so well: it discloses the whole-diagram replacement, the accepted formats (plain XML, compressed save format, .drawio.svg) and explicitly the rejected ones (.png, plain .svg), plus the cell-ID visibility trap after loading. These are exactly the traits an agent needs and none are in the annotations.

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

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

Front-loads the replacement warning and keeps every sentence functional, but the middle paragraph is dense with parenthetical asides that make it heavier than needed for the payoff. No sentence is pure filler, so it stops short of a 5.

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 covers inputs, format limits, and the required follow-up calls well. It does not say what a successful load returns or how to inspect resulting pages beyond pointing at get_diagram, which is a minor gap for a session-mutating loader.

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% (baseline 3), and the description goes beyond it by giving a selection rule between the two mutually exclusive sources, noting compressed-format support for both, and warning that 'path' resolves against the server's working directory, which may not be the project directory. That last note is a real semantic addition the schema only hints at.

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 ('Load a .drawio diagram into the current session') and immediately scopes it with the destructive side effect 'REPLACING the entire diagram (all pages)'. It also distinguishes itself from the sibling create_new_diagram by saying the caller does not need to pass XML through that tool.

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 the two mutually exclusive input modes, when to choose each ('path' when the server should read from disk, 'xml' when content is already in hand), and the intended edit workflow (load here, edit_diagram, then export_diagram to the same path). It adds a concrete precondition: call get_diagram before edit_diagram after a path load, but not for self-supplied plain XML.

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 openWorldHint=false and destructiveHint=false, so the agent knows this touches only local diagram state and is non-destructive; the description is consistent with that. It adds the effect (new_name becomes the visible tab label), but says nothing about failure behavior when no page matches or whether the change is persisted/undoable.

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 purpose, then the identification constraint, then the effect. Every sentence carries information and there is no 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 simple, single-target mutation with no output schema and fully documented parameters, the description covers purpose, target selection, and outcome. It omits only edge cases (page not found, rename of the active tab), which are minor at this 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% and the schema details precedence rules, so baseline is 3. The description contributes genuine semantics the schema does not encode: the schema only marks new_name as required, while the description supplies the anyOf-style constraint that at least one page identifier must be given.

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 ("Rename an existing page (tab)") and clarifies the domain meaning of "page" as an editor tab. It is self-evidently distinct from add_page/delete_page/list_pages, but it never names or contrasts an alternative sibling, so it stops short of full differentiation.

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

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

The sentence "At least one of page_id / page_name / page_index is required" gives a real precondition for invocation, which is useful. However, there is no guidance on when to prefer this over add_page/delete_page or how to resolve a missing page, leaving usage largely implied.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false. The description adds non-obvious behavior beyond this: the current canvas is preserved in History so the restore is itself reversible, and the steps_back redo semantics. This is exactly the kind of context annotations do not provide.

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

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

Two tight sentences, front-loaded with what the tool does, then when to use it. No filler or redundancy.

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

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

Complete enough for a single-parameter tool: purpose, reversibility, and trigger conditions are all covered. A note on failure when no history exists would push it to a 5, but this is solid.

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, but the description independently clarifies the History/redo interaction that animates steps_back, adding real meaning. It does not restate the numbering definition verbatim, so it lands above baseline.

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 concrete verb+resource ('put an earlier version of the diagram from History back on the canvas') and frames it as an undo. It is clearly distinguishable from siblings like edit_diagram, load_diagram, or delete_page.

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 the triggering conditions: 'Use it when the user asks to undo, revert or go back.' This is direct when-to-use guidance with clear invocation cues.

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

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

Annotations only cover the safety profile (readOnly, not open-world), so the description carries the rest and does so well: it discloses the prerequisite ('Needs the preview tab to be open') and that a page selector renders a non-visible page 'without changing what the user sees'. The one incompletely covered trait is whether the call has any side effect on the preview state.

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 ordered by importance: action, when to call, then page-selection semantics and prerequisite. 'so you can see your own result' is mildly redundant but justifies the tool's existence rather than padding.

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 no-output-schema tool it covers the essentials: what is returned (a PNG image), the prerequisite tab state, and the page targeting behavior. Nothing critical is missing, though a note on what happens if the preview tab is not open would fully close the loop.

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 page_id/page_name/page_index and their precedence are already fully documented in the schema. The description only adds the behavioral distinction between supplying vs omitting a selector, not new syntax or format detail, which is the expected baseline.

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 the diagram ... return it as a PNG image') plus the intent ('so you can see your own result'). It does not distinguish itself from the sibling export_diagram, which likely overlaps in producing an image, so an agent must still infer which one to use.

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 says when to call it ('once after drawing or heavily editing a complex diagram, then fix overlaps and edges that cross shapes') and implies not to call it repeatedly. It never names the alternative (export_diagram) or states when not to use it, so the routing guidance is contextual rather than explicit.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false, so the description usefully adds real behavioral context: it spins up an embedded server, opens a browser window with draw.io, streams live diagram updates, and returns a drawing guide to follow. It omits lifecycle details (does it block? how to stop the server? what if a browser can't be opened), which keeps it from 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?

Four short sentences, front-loaded with the primary action and the mode branch, and each sentence carries information. There is mild redundancy in restating the browser preview three times ('open the browser', 'opens a browser window', 'browser will show diagram updates').

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 helpfully notes the result includes the drawing guide, and it covers the side effects of a 1-param tool. Remaining gaps are minor lifecycle questions rather than anything blocking a correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents session_id with its pattern and provenance. The description's 'or continue a saved one with session_id' restates rather than extends that meaning, making the baseline 3 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 states a specific verb and resource ('Start a new diagram session... and open the browser for real-time preview') and cleanly splits the two modes (new vs. continue via session_id). It does not, however, distinguish itself from plausible siblings like create_new_diagram or load_diagram, whose relationship to a 'session' an agent must infer.

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 a clear selection rule for its only parameter fork: pass session_id to continue a saved diagram, omit it to start fresh, and the schema notes where session_ids come from (list_saved_diagrams). No explicit exclusions or named alternatives are given, so it stops short of full when/when-not guidance.

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