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 states the basic action and coordinate system, but omits critical information such as whether the tool requires an open Visio document, whether it modifies the current page or the page specified by pageIndex, what happens on failure (e.g., no page exists), and whether it returns any handle or ID to the created shape. This is insufficient for a state-changing 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?

The description is a single, clear sentence that front-loads the action and the key coordinate detail. It is efficient and avoids redundant wording, though it could be expanded slightly without becoming verbose. No 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?

For a tool with 8 parameters, a nested object, and no annotations or output schema, the description is notably incomplete. It does not explain prerequisites (e.g., an open document), how coordinates relate to the page origin, or what the tool returns or does not return. An agent would likely need to inspect the schema further and may still lack critical context about operational behavior.

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 88%, meaning most parameters already have descriptions. The description reinforces the coordinate system (inches from top-left) but does not add new semantic details beyond the schema. For example, it does not explain how style options interact or how width/height defaults are chosen. With high coverage, a baseline of 3 is appropriate, with no extra value added.

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 ('Add') and the resource ('a shape to a Visio page'). It also provides a key detail—coordinates in inches from the top-left corner—which distinguishes the positioning semantics from other shape tools like move_shape. This is specific and unambiguous, separating it from siblings that modify existing 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?

No guidance is given on when to use this tool versus alternatives. It does not mention that this is for creating shapes, nor does it exclude cases where other tools (e.g., set_shape_text) are more appropriate. The intended context is implied but not explicit, leaving the agent to infer when to call add_shape.

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 behavior. It does mention key behaviors: validating against the type's vocabulary and rejecting mixed element types, and returning a normalized analysis. However, it does not state whether the operation is read-only, what happens on validation failure, or any side effects. The absence of annotations raises the bar, and the description only partially covers the behavioral surface.

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, fairly dense sentence that front-loads the phase information ('PHASE 1 of diagram generation') and then explains the workflow. It is efficient and not verbose, though it runs on a bit. It earns a 4 for being concise and structured without wasting words.

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

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

The tool has six parameters, no required fields, no output schema, and no annotations. The description explains the high-level workflow and mentions the output is a 'normalized analysis' to pass into plan_diagram, but it does not describe the exact structure of that analysis or how errors are reported. It also does not clarify what happens when validation fails beyond 'rejecting mixed element types'. Given the lack of an output schema, the description should provide more detail on return values and error behavior, so it is only partially complete.

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

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

Schema coverage is 100% and every parameter has a description, so the baseline is 3. The description adds some context about the overall workflow (e.g., that nodes/edges form the graph to be validated), and clarifies that omitting diagram_type returns the type menu. However, it does not add per-parameter semantics beyond what the schema already provides; the schema already explains the guard labels, kind vocabulary, and rationale.

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 purpose: validate a graph (nodes/edges) against a chosen diagram type's vocabulary, rejecting mixed element types, and return a normalized analysis. It names the specific resource (graph) and action (validate), and distinguishes itself from siblings by positioning it as 'PHASE 1' and noting the output feeds into plan_diagram, which differentiates it from design and planning 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 clear context: this is the first step after reading the requirement and extracting elements, and the output should be passed to plan_diagram. It implies when to use it (after extraction, before planning) but does not explicitly mention alternatives or when not to use it, such as when to use validate_spec or get_type_vocabulary instead. This is clear context without exclusions, so a 4 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?

With no annotations provided, the description bears the full burden of disclosing behavioral traits. It states the action but omits critical consequences, such as unsaved changes being lost when save=false. This is a significant gap for a close operation that can discard data.

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, clear sentence with no redundant wording. It is appropriately front-loaded and efficient.

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

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

For a mutation operation without annotations, the description is incomplete. It does not mention the risk of losing unsaved changes, which is essential for an agent to make a safe decision. The presence of the 'save' parameter implies this, but it is not explicitly stated.

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 fully documents the 'save' parameter (default false), achieving 100% coverage. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action (close) and the resource (active Visio document), making the tool's purpose unambiguous. It is distinguishable from sibling tools like open_document or save_document without needing to inspect the schema.

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

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

