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

With no annotations to rely on, the description carries the full burden and does so thoroughly: containers are sized around members plus padding, members move with the container, nesting order matters, the master defaults to the first built-in style, and style_shape is needed for recoloring because theme guards are overridden. These are meaningful behavioral details well beyond a simple 'wrap shapes' statement.

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 information-dense but well organized: purpose and use cases first, then behavioral guarantees, then parameter summaries, then a follow-up action. Every sentence earns its place, and the structure makes the tool's key semantics easy to scan.

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 annotations, no output schema, and 5 parameters, the description is nearly complete: it covers behavior, return usage, nesting guidance, and follow-up styling. The main gaps are the optional page and padding_in parameters, which are not explicitly described, reducing full contextual completeness for edge cases.

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 0%, so the description must explain parameters. It clearly explains label, member_ids, and master, and mentions padding conceptually, but it does not explicitly document the page parameter or the padding_in parameter name/default. This is useful compensation but not complete.

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 uses a specific verb and resource: 'Wrap existing shapes in a real Visio container' and gives concrete use contexts (VNets, VPCs, subnets, resource groups, trust zones). It is clear, though it does not explicitly contrast itself with sibling tools such as badge_container or container_members.

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 gives clear when-to-use guidance through the listed use cases and explains the correct nesting order ('create inner containers first, then outer ones'). It also directs the agent to style_shape for recoloring afterward, but it does not explicitly state when not to use this tool or name alternative container-related 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 responsibility for behavioral disclosure. It states the main effect—arranging shapes and re-routing connectors—but does not warn that this may overwrite or destroy manual positioning and routing, nor clarify whether the action is reversible. For a mutating layout operation, this is a meaningful gap.

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 short and front-loaded: purpose first, then a practical usage hint, then a compact note on style values. Each sentence adds value, though the style explanation is slightly cryptic and could have been clearer.

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 four parameters, no annotations, and no output schema, the description is missing important context: how to target a page, what spacing means, whether resize_page changes the canvas, and full style enum semantics. It is adequate as a high-level summary but not sufficient for confident 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 0%, so the description must compensate for all four parameters. It only partially explains the style enum ('flowchart_tb' and the '_lr' suffix) and says nothing about 'page', 'spacing_in', or 'resize_page'. Other enum options like 'radial', 'circular', and 'tree_*' are left unexplained.

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 says exactly what the tool does: 'Run Visio's automatic layout on the page — arranges shapes and re-routes connectors.' This is a specific verb and resource, and it clearly distinguishes the tool from siblings like drop_shape or connect_shapes, which do not perform automatic layout.

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 phrase 'Great after dropping shapes at rough positions' provides clear usage context without explicitly naming alternatives or exclusions. It tells the agent when this tool is appropriate, though it does not mention when not to use it.

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 provided, the description carries the full burden of behavioral disclosure. It explains deterministic placement, automatic container membership, icon resolution order (built-in master then local folder), error-handling behavior, and the return value (shape_id). This is strong transparency for a mutation-style 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?

