List open documents

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.