The description provides no context on when to use this tool or how it compares to alternatives. It does not mention that save_document should be called first if changes need to be persisted, nor does it explain any prerequisites or conditions for closing.

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?

There are no annotations provided, so the description carries the full burden of behavioral disclosure. It states 'Draw a connector' which implies a mutation, but does not mention potential side effects, whether the operation is reversible, what happens if shapes do not exist, or whether the document is modified. The description is purely functional and lacks deeper behavioral context.

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, concise sentence that is perfectly front-loaded with the core action. There is no unnecessary verbosity or filler. Every word earns its place, making it highly efficient and easy to parse.

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 four parameters (two required) and no output schema, the description is incomplete. It does not mention that the shapes must already exist on a page, the effect of the optional 'text' and 'pageIndex' parameters, or any constraints (e.g., connector routing). An agent would need to inspect the schema to understand the full picture, but the description alone leaves out critical usage 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?

The schema description coverage is 100%, with each parameter having a clear description in the input schema. The tool description adds no additional meaning about parameters, such as how text or pageIndex affect the connector. Since the schema already fully documents parameters, the baseline of 3 is appropriate; the description does not need to repeat what the schema provides.

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

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

The description 'Draw a connector (arrow) between two shapes' is specific and unambiguous. It uses a clear verb and resource, and clearly distinguishes this tool from siblings like get_connections (which retrieves connections) and add_shape (which adds shapes). There is no ambiguity about what action it 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?

The description gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as the shapes needing to already exist, or when it might not be appropriate (e.g., if shapes are not on the same page). No alternatives are referenced, so an agent receives no context for selection.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states that it creates a new drawing document but does not disclose whether it requires Visio to be open, whether it replaces the current document, whether it creates a file or just an in-memory object, or what the return value is. For a mutation tool with zero annotation coverage, this is a significant 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 a single, front-loaded sentence with no filler. Every word contributes to the meaning, and it is appropriately sized for the tool's simplicity.

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 zero-parameter tool with no output schema and no annotations, the description is incomplete. It fails to mention prerequisites (e.g., Is Visio running?), side effects (e.g., Does it close the current document?), or what the tool returns. An agent would not know whether it can call this without first ensuring the application is open or whether it will disrupt existing work.

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 the description does not need to explain parameter behavior. The schema already covers the absence of inputs, and the description adds no param-related confusion. Baseline for zero parameters is 4, and nothing here reduces that.

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 ('Create') and a clear resource ('a new blank Visio drawing document'), distinguishing it from siblings like open_document (which would open an existing file) and save_document. The purpose is unambiguous and immediately 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 does not explicitly state when to use this tool versus alternatives, though it is implied that it is for creating new documents rather than opening or saving existing ones. No explicit when/when-not guidance is given, so the usage context is only implied by the verb and resource.

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 must carry the full burden of behavioral disclosure. It only states the basic action and gives no information about side effects (e.g., whether the new page becomes active), error conditions (e.g., what if no document is open), or return behavior. As a mutation tool, more transparency is expected.

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, concise sentence that front-loads the action and resource. There is no verbosity or redundancy; it earns its place entirely.

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 one optional parameter and no output schema, the description is adequate but incomplete. It omits explicit prerequisites (e.g., a document must be open) and what happens on success or failure. Given the low complexity, this gap is notable but not severe.

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 parameter 'name' is fully described in the schema ('Name for the new page'), yielding 100% schema description coverage. The tool description does not add any additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific action ('Add a new page') and a specific resource ('to the active Visio document'), which clearly distinguishes it from siblings like add_shape (adds shapes) and get_pages (reads pages). The active-document qualifier adds useful 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 operates on an active Visio document, hinting at a prerequisite, but it does not explicitly state when to use this tool versus alternatives (e.g., create_document for new files, add_shape for shapes). No exclusionary guidance or explicit 'use when' conditions are given.

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. It correctly notes the destructive, irreversible nature via the word 'permanently', which is key. However, it does not disclose other potential behavioral aspects such as whether attached connectors or child elements are also deleted, or the nature of the response on success.

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, succinct sentence that leads with the action. There is no filler or redundancy; it efficiently conveys the core purpose.

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 delete operation with one required parameter, the description is adequate but lacks some context. It doesn't state whether the shape must belong to an open document, and since there is no output schema, it doesn't mention the return value or success behavior. However, given the simplicity, it is only slightly under-specified.

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

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