The description is dense but every sentence adds value: purpose, placement behavior, icon resolution, error guidance, and return value. It is front-loaded with the core purpose and avoids filler or repetition.

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 does well by covering return value, side effects, and resolution behavior. Minor gaps remain around page selection semantics and size_in interpretation, but defaults and enum values in the schema partially cover those.

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 0%, so the description must compensate. It does explain icon resolution and implies container_id through 'container', but it does not explain the page parameter or the meaning/units of size_in, and corner is only indirectly referenced as 'the chosen corner'. Some parameter semantics are left to inference.

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 opens with a specific verb+resource: 'Badge a container (zone) with a small header icon.' It gives concrete examples (VNet, Subnet/Subscription icons) and clarifies this is a container-scoped operation, clearly distinguishing it from siblings like add_container or drop_shape.

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 communicates the intended use case well: badging containers with small header icons, with illustrative examples. It does not explicitly name alternative tools as 'use this instead of X', but the container-specific scope and deterministic placement make the appropriate context 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the connector is glued to both shapes, that Visio auto-picks the best sides, and that connectors re-route when shapes move. It could also mention arrow defaults or page handling, but the core dynamic behavior is well communicated.

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 compact and front-loads the most important behavioral detail before listing arguments. The styling conventions are not fluff; they help an agent choose appropriate values for architecture diagrams. It earns its length, though it could have been slightly tighter.

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 10-parameter tool with no annotations and no output schema, the description is reasonably helpful but incomplete. It covers core behavior and styling semantics, yet it leaves required parameter semantics implicit and does not mention the arrow-related parameters. It is adequate for basic use 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 0%, so the description must add parameter meaning beyond names. It does add meaningful semantics for label, route, line_pattern, line_weight_pt, and line_color, including conventions like dashed lines for control-plane flows. However, it omits the required from_id and to_id parameters, plus page, begin_arrow, and end_arrow, leaving part of the parameter space unexplained.

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 opens with a specific verb and resource: 'Connect two shapes with a dynamic connector glued to both.' This clearly separates it from drawing, styling, or container tools and explains the unique behavior of auto-routing and re-routing.

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 when to use the tool by stating it connects two shapes, but it does not explicitly compare against siblings like drop_shape, style_shape, or add_container. It offers useful architecture-diagram conventions for line patterns and weights, but no direct when-to-use or when-not-to-use guidance.

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 of disclosing behavior. It reveals the mutating nature (add/remove) but does not explain side effects, such as whether duplicate members are handled, what happens if the container does not exist, whether changes are reversible, or whether any permissions are required.

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 well-formed sentence with no filler. It puts the core operation front and center and earns every word.

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 absence of annotations, output schema, and parameter documentation, the description is too thin to fully support correct invocation. It leaves the optional page parameter unexplained and does not cover error cases, idempotency, or what response the caller should expect.

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 0%, so the description must compensate. It loosely maps member_ids to 'shapes' and container_id to 'existing container,' and action to add/remove. However, it does not explain the optional page parameter or clarify the expected format or semantics of the IDs.

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 clear verb-add/remove-with a specific resource (shapes) and target (an existing container). It distinguishes itself from siblings like add_container (which creates a container) and drop_shape (which drops shapes without container context).

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 the tool is for modifying membership of an existing container, which gives some usage context. However, it does not explicitly state when to prefer this tool over alternatives such as add_container, drop_shapes, or badge_container, nor does it mention any prerequisites or exclusions.

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 behavioral burden. It usefully discloses template resolution behavior, including unit suffix handling and blank-drawing default. It does not mention what happens to the currently open document or failure behavior for invalid templates, though the core side effect of creating a new document is clear.

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 compact and front-loaded with the core purpose, followed only by relevant parameter details and examples. Every sentence earns its place 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?

For a low-complexity tool with two optional parameters and no output schema, the description covers the meaningful choices and edge cases well. The only minor gap is the effect on the active document state, which is mostly implied by the act of creating a new document.

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 0%, but the description fully compensates by explaining both parameters: template name vs. absolute path, examples, suffix rules, and measurement's role. This adds substantial meaning beyond the raw schema.

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 action ('Create') on a specific resource ('new drawing document in Visio'). The Args section further clarifies that it produces either a blank or template-based drawing, distinguishing it from sibling tools like open_document and save_document.

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 usage when a new drawing is needed, especially via the 'Omit for a blank drawing' guidance and the template/measurement behavior. However, it never explicitly contrasts with open_document or states when not to use this tool, leaving alternatives 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 no annotations provided, the description bears the full burden of disclosing behavior. It states the destructive action but does not mention permanence, cascade effects on connected shapes, undoability, permissions, or other 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 one short, front-loaded sentence with no filler. Every word carries meaning, and it communicates the essential operation immediately.

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 destructive tool with no annotations, no output schema, and an unexplained optional page parameter, this description is too thin. It covers the core action but omits page semantics, behavioral caveats, and any guidance that would help an agent invoke it confidently in context.

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 0%, so the description must compensate. It clarifies that shape_ids are the identifiers of shapes to delete, but it completely ignores the optional page parameter, leaving its role and relationship to shape_ids undocumented.

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 uses a specific verb (Delete), a clear resource (shapes or connectors), and a precise selection method (by id). This distinguishes it from sibling tools like drop_shapes or update_shape, which imply different operations.

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 gives no guidance about when to use this tool versus alternatives, and names no sibling tools or conditions. An agent can infer deletion intent from the name and description, but there is no explicit 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.

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

