compare_volumes

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: both fields are 'sampled on a grid over field's box', and 'the first band's field_total is what is inside' hints at the result structure. It still omits cost, whether it cooks upstream geometry, and permissions/side-effects, so it is adequate but incomplete.

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?

Purpose is front-loaded in one line, followed by the example and then the argument list. The example is a bit wordy but earns its place by disambiguating a niche concept; nothing is redundant.

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 five-parameter compute tool with no annotations, no output schema, and 0% schema coverage, the description covers every parameter plus an illustrative result ('field_total'). The remaining gap is the overall shape of the return value and performance characteristics, which are minor for this tool class.

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%, so the description must compensate, and it largely does: all five parameters are annotated in the Args block, including the dual meaning of bands ('Band count, or a list of band edges') and against_node's conditional role ('when not node_path'). This meaningfully exceeds the bare schema anyOf types, though edge-ordering semantics could be spelled out further.

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 opening line states a specific operation – binning one field's totals by the bands of another field – and the density-vs-collider example makes the abstract verb concrete. It's clearly distinguishable from neighbors like sample_volume and get_volume_info, though it never names them, so differentiation is implicit 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?

The worked example ('how much density is inside the collider') shows one scenario where this tool applies, which gives implied usage. However it never states when not to use it, nor points to alternatives like sample_volume for single-point queries, leaving the agent to infer the boundary.

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