Schema description coverage is 100%, so both parameters (shapeId and pageIndex) are fully documented in the schema. The description adds no additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'delete' and the resource 'shape', and the qualifier 'permanently' adds precision. It distinguishes from sibling tools like move_shape or resize_shape which operate on shapes differently.

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 removing a shape from the page, but provides no explicit context on when to avoid it (e.g., if the shape is referenced elsewhere) or any prerequisites like an open document. No alternatives are mentioned, but none exist among siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses the stencil resolution step, the 'needs_download' status and rendering fallback behavior, and that Visio remains open and visible. It does not mention file overwriting or return value format, but the key behaviors are 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 three sentences, front-loaded with the phase and purpose, and includes conditional behavior. It is efficient and well-organized, though it could benefit from clearer separation of output and side effects.

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, the description should explain return values. It mentions the 'needs_download' status but not the full return format on success or failure. It also leaves ambiguity about whether a new document is created or an existing one is used, though it implies rendering in the current Visio session. For a pipeline tool, this is moderately complete but has gaps.

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 covers all 5 parameters with descriptions, so the description adds minimal value beyond that. It does provide context that 'spec' comes from plan_diagram, but this is a usage hint rather than parameter semantics. Baseline 3 is appropriate given 100% schema coverage.

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 purpose: it is Phase 3 of diagram generation, renders the positioned spec in Visio, and saves output files. It references the input spec from plan_diagram and distinguishes itself from siblings like resolve_stencil and validate_spec by focusing on the rendering step.

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 implies usage as the rendering step after plan_diagram, and explains the conditional behavior for missing stencils. However, it does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or prerequisites beyond the phase context.

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

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

With no annotations, the description carries the full burden but discloses almost nothing beyond the action. It does not mention file-overwrite behavior, whether an open document is required, if the operation is synchronous, or how pageIndex applies to non-PDF formats. The schema hints at 'PDF only' for omitting pageIndex, but the description adds no clarity.

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

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

The description is a single sentence with zero waste. It is front-loaded with the core purpose and lists formats explicitly.

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 moderately complex (multiple formats, pageIndex logic), yet the description lacks critical context: return value, error behavior, prerequisites, and file-overwrite semantics. The schema provides some parameter details but the description itself is incomplete for an agent to call correctly.

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

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

Schema description coverage is 100% and all parameters are documented in the schema itself. The description adds no extra meaning about the parameters, so a baseline of 3 is appropriate.

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

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

The description clearly states the action (export) and the resource (Visio document or a page) plus the target formats (PNG, PDF, SVG, EMF, VSDX). It is specific and unambiguous, and no sibling tool appears to offer the same function, so it stands apart.

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 like save_document, nor when to specify pageIndex versus omit it. There is no context about prerequisites (e.g., document must be open) or exclusions for certain formats.

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. 'List' implies a non-destructive read, which is useful, but nothing is said about failure modes (e.g., behavior when no document is open or pageIndex is out of range), return format, or whether it requires an open document. The primary behavior is disclosed; edge cases are not.

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 sentence with zero wasted words, front-loaded with the verb and resource. It conveys purpose and output shape economically.

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 read tool with one fully-documented optional parameter and no output schema, the description covers the essentials: what it lists and what it shows. It could briefly note the page-scoping of the pageIndex parameter, but the schema already handles that, so nothing an agent strictly needs is missing.

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

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

Schema coverage is 100%, so the single pageIndex parameter is fully documented in the schema. The description adds no parameter details beyond what the schema already provides, which meets the baseline for high coverage but does not exceed it.

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

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