With no annotations, the description carries the behavioral burden. It usefully discloses that (x, y) is the shape CENTER, coordinates are in inches, and the origin is bottom-left. It also states the return value, which is helpful for chaining tools. It does not discuss side effects on the existing page, but for a creation/drop tool this is reasonably 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 sentences with no filler. The primary action is front-loaded, followed by the critical coordinate convention and return value. Every clause 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?

The core required parameters are covered, but the description omits five optional parameters and does not reference related tools like find_masters or drop_shapes. With no annotations, no output schema, and 8 parameters, this leaves meaningful gaps for an agent trying to call it correctly in anything beyond the simplest case.

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 0%, so the description must compensate. It explains x and y, but leaves master, stencil, text, width_in, height_in, and page semantically unexplained. An agent can guess some of these from names, but the description adds little beyond the schema for most parameters.

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 names a specific action ('Drop one master onto the page') with a clear object and target. It is distinct from tools like drop_text or create_document, but it does not explicitly differentiate from the sibling drop_shapes beyond the singular 'one master.'

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 usage context is implied: use this tool to place a single master and obtain a shape_id for later operations. However, it does not state when to prefer drop_shape over drop_shapes, nor does it mention that find_masters is the likely way to discover valid master names.

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 provided, the description carries the behavioral disclosure burden. It discloses two important behaviors: the operation runs in a single undo scope, and it returns a shape_id per item in order. This adds meaningful execution context, though it omits possible failure modes or prerequisites like an open document.

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 exactly two sentences, with no filler. The core purpose is front-loaded, followed by high-value execution details. Every sentence 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?

The description covers the essential context: batch behavior, undo scope, and return shape. Given the schema's rich self-descriptions, this is sufficient for an agent to call the tool correctly. Minor gaps remain around the optional 'page' parameter and error behavior, but these are not critical given schema coverage.

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 0%, meaning the description mentions none of the parameters. The description does not compensate for this gap; it says nothing about the shapes array, page parameter, or DropSpec fields. Although the schema itself is well-documented, the description adds no parameter-level 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?

The description states a specific verb ('Drop'), a resource ('masters'), and the batch nature ('many in one call'), which clearly distinguishes this from the sibling tool 'drop_shape'. It also adds a usage preference ('preferred when building a diagram'), making the tool's role 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?

The phrase 'preferred when building a diagram' provides clear context for when this tool should be used. However, it does not explicitly name alternatives or state when NOT to use it, so it falls short of the full 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 are provided, so the description carries the full burden of behavioral disclosure. It reveals that the tool creates a borderless/fill-less label, that (x, y) is the center in inches, that size is estimated when omitted, and that unconnected text is ignored by auto-layout. These are meaningful behaviors beyond the tool name.

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 sentence that front-loads the core purpose and then adds positioning, sizing, and auto-layout behavior without any redundancy. Every clause contributes useful 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?

For a simple creation tool, the description covers the essential behavior: what is created, where it is placed, how sizing works, and how it interacts with auto-layout. It does not describe return values or all styling defaults, but the schema and obvious parameter names reduce the risk of incorrect 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?

