read_visual_artifact

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 usefully discloses that the tool returns an MCP image content block and constrains input to 'safe PNG'. However, it does not explain what 'safe' means, how unsafe files are handled, or what errors or limitations may occur.

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, front-loaded sentence that states the action, the input type, and the output format. There is no wasted text or irrelevant 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?

Although an output schema exists, the description is incomplete for a tool with two required parameters at 0% schema coverage. Key contextual information is missing: how to obtain valid artifact paths, what 'artifact_dir' means, what 'safe' implies, and when to prefer this tool over 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?

Schema description coverage is 0%, and the description does not explain the roles of 'path' and 'artifact_dir'. The word 'PNG' hints that 'path' should point to a PNG file, but there is no clarification of how the two required parameters relate or what values are expected.

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 ('Read') and a specific resource ('one safe PNG'), and clearly states the output form ('MCP image content block'). It is easy to distinguish from siblings like list_visual_artifacts and read_visual_report because it targets a single image artifact rather than a listing or report.

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 about when to use this tool versus alternatives. It does not mention that list_visual_artifacts should probably be used to discover valid paths, nor does it differentiate itself from read_visual_report or compare_visual_runs. The usage context is only implied by the tool name and description.

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