The description uses a specific verb ('List') plus a concrete resource ('connectors on a page') and adds what the output shows ('which shapes they connect'). This cleanly distinguishes it from siblings like get_shapes (shapes, not connectors) and connect_shapes (a creation/action tool, not a listing tool).

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

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

The read-vs-write nature of the tool is inferable from 'List', but there is no explicit when-to-use guidance or mention of alternatives. Given the large sibling set, a sentence clarifying that this only reads existing connections (as opposed to connect_shapes, which creates them) would materially help routing.

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

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

With no annotations provided, the description must disclose behavior. 'Get' clearly indicates a read-only operation, but it does not mention potential error conditions (e.g., no active document) or the exact return structure. It is transparent about the action, but lacks edge-case behavior details.

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, front-loaded sentence that names the operation and enumerates the returned data succinctly. No filler words; every word carries 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?

Given the tool has no parameters and no output schema, the description tells an agent exactly what information will be returned (name, path, page count, save status). It lacks explicit mention of prerequisites or error behavior, but for such a simple retrieval, this is mostly adequate. Minor gap: no statement about behavior when no document is open.

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 zero parameters, so the description has no need to explain them. The baseline for 0 parameters is 4, and the description appropriately avoids redundant parameter 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?

The description clearly states the verb 'Get' and the resource 'document info', listing specific data fields (name, path, page count, save status). This distinguishes it from sibling tools like get_pages or get_selection, which retrieve different aspects of the 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 usage context is implied: if you need basic metadata about the active document, you use this tool. However, it does not explicitly state when not to use it or compare to alternatives like get_pages or get_visio_status. Guidance is vague but sufficient for a simple getter.

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. The description states a read-only action ('List') and implies no side effects, but it does not explicitly confirm that it does not modify the document, nor does it mention error conditions (e.g., what happens if no document is open). For a read-only tool this is acceptable, but the lack of explicit behavioral detail leaves a small 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 a single, concise sentence with no filler. It front-loads the primary action and resource, then lists the returned fields. Every word contributes value, 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 tool's simplicity (no parameters, no output schema, no nested objects), the description covers the essential information: what it returns (name, size, shape count) and on what resource (active document). It omits error handling and preconditions, but for a list operation this is a minor gap. The description is sufficient for an agent to call it correctly in most 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?

The tool has zero parameters and the schema is empty with 100% coverage, so there is nothing for the description to add about parameters. Per the baseline rule for 0 parameters, a score of 4 is appropriate—the description correctly avoids irrelevant 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?

The description clearly states a specific verb and resource: 'List all pages in the active Visio document'. It also specifies the returned attributes (name, size, shape count). This distinguishes it from siblings like get_shapes (which lists shapes) and get_document_info (which covers document-level metadata). No ambiguity remains.

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 specifies the context ('active Visio document'), which implies when the tool is appropriate. It does not explicitly mention alternatives or when not to use it, but for a simple list operation with zero parameters, the intended scope is clear. It could improve by noting that it complements get_shapes (for shape details) or requires an open document, but that is minor.

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 only states the action without mentioning whether it is read-only, what happens when nothing is selected, or any side effects. While this is a simple get operation, the lack of any behavioral context leaves gaps.

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, tightly written sentence with no redundant words. It front-loads the verb 'Get' and immediately specifies the resource. Every word contributes to clarity.

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 no parameters and no output schema, the description largely suffices. It names the exact resource and scope. It does not explicitly state the return format (e.g., list of shapes) or behavior on empty selection, but these are minor omissions given the tool's simplicity and the presence of sibling tools that clarify its role.

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

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

The tool takes zero parameters, so the input schema already fully covers them. Per the rubric, a zero-parameter tool gets a baseline of 4, and the description correctly adds no extraneous parameter information. No compensation is needed.

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

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