With 0% schema description coverage, the description partially compensates by explaining that (x, y) is the center in inches and that size is estimated from text when not supplied. However, most optional parameters such as text_color, font_size_pt, align, bold, and page are left to their schema titles and defaults, so the burden is only partially met.

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 names a specific primitive ('text-only label') and clearly separates it from general shape tools by stating 'no border, no fill' and listing concrete use cases: diagram titles, legends, and callouts. This makes it easy to distinguish from siblings like drop_shape and drop_shapes.

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 gives clear usage context with explicit use cases and notes that auto-layout ignores unconnected text shapes, which helps an agent decide when this tool is appropriate. It does not explicitly name an alternative tool or state a 'use drop_shape instead' condition, so it stops short of full differentiation.

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 provided, the description carries the full burden of behavioral disclosure. It does disclose the key behavior that the image is returned to the agent, and it explains the path default behavior. However, it does not mention whether the operation is read-only, what happens if the page does not exist, or whether a file is also written to disk when path is provided.

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 concise and well-structured. The purpose and usage guidance are front-loaded in the first two sentences, followed by a compact parameter breakdown. No unnecessary words or redundant details are present.

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 tool with two optional parameters and no output schema, the description covers the core behavior, the returned image, parameter defaults, and the intended workflow context. A minor gap is the lack of detail about error behavior or the exact relationship between the output file and the returned image, but overall it is sufficient for an agent 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 description coverage is 0%, so the description must compensate, and it does. It explains both parameters: path is the output .png path with an auto-named temp file fallback, and page defaults to the active page. This fully clarifies the parameter semantics beyond the bare schema.

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 tool exports a page as PNG and returns the image for visual inspection. This distinguishes it from other sibling tools like auto_layout, drop_shape, or get_page_state, which perform different actions. The purpose is specific and actionable.

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 after dropping/connecting/layout operations to verify results and iterate. This gives clear contextual guidance, though it does not mention when not to use it or suggest alternative tools for other export or inspection needs.

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 disclosure burden; it explains what is searched, the 100-item cap, inclusion of local custom icons, and how those hits are labeled. It is read-oriented and lacks side effects, though it does not explicitly describe the full return shape or behavior when no stencils are open.

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 compact sentences, each carrying distinct useful information, with the core search action and key constraint front-loaded. No filler or repetition of the 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?

The tool is simple and the description covers search scope, listing cap, and local-icon behavior, but it omits the effect of the `stencil` parameter and—because no output schema exists—never explicitly states what the returned records look like. An agent could invoke it correctly for a plain search but would be guessing about stencil filtering and return shape.

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 description adds real semantics for `query` (substring matching, omit to list all, cap of 100), but it never mentions the `stencil` parameter, leaving an entire parameter unexplained in both schema and description. Since schema description coverage is 0%, this omission is a significant gap.

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 action ('Search masters') along with the resource ('in the open stencils'), matching key ('name substring'), and the broader listing behavior when query is omitted. The parenthetical '(droppable shapes)' removes ambiguity, and the local-icon inclusion distinguishes it from similar discovery 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?

Gives clear practical context: search within open stencils, use a substring, and omit query to list all results up to 100. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops 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?

With no annotations, the description carries the behavioral burden. 'List' and 'discover' clearly imply a read-only operation, and the description discloses the exact output scope plus a prerequisite (an open document). It does not discuss errors or null-page behavior, but the core behavior is 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 dense sentences with no filler; the output inventory is front-loaded and the call trigger appears in the second sentence. Every word 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?

The description compensates well for the missing output schema by listing return fields and gives a concrete use case. However, the page parameter semantics are unexplained, and there is no note about behavior when the document/page is unavailable—an important gap for an optional-parameter tool with no annotations.

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 schema has 0% description coverage, and the description only refers to 'a page' without explaining the page parameter's expected format, how to identify a page, or what null means. The optional default is not documented in prose, so the agent is left to infer the calling convention.

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 uses a specific verb ('List') and a clear resource ('everything on a page'), then enumerates the exact returned fields: shape ids, master names, positions, sizes, text, connector endpoints, and container membership. This makes it easy to distinguish from sibling tools like find_masters or container_members.

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 explicitly tells the agent when to call this tool: to '(re)discover shape ids, e.g. after open_document.' This provides a clear trigger and prerequisite. It does not mention when not to use it or name alternatives, so it falls short of a full 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?

