diagram_file

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 return contract in detail (text vs. base64 blob, field names), which is valuable, but says nothing about whether the call is read-only, what happens on an invalid path, or any permission/rate constraints. Decent disclosure of output shape, silent on operational behaviour.

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?

Front-loaded with the purpose, then the agent-relevant routing warning, then Args/Returns blocks. Every line earns its place, though the explicit Returns block is partly redundant with the existing output schema.

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 tool with an output schema, the definition covers purpose, the source of the path argument, the exclusion for agents, and the return shape. Only failure/error behaviour and the absence of side effects remain unstated.

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% and the single parameter is bare ('path: string'), so the description must compensate. It does: 'A path from the "files" of a diagram result' tells the agent where the value is sourced from, which is the key semantic an agent needs and is 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?

States a specific verb and resource ('Return a rendered diagram file's contents') and names the consumer ('to the TerraVision view'), which is clearer than most siblings like render_graph or open_diagram_file. It does not explicitly contrast itself against those siblings, so it stops short of a 5.

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?

Gives an explicit 'when' ('Used by the diagram view in chat apps to load the SVG and the graph JSON') and an explicit 'when not' ('Agents do not need it: read the paths in the result yourself'). This directly routes an agent away from the tool and toward an alternative behaviour, which is exactly the guidance dimension's purpose.

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