The description clearly states the action (get) and the resource (shapes currently selected in the active Visio window). It implicitly differentiates from siblings like get_shapes (all shapes) and get_visio_status (status), making its specific 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 when the agent needs selected shapes rather than all shapes, but it does not explicitly name alternatives or provide exclusion criteria. It relies on the reader to infer context from the sibling list, so guidance is implied but not 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?

With no annotations provided, the description must carry the full behavioral burden. It discloses that the tool returns shape attributes, which is useful, but it does not mention behavior such as ordering of results, pagination/limits, the meaning of coordinate units, or what happens on an invalid pageIndex. It is adequate but not rich, giving a 3.

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, efficient sentence that front-loads the verb and resource and then lists the returned attributes. There is no filler, no redundancy, and every clause adds information an agent needs.

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

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

Since there is no output schema, the description appropriately enumerates what is returned (IDs, positions, sizes, text content), which is the key contextual gap for a read tool. It is nearly complete for the agent's call-time needs; the only omissions are minor behavioral details like result ordering, which fall under behavioral transparency and are not critical for invoking correctly.

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

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

Schema coverage is 100%, and the single pageIndex parameter is already fully documented in the schema as a 0-based page index with a default of the first page. The description adds no meaning beyond the schema, so the baseline of 3 applies; it neither compounds nor detracts.

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) with a clear resource (all shapes on a page) and enumerates exactly what is returned (IDs, positions, sizes, text content). This clearly distinguishes it from the sibling mutation tools like add_shape, set_shape_text, move_shape, and delete_shape, which modify shapes rather than read them.

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 guidance is given on when to use this tool versus alternatives, and no sibling tools are named. While get_pages and the shape-mutating tools are functionally distinct, the description does not tell the agent anything about context—such as calling this before move_shape/resize_shape to obtain coordinates, or that it is the read complement to the shape-edit operations.

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 burden. It clearly indicates a read operation via 'Return' and describes the output content. It does not explicitly state non-mutating behavior or error handling, but 'Return' strongly implies a safe query. It adds context about the data format (px @96dpi) which is beyond the schema.

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

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