With no annotations, the description carries the behavioral burden. It discloses that URLs must point to raw image bytes, that HTML pages are rejected with guidance, that x/y define the shape center, that aspect ratio is preserved when one dimension is given, and that shape_id is returned. It does not mention prerequisites such as an open document or behavior with an invalid local path, but the core behavior is well covered.

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 well structured: purpose first, then parameter details, then routing guidance. Every sentence adds useful information, and the formatting makes the source and sizing semantics easy to scan.

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 six parameters, no annotations, and no output schema, the description is close to complete: it covers purpose, use cases, parameter semantics, caveats, and return value. The main gap is the unexplored page parameter, and there is no explicit statement about the document being open or the page context.

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 0%, so the description must compensate. It richly explains source, x/y units and origin, and width/height scaling rules. However, the optional page parameter is not described at all, leaving one of the six parameters undocumented in text.

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 names a specific action and resource: 'Insert an external image ... onto the page as a shape.' It also clarifies the intended niche (custom icons with no Visio master, vendor logos), which distinguishes it from the sibling drop_shape/drop_shapes 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?

Explicit guidance says to prefer built-in masters via drop_shape when Visio has the icon, and to use this tool only for the gaps. It also clarifies when a URL is appropriate versus when the user must download the file first, giving concrete decision rules.

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 behavioral burden. It explains where the folder lives, how paths are resolved, and how labels are derived (file name without extension). It does not specify the return shape or what happens if the folder is missing, but for a read-only listing tool the disclosed behavior 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?

Three sentences lead with the action and then provide only valuable context: the manual download workflow, label semantics, and folder resolution. No filler or redundant 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?

For a parameterless tool with no output schema, the description is comprehensive: it states what is listed, how labels are derived, where files are stored, how to override the location, and how the result is used with sibling tools. Nothing an agent needs to decide whether to call it 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 has zero parameters, so there is nothing for the description to add beyond the schema. The mention of the environment variable is relevant configuration context, not a parameter, and the baseline of 4 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 first sentence uses a specific verb and object: 'List the local custom-icon folder and the labeled image files in it.' It is unambiguous about what the tool returns and mentions the label-to-filename convention, which distinguishes it from the sibling find_masters and drop_shape 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?

The description gives a clear workflow: labels found here can be placed with drop_shape('<label>', x, y) when Visio has no built-in master, and it notes the folder location and VISIO_MCP_ICONS_DIR override. It does not explicitly list when not to use this tool, but the usage context is clear enough.

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 must disclose behavioral traits. It only says 'for viewing or editing' and gives no information about side effects, such as whether the document becomes the active document, whether the file is locked, what happens if the file does not exist, or whether the operation is destructive.

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?

A single, well-structured sentence that front-loads the verb and resource, with no redundant information. Every word contributes meaning.

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?

While the tool is simple, the description omits critical operational context: what happens after opening, whether this sets the active document for subsequent sibling operations (e.g., get_page_state, drop_shape), and what the tool returns. With no output schema and no annotations, these gaps leave an agent guessing about the workflow.

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 schema has a single 'path' parameter with no description and 0% coverage. The description adds value by specifying the file extensions (.vsdx/.vsd) and emphasizing the file must be 'existing', but it still leaves ambiguity about path formats, relative vs. absolute paths, and file access requirements.

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 'Open' and the resource 'existing Visio file', plus the specific formats (.vsdx/.vsd). It implicitly distinguishes itself from siblings like create_document and save_document by emphasizing 'existing' and 'file' rather than creation or saving.

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 the tool should be used when there is an existing Visio file path that needs to be opened for viewing or editing. However, it does not explicitly mention alternatives like create_document or open_stencil, nor does it provide when-not-to-use conditions.

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 full burden. It discloses the accepted input forms and the intended effect (masters become droppable), but does not mention side effects, prerequisites (e.g., whether a document must be open), or failure behavior. This is moderate transparency for a simple open 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?

