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

The description accurately reflects a mutating action, and there is no contradiction with the annotations, but it adds little beyond the basic fact that a page is added. No additional side effects or limitations are disclosed.

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 very concise and well structured, with a one-sentence purpose followed by clear per-argument explanations. No unnecessary details are included.

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 such a simple tool, the description provides enough context to use it correctly, including defaults and how to specify the target document. It does not discuss output or persistence, but those are not critical for this action.

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 zero schema-level descriptions, the prose fully compensates by explaining both parameters: the name is optional with an auto-generated fallback, and the document accepts a file name or 1-based index with the active document as the default.

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: 'Add a page to a document.' This clearly distinguishes the tool from siblings like add_shape or delete_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 explains how to target a document and how the page name behaves, but it does not explicitly state when to use this tool versus alternatives such as adding shapes or working with existing 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?

Clearly indicates the tool mutates the document by adding a shape and reports the new id. It also explains defaults for page/document/master behavior beyond the minimal 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?

The description is reasonably concise but contains slight redundancy between the first sentence and the Args list, and a minor typo ('drop' instead of 'use').

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?

Includes return behavior, related tool reference, and defaults. With an output schema present, it need not elaborate further; the description gives enough context for successful 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 no schema-level descriptions, the text explains all 10 parameters, including units, defaults, and optional behavior (e.g., page/document omission, width/height defaults, primitive options).

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 ('Add a shape to a page') and the return value ('return its new id'), clearly distinguishing it from sibling tools that render, query, or modify 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?

Provides practical guidance on preferring masters and consulting visio_list_masters, plus behavior when no master is used. It does not explicitly contrast with every alternative, but the usage context is clear.

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

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

The description discloses an important behavioral trait: the connector is glued to both shapes and reroutes itself when they move. Annotations already indicate this is a non-readonly, non-idempotent, non-destructive operation, and the description adds useful runtime behavior without contradiction.

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: a short behavioral summary followed by a brief parameter list. It contains no redundant or irrelevant 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?

The description is complete for the simple operation: it explains what the tool does, how the connector behaves, and all parameters. It does not discuss errors or return values, but the presence of an output schema makes that less necessary.

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?

All five parameters are explained in the Args section, including which shape is the source/destination, that label is optional, and that page/document can be omitted to use the active document/page. This adds meaning beyond the bare input 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 action ('Draw a dynamic connector') and the involved resources (from one shape to another), distinguishing it from sibling tools such as adding/moving/deleting shapes or listing connections. It is specific and 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 description gives clear context for when to use the tool: when connecting two Visio shapes with a dynamic connector. It does not explicitly name alternatives or exclusions, but the function is straightforward and sibling tools are clearly different.

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

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

The annotations already mark the tool as destructive and not read-only. The description goes beyond that by explaining the consequence for connected shapes, which is important behavioral context. It does not mention undo or irreversibility, but the destructive hint covers the primary risk, and the connector warning adds meaningful transparency.

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. It opens with a one-sentence purpose, adds a relevant warning, and then lists the parameters with brief explanations. 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?

Given the tool's low complexity and the presence of an output schema, the description covers the essential operational context: what it does, what side effects to watch for, and how to specify parameters. It could mention the return format, but that is not required when an output schema exists. Overall, it is sufficiently complete for an agent to use 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?

The description provides meaningful context for all three parameters: shape_id is the ID from visio_list_shapes, page is a page name or 1-based index with an omit default, and document is a file name or 1-based index with an omit default. This compensates for the lack of schema descriptions and gives the agent enough to fill parameters correctly.

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's function: 'Delete a shape from the page.' It names the specific resource (shape) and action (delete), and no sibling tool performs the same action. The additional note about dangling connectors reinforces the purpose.

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 practical guidance on when to use the tool and warns about a key side effect: deleting a box leaves connectors behind. It suggests checking visio_list_connections or deleting those too, which helps the agent decide whether this tool is appropriate. It could be stronger by explicitly contrasting with non-destructive alternatives, but the guidance is clear.

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

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