Two sentences, no wasted words. The first sentence front-loads the primary function and output details; the second gives a clear usage directive. Ideal length and structure.

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 a single parameter and no output schema, the description adequately specifies what is returned (each kind's Visio master, size, styling) and why (build nodes with valid kind values). It could mention behavior on invalid diagram types or explicitly confirm read-only status, but these are minor gaps.

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

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

Schema description coverage is 100%: diagram_type is described as 'Diagram type key, e.g. 'activity' or 'flowchart'.' The description reinforces this with 'for one diagram type' and 'for the chosen type,' but adds no new parameter-level details beyond the schema. Baseline of 3 applies.

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

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

The description clearly states the action ('Return') and the resource ('the full element vocabulary for one diagram type'), and enumerates the specific content (Visio master, default size, default styling). It distinguishes itself from siblings like list_diagram_types by focusing on the vocabulary of a single type rather than the list of types.

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 use case: 'Use this to build nodes with valid kind values for the chosen type.' It explains when to call it, but does not explicitly state when not to use it or name alternatives. This is clear context without 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 must carry full behavioral disclosure. It states it returns version and open document info, but does not specify the return structure, how 'not running' is reported, or whether it has side effects (likely none). The description is partially transparent but lacks critical details about the response format.

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, succinct sentence that front-loads the primary purpose ('Check whether Microsoft Visio is running') and immediately states deliverables. There is no wasted wording or redundancy.

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

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

For a simple 0-parameter status tool without an output schema, the description should specify the exact return shape (e.g., a status code, boolean, or object with version and document fields). It mentions 'version and open document info' but leaves 'open document info' vague, and does not explain behavior if Visio is not running. This is a noticeable gap for an agent to correctly parse the result.

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 the baseline is 4. The description does not need to explain parameters, and the empty schema is consistent. No additional meaning is required.

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 ('Check'), a clear resource ('Microsoft Visio running status'), and what it returns ('version and open document info'). This distinguishes it from siblings like get_document_info, which likely requires a document context. The purpose is 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 does not explicitly mention alternatives or when to use this tool versus others. It implies usage as a pre-check before Visio operations, but this is not stated. No exclusions or prerequisites are given, leaving the agent to infer the appropriate context.

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 clearly implies a read-only listing operation, discloses that the catalog is current ('currently UML Activity and Basic Flowchart'), and describes what each entry contains. No hidden side effects or surprising behavior are suggested.

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 compact sentences with zero filler. The core behavior, current contents, and usage guidance are all present and front-loaded.

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, read-only listing tool, the description is complete: it gives the exact subject of the list, the current available types, and what each returned entry includes. No output schema is needed given the 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?

The tool has zero parameters, so there is no parameter detail for the description to add. The baseline of 4 applies here because semantic risk is minimal and no input guidance is needed.

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

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

States a specific verb ('List') with a resource ('every diagram type this server can build') and even enumerates the current types. This clearly distinguishes it from sibling tools like get_type_vocabulary or analyze_requirement.

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

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

Explicitly states when to use the tool: 'Use this to choose a type when the requirement does not name one.' It does not mention alternatives, but the primary use case is unambiguous and directly actionable.

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 only states the action without mentioning side effects, preconditions (e.g., shape must exist), failure modes, or reversibility. For a mutation tool, this is a significant 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 a single concise sentence that front-loads the core action and coordinate system with no extraneous information. Every word contributes to the 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?

For a simple move operation, the description is minimally adequate, but it lacks context about behavior when pageIndex is omitted (whether the shape moves on its current page), error conditions if the shape doesn't exist, or any other operational details. The absence of an output schema increases the need for description-provided context, which is not met.

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 input schema provides full descriptions for all four parameters, including coordinate meanings and page index. The description adds no new parameter semantics beyond reiterating 'top-left' which is already specified in the schema. The baseline of 3 applies since schema coverage is 100%.

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 ('Move'), a resource ('shape'), and the coordinate system ('top-left coordinates in inches'). It clearly differentiates from sibling tools like add_shape or resize_shape by its focus on repositioning, 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?

No guidance is provided on when to use this tool versus alternatives. The verb implies usage for moving shapes, but there is no explicit mention of selection criteria, exclusions, or references to sibling tools, leaving the agent to infer from context alone.

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 only says 'open', which implies a load operation but does not disclose failure behavior (e.g., missing file), whether the document becomes active, or any side effects. This is minimal and insufficient for a tool with no annotation support.

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-structured sentence with no extraneous content. It directly states the action and the accepted input formats, making it maximally concise and easy to parse.

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 sibling open_visio, the description lacks any distinction or routing guidance, creating ambiguity. It also omits prerequisites like file existence or error handling. While the tool is simple, the lack of differentiation from a similarly named tool makes it incomplete for confident agent selection.

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 already fully documents the filePath parameter with a clear description of the absolute path and file types. The tool description adds no additional parameter semantics, so with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description states a clear verb 'open' with a specific resource 'existing Visio file' and lists accepted formats (.vsdx or .vsd). This distinguishes it from generic actions, but it does not differentiate from the sibling open_visio, which likely overlaps, so a 5 is not warranted.

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 guidance on when to use this tool versus alternatives like open_visio. There is no mention of prerequisites, when opening is appropriate, or any exclusions. An agent would have no basis to choose between this and the similarly named sibling.

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 behavioral burden. It discloses two meaningful behaviors: auto-detection of installation and no-op if already running. However, it does not mention error handling, permissions, or what happens if the path is invalid. For a simple startup tool, this is reasonably transparent and adds value beyond a generic 'start' 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 a single, front-loaded sentence that immediately states the main action, followed by two short behavioral clarifications. There is no wasted wording or irrelevance; it is optimally concise and well structured.

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

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

Given the tool's simplicity—one optional parameter, no output schema, no nested objects—the description provides sufficient context for an agent to call it correctly. It states the action, the auto-detection behavior, and the idempotency. Minor gaps, such as behavior when Visio is not installed or when a provided path fails, do not critically hinder correct usage for a typical agent.

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

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

Schema description coverage is 100% for the only parameter (visioPath). The description adds no additional meaning beyond what the schema already states; the schema already says 'Optional explicit path to VISIO.EXE.' Per the baseline for high coverage, the description earns a neutral 3 without adding new semantics.

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 ('Start Microsoft Visio') and distinguishes this tool from its siblings (which operate on documents) by specifying the resource. The added behavior 'Does nothing if already running' further clarifies its 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 implies when to use it—when you want to start Visio—but provides no explicit guidance about when not to use it or how it compares to alternatives like get_visio_status. The context about auto-detection and idempotency gives some situational context, but no exclusions or alternative routing are mentioned.

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

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

With no annotations, the description carries the full burden and discloses the key behavioral traits: it computes ranks/rows, routes edges through corridors, places guard labels, and preserves manual overrides (explicit x/y and edge waypoints). The override-preservation note is genuinely useful non-obvious behavior. It omits output format and error handling, but the core mutation/computation 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?

A single well-structured sentence, front-loaded with the phase and core action, then detail. It packs ranks/rows, routing, guard-label placement, and manual-override behavior without bloat — efficient but slightly dense in the middle.

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 1-parameter tool with no output schema, the description covers input provenance and behavior well. However, since no output schema exists, the description arguably should describe the return value (the positioned layout structure) and error behavior on invalid specs, which it does not.

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

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

Schema coverage is 100% for the single 'spec' parameter, so baseline is 3. The description adds value by naming the spec's source (analyze_requirement) and elaborating on what the layout computation entails, but it doesn't add format or structural constraints beyond what the schema documents.

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 ('computes') and resource ('a concrete, positioned layout'), and anchors itself as 'PHASE 2 of diagram generation,' which positions it in a pipeline and distinguishes it from siblings like analyze_requirement and design_diagram. An agent can tell exactly what this step does.

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?

'Takes the analysis (or any IR spec)' clearly tells the agent what input to feed it and that it follows analyze_requirement in the pipeline. The phase framing implies sequencing, but no alternative tools are explicitly named nor exclusions stated, so a point is lost.

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 only states the action without revealing side effects (e.g., in-place mutation), error behavior, permissions required, or what happens to existing dimensions. It does not contradict annotations since none exist.

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, concise sentence with no superfluous words. It front-loads the core action and adheres to conciseness principles.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description is too sparse. It omits critical context like whether the shape is modified in place, error handling, and when pageIndex is needed, leaving the agent without sufficient information to confidently invoke the tool.

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

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

Schema coverage is 100% (all parameters have descriptions), so the schema already documents width, height, shapeId, and pageIndex. The description adds no parameter-specific meaning, so the baseline 3 applies.

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

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

The description states a specific action ('resize a shape') and resource, clearly distinguishing it from sibling tools like move_shape or delete_shape. However, it does not explicitly mention that it changes width and height, though the schema implies this. It is clear and adequate.

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 guidance on when to use this tool vs alternatives, no prerequisites (e.g., shape must exist), and no exclusions. An agent must rely solely on the name and schema, leaving usage context unaddressed.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly reveals the two possible return statuses ('resolved' with path, 'needs_download' when not installed) and outlines the internal discovery sequence, giving an agent an accurate model of what to expect. It does not explicitly state that the operation is read-only, but the language implies no mutation.

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

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

The description is two sentences with no filler. The first sentence establishes the tool's purpose and discovery mechanism, and the second defines the return statuses. Every clause adds operational 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?

For a single-parameter tool with no output schema, the description covers the essential behaviors: what it resolves, how it searches, and what it returns in both installed and missing cases. It does not describe the exact shape of the resolved path or any error conditions, but these are minor given 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?

The only parameter, diagram_type, is already fully described in the schema with a concrete example ('activity' or 'flowchart'). The description adds no additional semantic meaning beyond restating that a diagram type has masters. With 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Resolve') and a specific resource ('which installed Visio stencil supplies a diagram type's masters'). It clearly distinguishes this from sibling tools like list_diagram_types or get_visio_status by focusing on stencil resolution rather than diagram types or Visio process status.

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 tool's discovery order ('discovery-first: running docs -> candidate files -> master index') but does not specify when to use this tool versus alternatives. No mention of conditions like 'use before add_shape' or 'use when a stencil may not be installed' is provided.

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 behavioral disclosure burden. It only states 'save' without explaining overwrite behavior (the overwrite parameter defaults to false, which is critical), potential failure scenarios, or that saving in place modifies the existing file. This is a significant gap 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?

