vw2d_preview

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

The description adds behavior annotations do not cover: the output is a rendered image, issues are shown in red and orange, arrows show where vw2d_fix would snap points, and bbox both limits the view and re-runs checks on that area. That last point is a non-obvious but important side effect. The return format and whether points are mutated are not stated; readOnlyHint covers that.

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?

It is short and front-loads the render step, but the telegraphic style ('arrows = where vw2d_fix snap would move a point') and the run-on inventory of two parameters sit awkwardly together. The result is compact but cryptic rather than fully 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?

With 10 optional parameters, no output schema, and no annotation detail beyond read-only, the description is far too thin. Key knobs an agent must set (compare mode, width_px, selection, tolerance_mm, ignore_classes) are left unexplained, so calling this correctly requires guessing.

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% for 10 parameters, so the description has to explain them. It explains only focus_issue and bbox, and even for bbox it gives no units beyond 'document units' and no ordering convention. layer, uuids, compare, width_px, selection, class_name, tolerance_mm, and ignore_classes are never mentioned, so 8 of 10 parameters are undocumented anywhere.

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 concrete verb and resource: it renders a preview image of the geometry with issues annotated. Color-coding and arrow semantics are stated. It does not, however, explicitly frame this as 'the preview counterpart to vw2d_check', so the differentiation from siblings stays implicit.

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?

Two usage scenarios are spelled out: focus_issue zooms to an issue id coming from vw2d_check, and bbox limits the preview to an area. That is real guidance, but it never says when to call this instead of vw2d_check on its own, or when a preview is unnecessary.

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