The readOnlyHint annotation indicates the document itself is not modified, and the description clarifies output is an image file. It does not detail side effects like file overwriting or error conditions, but the annotation covers the main safety concern.

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 every sentence adds useful information. It front-loads the primary purpose and then provides parameter-specific details without unnecessary 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?

The purpose, parameters, and supported formats are all covered. Return value details are not specified, but the context indicates an output schema exists, so that omission is acceptable; however, no error or fallback behavior is mentioned.

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?

All four parameters are explained with meaningful semantics: path resolution, page selection via name/index, document selection, and max_pixels behavior for raster formats. This goes well 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 action: writing a page to an image file on disk. It lists supported formats and distinguishes the tool from PDF export and page rendering siblings by focusing on image files.

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 explains how parameters behave but does not explicitly say when to prefer this tool over visio_export_pdf or visio_render_page. It lacks direct guidance on alternatives or use-case boundaries.

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

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

The readOnlyHint annotation indicates the tool does not mutate the document, and the description does not contradict that. However, the description does not mention side effects such as creating or overwriting a PDF file at the destination path.

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, direct, and well-organized. Every sentence and parameter line adds relevant information without unnecessary verbosity.

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 fairly simple and the description covers the main inputs and behavior. It does not describe the return value, but an output schema is present, so omitting return-value details is acceptable.

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 useful meaning to each parameter, such as 'Omit for the active document' and 'Export every page rather than a single one.' It lacks some detail, like whether page is a name, number, or 1-based index, but overall it substantially supplements 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 name and description clearly state the tool exports a document to PDF. However, it does not explicitly distinguish itself from the sibling visio_export_page, relying on the parameter hints to imply the document-level scope.

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 by mentioning paths and page options, but it does not explicitly state when to prefer this tool over visio_export_page or other export-related tools. Usage guidance is present only through the parameter descriptions.

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

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

The description says 'Read' and 'Inspect', making the read-only nature clear, and the readOnlyHint annotation reinforces this. It also explains the shape_data key format in relation to visio_set_shape_data, which adds useful behavioral context beyond the annotation.

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-organized, with a brief purpose statement followed by an Args section. No unnecessary wording or redundancy is 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?

The description provides enough context to understand what data is fetched, how shape_data keys relate to another tool, and how to use defaults for page and document. Given the output schema is noted as existing, the description adequately covers the tool's scope.

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?

All three parameters are described with concrete types and defaults: shape_id comes from visio_list_shapes, while page and document support name or 1-based index and explain omission behavior. This fully covers the input schema despite the schema itself lacking descriptions.

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 reads everything about one shape, including text, geometry, Shape Data, layers, and links. The title 'Inspect a shape' reinforces a read-only purpose without ambiguity.

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

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

The description implies use when needing full shape details, but it does not explicitly contrast with sibling tools like visio_list_shapes or visio_search_text. The note about visio_set_shape_data expectations hints at a follow-up workflow but stops short of explicit usage 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?

Beyond the readOnlyHint annotation, the description discloses important behavior: connectors glued at only one end or neither end return null on the loose side, which is how broken diagrams are detected. This adds meaningful behavioral context beyond the annotation.

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: a front-loaded purpose statement, a valuable edge-case note, and a compact parameter list. Every sentence contributes useful information without 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?

The description is complete for a read-only list tool with optional parameters and an output schema. It covers purpose, parameter semantics, and the key null-value behavior, leaving no critical gap for 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 0%, so the description carries the full burden for parameters. It clearly explains both page and document: name or 1-based index, and that omitting them targets the on-screen page or active document. This is exactly what an agent needs.

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

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

The description states a specific verb and resource: 'Read the page as a graph: which shape each connector runs from and to.' This clearly identifies the tool as inspecting connector topology, distinguishing it from sibling tools like visio_list_shapes or visio_get_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 gives clear context for when to use the tool: to understand connector relationships and to spot broken diagrams via null values on loose connector ends. It does not explicitly name alternatives or exclusions, but the intended use case is evident.

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

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

Annotations are minimal with only readOnlyHint: true, which the description aligns with ('List' is read-only). The description adds meaningful context beyond annotations by explaining that include_stencils reveals normally hidden stencil/template documents, clarifying that the default behavior excludes them. This adds a behavioral nuance not captured by the schema or 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?