One concise sentence that front-loads the primary action and immediately communicates the optional path. There is no wasted verbiage, making it easy to scan and understand.

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 two optional parameters and no annotations, the description is passable but misses essential behavioral context. It doesn't explain the overwrite default behavior, when saving in place is acceptable, or what happens if the file already exists. For a simple tool, this is a moderate gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal new meaning: it reiterates the filePath purpose ('optionally save to a new path') but does not clarify the overwrite parameter or any constraints. It provides no additional clarity beyond 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 states a specific verb ('Save') and a definite resource ('the active Visio document'), and distinguishes itself from siblings like export_document by clarifying it saves rather than exports. The optional path nuance adds precision 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 makes the core use case clear: save the active document, optionally to a new path. It doesn't explicitly mention when not to use it or name alternatives, but the context is unambiguous and the verb 'save' naturally separates it from other document operations.

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 action ('set or replace') but provides no additional context: no mention of write effects, error handling, reversibility, or what happens if the shape doesn't exist. The description is too thin to inform the agent about side effects beyond the basic mutation.

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, clear sentence with zero redundancy. It is appropriately sized for the tool's simplicity and front-loaded with the main action. No filler or unnecessary detail; it 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?

Given that this is a mutation tool with no annotations and no output schema, the description is overly sparse. It fails to provide context about typical use cases, relationships to sibling tools (e.g., add_shape), or behavioral nuances (e.g., whether text is appended or replaced). The schema covers parameters, but the description leaves out essential operational context for an agent to use 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?