Two sentences with no wasted words. The purpose is front-loaded, and the parameter details appear in a clearly separated second sentence. Every clause 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 single-parameter tool with no output schema, the description covers the main calling concerns: what input to provide and what happens after the call. It is slightly incomplete because prerequisites (e.g., needing an open document) and possible error conditions are not addressed, but overall it is sufficient for the tool's simplicity.

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 0%, so the description must compensate. It does so by explaining all three acceptable formats for name_or_path: built-in names with examples, absolute path, and fuzzy match against My Shapes folder. This gives the agent concrete guidance beyond the bare schema.

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 ('Open') and a specific resource ('stencil (shape library)'), and explains the resulting capability ('so its masters can be dropped'). This clearly distinguishes it from sibling tools like find_masters, drop_shape, and create_document.

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 the use case (opening a stencil to use its masters) and gives useful input context (built-in names vs My Shapes folder). However, it does not explicitly contrast with alternatives or state when not to use it, leaving some inference to the agent.

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 provided, the description carries the full burden of behavioral disclosure. It states the three actions but does not explain side effects, such as whether 'add' creates a persistent page, whether 'activate' changes the current view, or whether these operations require special permissions.

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

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

The description is a single, tight sentence that front-loads the primary actions and stays free of filler. Every phrase adds information about the tool's behavior.

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?

The tool is simple with two parameters and an enum, and the description covers the main actions. However, it omits any details about return values, error cases, or the effect of 'activate' on the document state, which an agent might need for confident 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 0%, so the description must compensate. It does add useful meaning by clarifying that the page can be 'optionally named' for add and that activation is 'by name.' However, it does not specify when name is required or how the list action uses the parameter.

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 names the resource (pages) and specifies three concrete verbs: list, add, and activate. It is unambiguous about what the tool does, though it does not explicitly differentiate itself from sibling tools like get_page_state.

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 gives no guidance on when to use this tool versus alternatives such as get_page_state, export_page_png, or set_page_size. An agent must infer from the action enum which operation is appropriate, with no context about prerequisites or exclusions.

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 burden of behavior. It usefully discloses the stateful behavior (path needed first, then save in place) and implies file overwriting via 'save in place.' However, it does not cover potential errors when no drawing is active, what permissions are required, or whether an existing file is overwritten without warning.

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, with the core action first and parameter nuance second. Every sentence adds necessary information and there is no redundancy.

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

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

For a one-optional-parameter tool with no output schema, the description is nearly complete: it tells the agent how to invoke the first save and subsequent saves. It could be slightly more complete by stating error/return behavior or requiring an open active drawing, but those are minor for a save operation.

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 0%, so the description alone must explain the 'path' parameter. It does so thoroughly: absolute path, .vsdx extension, required on first save, optional on later saves. This goes well beyond the bare nullable string schema.

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 uses a specific verb ('Save') and a clear resource ('the active drawing'), which immediately distinguishes it from sibling tools like create_document, open_document, and export_page_png. There is no ambiguity about what operation this tool performs.

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 provides explicit context for the optional path parameter: first call requires an absolute .vsdx path, subsequent calls can omit it. It does not explicitly name alternative tools or state when not to use save_document, but the save-vs-create/open/export distinction is clear enough from the wording.

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 provided, the description carries the full burden of behavioral disclosure. It reveals the default page size, export cropping behavior, invisibility of out-of-bounds shapes, orientation inference, and the shrink/grow behavior of fit_to_contents.

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 usage caveat is front-loaded, followed by a compact Args section with examples. Every sentence contributes either to when to call it, what it does, or how the parameters behave.

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 five-parameter, no-annotation tool, the description provides strong context about sequencing, units, and alternatives. However, the undocumented 'page' parameter and the absence of any statement about return values or persistence keep it just short of 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 0%, so the description must add parameter meaning. It does so for width_in/height_in (units and an example), orientation (inferred if omitted), and fit_to_contents (explicit behavior), but never mentions the 'page' parameter from the schema.

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 opens with a specific verb and object ('Resize the page') and clarifies the real-world goal (preparing for wide architecture diagrams). This is unambiguous among the sibling list, none of which target page dimensions.

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 timing guidance ('Do this BEFORE building a wide architecture diagram') and explains the consequence of skipping it (cropped exports). It does not enumerate when-not-to-use scenarios, but no sibling tool overlaps with this operation.

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 provided, the description carries the full burden of behavioral disclosure. It reveals two important behaviors: only supplied fields are changed (partial update), and theme-guarded cells are force-overridden. These go beyond a simple statement and help the agent predict side effects, though it doesn't cover return values or permissions.

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

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

