Render a page

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.