The schema already fully describes all three parameters with 100% coverage, including the default for pageIndex. The description adds no extra meaning beyond the schema—it simply restates the tool's purpose without clarifying parameter formats, constraints, or special behaviors. Baseline 3 is appropriate since the schema does the heavy lifting.

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 (set or replace) and the resource (text label of a shape). It is specific enough to distinguish from siblings like move_shape or resize_shape, though it doesn't explicitly name alternatives. The verb+resource combination is 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 the tool is for updating a shape's text label, but it offers no explicit guidance on when to use it versus other shape operations, nor does it mention any prerequisites (e.g., shape must exist). There are no exclusions or alternative suggestions, leaving the decision to the agent's 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?

No annotations are provided, so the description carries the full burden. It discloses the types of checks (vocabulary/structure, conditional geometry), the condition (if nodes are positioned), and the return format ({ ok, problems }). It does not mention side effects or error behavior, but for a validation tool 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?

Two sentences with no wasted words. The purpose is front-loaded, and the behavioral details are packed efficiently. It is appropriately sized for the information conveyed.

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 validation tool with a nested object parameter and no output schema, the description covers the input shape, the checks performed, and the return format. It references a prompt for the full shape, which is a reasonable pointer. Missing details like problem format are minor given 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 100%, but the schema's description of 'spec' is vague ('A diagram IR object (see the diagram_from_requirement prompt for the shape)'). The tool description adds meaningful structure by specifying diagram_type/nodes/edges, which goes beyond the schema and clarifies the expected shape.

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

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

The description clearly states the verb 'Validate' and the resource 'diagram spec', and specifies the object shape (IR object with diagram_type/nodes/edges). It distinguishes itself from all siblings, none of which are validation 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 implies usage—you would validate a spec before using it—but does not explicitly state when to use it versus alternatives, nor any exclusions. Since there are no direct sibling validation tools, the context is implicit but not explicit.

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