The description is compact and well-structured: the core purpose first, then color format, then partial-update behavior, then container override capability. Every sentence adds distinct value, and there is no redundancy.

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

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

For a 9-parameter mutation tool with no output schema and no annotations, the description is moderately adequate. It covers the main purpose, color format, partial updates, and container overrides, but omits guidance on the page parameter, line pattern/weight specifics, and any expected return or post-conditions. It is usable 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 0%, so the description must compensate for the 9 parameters. It gives useful color format examples but does not explain most parameters like page, bold, line_pattern, or font_size_pt. The partial-update note covers null defaults implicitly, but the parameter semantics remain largely undocumented.

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 'Style' and the target resources: shape, connector, or container. It also clarifies the scope by mentioning that only provided fields are changed and that containers are supported. However, it does not explicitly distinguish this from sibling tools like update_shape, so it falls short of full sibling 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 description implies usage: use this tool when you need to style a shape, connector, or container, including containers with theme-guarded cells. It does not explicitly state when not to use it or name alternatives, so guidance is mostly implied 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?

With no annotations, the description carries the full behavioral disclosure burden. It does disclose an important partial-update behavior: only provided fields are changed, implying other properties remain untouched. However, it does not mention permissions, side effects, units for dimensions, or what happens when null values are supplied, leaving significant behavioral ambiguity for a mutation 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?

The description is a single efficient sentence that front-loads the core action and includes the important partial-update caveat. There is no filler or redundant restating 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?

For a tool with seven parameters and no output schema, the description covers the main purpose but omits at least one parameter ('page') and does not clarify units or null behavior. It is reasonably complete for the common use case but leaves notable gaps for an agent needing precise 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 0%, so the description is the only source of parameter meaning. It maps 'text' to the text parameter, 'position (center, inches)' to x/y, and 'size' to width_in/height_in, adding some unit and intent context. However, it does not explain the 'page' parameter or the null/default semantics, leaving part of the parameter set undocumented.

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 identifies the target resource ('a shape') and the specific actions: changing text, position (center, inches), or size. It goes beyond the tool name by enumerating updatable fields, making the tool's purpose concrete and distinguishable from sibling shape-related tools like delete_shapes or style_shape.

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

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

The description provides no explicit guidance on when to choose this tool over alternatives such as drop_shape, style_shape, or delete_shapes. The only implicit usage signal is 'Only the provided fields are changed,' which suggests incremental updates but does not state when this tool is appropriate or when a sibling should be used.

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 provided, the description carries the full burden of disclosing behavior. It honestly reveals the side effect that it 'Launches Visio if it is not already running', which an agent must know before calling. It also clarifies the built-in stencil library behavior (openable by bare filename, no download needed), adding useful operational context beyond the core report.

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 primary purpose, then lists concrete report contents, then adds the critical launch side effect and invocation advice. Each sentence earns its place and there is no filler or repetition.

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 there is no output schema and no annotations, the description sufficiently tells the agent what the tool returns, what side effect it may have, and when to call it. The enumerated report contents plus the launch behavior and 'Call this first' instruction make the tool safe and correctly invocable.

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 has zero parameters and 100% schema description coverage, so there is no parameter semantic burden for the description to carry. The baseline of 4 applies because there is nothing for the description to add about parameters.

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 opens with a specific verb and resource ('Report Visio state') and enumerates exactly what the report contains: version, open documents and stencils, active page, My Shapes path, and the built-in stencil library. This clearly distinguishes it from the action-oriented sibling tools like open_stencil or create_document.

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 says 'Call this first', giving an explicit invocation order relative to the sibling tools. It also notes it launches Visio if not running, which tells the agent this is the correct entry point before operating on documents or stencils. It does not explicitly name alternatives or exclusions, but for a state-report tool that is a minor gap.

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