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

Annotations only give readOnlyHint=true and idempotentHint=false; the description goes well beyond them, disclosing that rows are capped at 20 with paging, that refs can be null, that grip may be null with grip_reason 'stale' when the model moved on, that measure/section may be null, that axis_parallel=false blocks render_view and draw_section, and that values are in project metres. With no output schema, this return-shape disclosure carries real weight, though it is delivered as an undifferentiated wall rather than structured sections.

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 content is front-loaded, but it is one enormous run-on sentence chain stitched with semicolons, parentheticals and nested asides ('refs (what each click hit: kind element|point|edge|face, guid, point; at a point, edge or face also grip: ...)'). Important operational facts like the 20-row cap and the metres unit are buried mid-stream, making the definition hard to parse on first read.

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 zero-argument, read-only tool with no output schema, the description covers the return payload unusually thoroughly: set membership rules, non-element targets, refs/grip/snap semantics, measure, section planes, units and paging. Gaps are minor - it does not say what an empty selection returns or whether the snapshot is taken at call time - but nothing critical for calling it correctly is missing.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does confirm that no filter arguments exist and that paging is done through find_elements instead, which is a small useful addition.

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?

It states a concrete resource and scope: 'What the human selected in the viewer, fixed as a set', and clarifies the set is a snapshot so a write against it hits exactly those elements. That distinguishes it from get_element (one element) and find_elements (model query), though it never names those siblings as alternatives, so the differentiation is inferable rather than explicit.

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?

Usage is implied rather than stated: it says the set 'reads in pages with find_elements filter.set (next)', which is a useful hand-off, but there is no explicit 'use this when the human picked something in the viewer; use cast_ray instead when you need to probe geometry'. The agent must infer the when-to-use from the surrounding text.

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