The description is extremely concise, consisting of two sentences that convey the core purpose and the parameter's effect. The main action is front-loaded, and every sentence adds value. There is no redundant information or filler.

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

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

The tool has an output schema (not shown but indicated by 'Has output schema: true'), so return-value documentation is likely covered there. The description covers the primary behavior and the only parameter's semantics. For a simple one-parameter list operation, this is largely complete. A slight gap is the absence of any mention of the output format or that it returns only user drawings by default, but the description implies this and the output schema may handle details.

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%, and the schema only provides a title ('Include Stencils') and a default. The description adds semantic value by explaining that enabling this parameter 'will list open stencil and template documents' and that these are 'normally hidden because they are not the user's drawing'. This clarifies the parameter's effect and why it defaults to false, going beyond the schema's minimal labeling.

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 'List' and a clear resource 'drawings open in Visio right now'. It is distinctly different from sibling tools like visio_list_pages or visio_list_shapes, which operate on other scopes. The phrasing 'right now' clarifies it returns the current session's documents, making the purpose 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 description implies usage context by specifying 'open in Visio right now', but it does not explicitly state when to use this tool versus alternatives (e.g., when to use visio_list_pages or visio_list_shapes). There is no guidance on exclusions or when not to use it. The include_stencils note suggests a conditional use case but does not frame it as a selection criterion.

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

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

The readOnlyHint annotation already covers the read-only nature, and the description adds useful behavioral detail about the default scoping of the search. It does not over-promise or hide side effects, and the added context goes beyond the annotation.

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 succinct and well-organized: purpose first, then default behavior, then parameter details. No redundant or superfluous text, making it easy for an agent to parse quickly.

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 simple two-parameter non-nested structure, the description covers all necessary aspects: purpose, behavior, default options, and parameter semantics. It is complete for the tool's 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?

Both parameters are fully explained in the description text, including their meaning and default behavior (e.g., 'Look inside this stencil instead', 'Omit for the active document'). This adds significant value beyond the raw schema, which contains no descriptions.

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 lists shape masters for use with visio_add_shape, distinguishing it from other list-type tools by specifying the resource type and associated action. It provides a specific verb and resource, making the purpose 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 description explains the default behavior when no arguments are given ('masters already used in the drawing plus every open stencil'), which offers context for typical use. However, it does not explicitly mention when to prefer alternatives like visio_list_shapes or visio_get_shape, 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?

readOnlyHint=true already communicates the safety profile. The description adds active-document default behavior and what fields are returned, but does not discuss error behavior, pagination, or performance. This is acceptable given the read-only annotation, but not exceptional.

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 clear sentence plus an Args block. The purpose is front-loaded and useful details are present 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 single-parameter read-only list operation with an output schema, the description is complete. It explains the parameter semantics and the type of information returned, leaving little ambiguity for an agent 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 coverage is 0%, so the description is the only source of semantics for the 'document' parameter. The Args section explicitly describes file name or 1-based index and the active-document default, fully compensating for 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 clearly states a specific action ('List the pages'), the resource (pages of a document), and the return content (size in inches and shape counts). This distinguishes it from siblings like visio_list_documents, visio_list_shapes, and rendering/export 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 practical context by explaining how to specify the document (file name or 1-based index and active document when omitted). It does not explicitly compare with or exclude sibling tools, but the context is clear enough for choosing it to list page information.

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

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

Annotations declare readOnlyHint=true, and the description adds useful behavioral context beyond that: it reveals that x and y coordinates represent the shape's centre in inches from the bottom-left of the page, and that include_connectors can hide connector lines. This goes beyond the annotation's simple read-only flag and helps agents interpret output correctly.

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 and front-loaded: a one-sentence summary, a key usage note, a brief coordinate clarification, and a compact Args list. Every sentence adds value, and the length is appropriate for the tool's complexity.

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 three optional parameters and the presence of an output schema, the description covers all necessary information: what the tool does, how to specify page and document, and how to control connectors. It also explains the coordinate system, so an agent can call the tool correctly without needing additional documentation.

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 fully compensate, and it does. The 'Args' section explains each parameter: page accepts a name or 1-based index with a default behavior, document similarly, and include_connectors controls whether connectors are returned. This is explicit, actionable guidance that the schema lacks.

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

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

States a specific verb ('List') and resource ('shapes on a page') with the data returned (id, text, master, geometry). The line 'This is the way to find the shape ids every editing tool needs' clearly distinguishes it from sibling tools that serve different purposes, such as visio_get_shape or visio_search_text.

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 a clear usage directive: 'This is the way to find the shape ids every editing tool needs' tells agents this is the go-to tool for obtaining shape IDs, which is critical for editing workflows. It does not explicitly contrast with alternatives like visio_get_shape or visio_search_text, so it stops short of a full when-not-to-use list, but the context is strong enough for an agent to select it appropriately.

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

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

The description accurately conveys the primary behavior (move/resize/rotate) and adds a transparency guarantee: 'Only the values you pass are changed.' This goes beyond the annotations (which only indicate readOnly=false, idempotent=false, destructive=false) by clarifying no unintended property changes. However, it does not mention potential side effects like connected connector adjustments, so it is not fully exhaustive.

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

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

The description is extremely concise: two sentences and a parameter list. It is well-structured with clear separations, and every sentence adds value. There is no fluff or redundant 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?

Given the schema and annotations, the description is complete. It covers all parameters with units and defaults, mentions the source for shape_id, and does not need to explain return values because an output schema is present. The context signals confirm an output schema exists, so no missing information.

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?

Each parameter is described in the text: shape_id is sourced from visio_list_shapes, x/y are in inches, width/height in inches, angle in degrees, and page/document have default behaviors. This fully compensates for the schema's lack of descriptions (0% coverage) and provides clear semantics for all 8 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 clearly states the tool's function: 'Move, resize or rotate a shape.' It uses a specific verb and object, and the phrase 'Only the values you pass are changed' distinguishes it from tools that might alter other properties. Given the sibling context, it is unmistakable that this tool is for geometry modifications.

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 does not explicitly state when to use this tool versus alternatives like visio_set_shape_text or visio_add_shape. It implies usage for geometric changes via the name and description, but lacks direct guidance or exclusionary language. The note about only changing passed values offers some situational cue, but it is not explicit enough for a high score.

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

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

The readOnlyHint annotation is complemented by the description stating the tool 'return[s]' the rendered image, implying no side effects. The additional hint 'Keep it modest' for max_pixels gives practical guidance on performance and image size, going beyond the annotation.

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-organized: a one-sentence purpose, a short usage rationale, and a clear args list. It front-loads the main action and avoids redundancy. Each sentence adds value, 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?

The description covers the tool's purpose, usage context, and parameter semantics. It lacks explicit information about the return format (e.g., base64, file reference), but given the platform likely handles this transparently, the omission is minor. It also does not mention error cases, which is acceptable for a read-only render 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?

Despite the schema having no descriptions (0% coverage), the tool description provides meaningful explanations for every parameter: page and document accept 'name or 1-based index' with 'Omit for' defaults, and max_pixels is defined as 'Longest edge of the image' with a caution to 'Keep it modest.' This fully compensates for the schema's lack of descriptions.

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's action: 'Render a page to a PNG and return it.' It also gives the intended use case: 'whenever layout, overlap or visual style matters,' distinguishing it from coordinate-based tools like visio_get_shape or visio_list_shapes. The purpose is specific and 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 description provides clear usage guidance: 'Use this whenever layout, overlap or visual style matters; shape coordinates alone rarely tell you whether a diagram reads well.' This directly advises when to choose this tool over inspecting shape coordinates. It does not explicitly name other export tools (e.g., visio_export_page), but the contrast with coordinate access is sufficient for most cases.

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 indicate this is not read-only, idempotent, or destructive, but the description adds no further behavioral detail. It does not mention return values, side effects, whether changes are persisted, or error behavior when no shapes match.

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 main action is stated in one sentence, followed by a compact Args list that matches each parameter without unnecessary fluff.

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 core operation and all parameters. An output schema exists, so omitting return details is acceptable. However, it could be slightly more complete by noting whether changes require an explicit save, especially since visio_save and visio_undo are sibling tools.

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?

All five parameters are described in the Args section with sufficient meaning: find, replace, page, document, and match_case. The descriptions clarify scope and defaults (e.g., omit page to cover every page), though they lack edge-case details.

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?

Description clearly states the action: replacing a substring in the text of every shape that contains it. This distinguishes it from related tools like visio_search_text (find only) and visio_set_shape_text (set entire text).

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?

No explicit guidance on when to use this tool versus alternatives. It does not mention that visio_search_text should be used for finding-only, or that visio_set_shape_text might be preferred for replacing full text, nor does it advise about save/undo workflows.

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

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

The annotations indicate the tool is not read-only, not idempotent, and not destructive, which is consistent with a save operation. The description adds that edits are in memory until called, but does not mention return values, errors, or side effects such as overwriting existing files.

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 brief and well-structured, with a clear first sentence and a compact parameter list. No unnecessary words or redundant information 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?

The description covers the core purpose and the in-memory edit context, and the output schema exists. However, it lacks details about parameter constraints, file format implications, error handling, and whether the operation blocks until the save completes, leaving some gaps for an agent to infer.

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 provides no descriptions for either parameter. The description gives minimal guidance: 'document' is a file name or index (defaulting to active), and 'path' allows saving elsewhere. However, key details like path format, overwrite behavior, or relationship between document and path are not explained.

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 saves the document to disk, using a specific verb ('Write') and resource ('document'). It distinguishes from sibling tools by focusing on persistence rather than rendering, listing, or editing 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 explains that edits are in memory until this is called, giving context for when to use it. It does not explicitly contrast with sibling tools or specify when to use the optional 'path' parameter versus saving to the default location.

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

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

The readOnlyHint annotation already indicates this is a non-mutating operation. The description reinforces this by using 'Find' rather than any modifying verb. It does not mention return format or errors, but the read-only nature is sufficiently disclosed through the annotation and wording.

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—one clear sentence followed by a minimal parameter list. No redundant information or filler is present, making it easy to parse quickly.

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 core search behavior and parameter semantics, and an output schema is present to define the return shape. It does not explicitly mention error scenarios or result ordering, but given the output schema and simple nature of the search, it is adequately 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?

Although the schema itself has no parameter descriptions, the prose description explicitly explains all three parameters: query (substring), document (file name or 1-based index, optional), and match_case (case-sensitive toggle). This fully compensates for the schema's lack of descriptions.

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's verb ('Find'), resource ('shapes'), and specific filter ('text contains a substring, across every page'), making its purpose unambiguous and distinct from sibling tools like visio_list_shapes or visio_replace_text.

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 makes the intended use case evident—searching for shapes by text content—and the optional parameters for document and case sensitivity are briefly explained. It does not explicitly contrast with sibling tools, but the purpose is clear enough to infer appropriate usage.

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

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

The description goes beyond the annotations by explaining that it changes both the selection and the on-screen page but does not modify the drawing. This gives important context about side effects and non-persistence.

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: a one-line summary, a single clarifying sentence about side effects, and a clear parameter list. No redundant or irrelevant content.

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

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

Given the tool's simplicity, the description covers the purpose, side effects, parameters and defaults. An output schema exists, so not detailing return values is acceptable. No important context appears 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?

Even though the schema has no descriptions, the Args section fully explains each parameter: shape_ids as the IDs to select, page with default behavior ('Omit for the page on screen'), and document with default behavior ('Omit for the active document').

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

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

The description clearly states the action ('Select shapes') and the resource ('in the Visio window'), and explains the intent ('to show the user what you mean'). This distinguishes it from sibling tools like visio_get_shape or visio_list_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?

It indicates when to use the tool (to visually show the user which shapes are meant) and clarifies that it only affects the on-screen selection, not the drawing. However, it does not explicitly contrast with sibling tools such as visio_get_shape or visio_set_shape_text, though the purpose is fairly clear.

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

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

Annotations only indicate readOnly=false, idempotent=false, and destructive=false, leaving the description to carry behavioral details. It mentions row creation on missing fields but does not describe whether existing values are overwritten, potential side effects, or error behavior.

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 brief and well-organized, with a clear one-sentence summary followed by a compact parameter list. No redundant or filler content is 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?

The description provides enough context for a simple setter operation and references related tools for parameter sourcing. It does not mention return values or error conditions, but the presence of an output schema reduces the need for explicit output documentation.

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?

All six parameters are described in the Args section, with useful context such as 'Id from visio_list_shapes' and 'as shown in visio_get_shape's shape_data keys'. The name constraint 'Letters, digits and underscores only' adds concrete validation information not present in 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 clearly states the operation: setting a Shape Data field on a shape, with the added behavior of creating the row if missing. It uses a specific verb and resource, and the scope is distinct from sibling tools like set_shape_text or add_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 gives helpful references for obtaining shape_id, page, and document values, but it does not explicitly state when to prefer this tool over alternatives or mention exclusions. Usage guidance is implied through the parameter references rather than directly stated.

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

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

The description adds no behavioral context beyond the annotations. It does not mention mutability, side effects, or whether the change requires saving. The annotations already indicate readOnlyHint false and idempotentHint false, but the description contributes nothing additional.

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 extremely concise, with the primary purpose in the first sentence and parameter details presented in a structured list. It is well-front-loaded and avoids unnecessary verbiage.

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 parameters fully and states the basic action, but it lacks context on expected outcomes, error conditions, or how it fits into the larger workflow (e.g., after adding a shape or before saving). The existence of similar sibling tools makes this missing context more significant.

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 includes explicit explanations for all four parameters (shape_id, text, page, document), providing complete coverage that the schema itself lacks. Each parameter is described with its source or usage, which fully clarifies its 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 'Replace the text of one shape' clearly states the verb and object, and specifies the scope of one shape. However, it does not explicitly distinguish this from the sibling tool 'visio_replace_text', which could cause ambiguity about which to use when multiple replacements are needed.

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?

There is no guidance on when to use this tool versus alternatives such as 'visio_replace_text' or 'visio_set_shape_data'. The description only states what it does, not when it is appropriate.

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

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

The readOnlyHint annotation is consistent with the description's 'check' behavior, and the description adds useful context about detecting lost connections, though it does not explicitly state there are no side effects.

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

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

Two concise, front-loaded sentences convey purpose and usage without extraneous detail.

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

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

For a parameterless status tool, the description fully covers what it checks and when to call it. Output schema is present, so return details are covered elsewhere.

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?

There are no parameters, so no parameter description is needed. The schema coverage is 100% and the description adds no conflicting or ambiguous parameter guidance.

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?

Clearly states the tool checks which running Visio instance is attached and what it has open, distinguishing it from sibling tools that modify or render content.

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 instructs to call this first and to call again if another tool reports a lost connection, providing clear when-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?

The description warns that the action may revert changes made by the user, which is meaningful behavioral transparency beyond the destructiveHint annotation. It does not fully detail side effects like interaction with save state, but for a simple undo operation this is adequate.

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 brief and front-loaded, with the core purpose in the first sentence. The Ctrl+Z analogy conveys behavior efficiently, and the Args line is directly tied to the parameter without unnecessary prose.

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 undo operation, the explanation is functionally complete: it states the action, the target, the parameter, and the key caveat about user edits. It does not enumerate every edge case, but the output schema exists and the behavior is well modeled by the Ctrl+Z analogy.

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 provides only a type and default for 'steps', but the description adds a plain-language explanation: 'How many steps to undo.' This clarifies the parameter's meaning and likely range of use, though it does not specify edge cases like zero or excessive values.

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 undoes recent actions in Visio, using the Ctrl+Z analogy which is immediately understandable. It also names the exact resource (Visio's undo stack) and distinguishes this from other document modification tools in the sibling list.

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 a clear usage frame ('exactly as Ctrl+Z would') and adds an important caveat that the undo may revert the user's own last edit rather than the agent's. It does not explicitly contrast with alternatives, but no other sibling tool performs undo, so the guidance is sufficient.

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