composition_view

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

The annotations already establish safety posture (destructiveHint=false, idempotentHint=true, openWorldHint=false), so the bar is lower. The description nonetheless adds genuine behavioral context beyond them: it refuses selections matching no atoms rather than silently colouring nothing, and it never reads atom properties, which prevents a whole class of misuse. It does not discuss how the render state is otherwise mutated despite readOnlyHint=false, so this is good but not exhaustive.

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 purpose is front-loaded in the first sentence, and the sense-2/sense-1 contrast, provenance rule, and error behavior follow in a logical order. A few clauses restate the same point ("Both statements are true and they answer different questions"), which is mild redundancy in an otherwise dense, waste-free text.

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?

An output schema exists, so return values need no explanation. Given that, the description covers everything an agent needs: what is computed, which data source is required, how to disambiguate from the sibling tool, and how failures are surfaced. Nothing material for correct invocation 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?

Schema coverage is 100%, so the baseline is 3. The description earns a point above baseline by explaining what the numbers in "table" actually mean (a ligand at 40% = 40% of imaged complexes had it bound) and by stressing they must be supplied externally rather than derived from q, which is semantic guidance the schema's format note does not convey.

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?

"Colour parts of a structure by the fraction of particles containing them" gives a specific verb, target, and quantity, and the description immediately pins down which of two occupancy senses is meant. It explicitly distinguishes itself from the sibling occupancy_view, so an agent can route between them without opening either schema.

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 description names the alternative explicitly ("For sense 1, use occupancy_view") and gives the discriminating condition (compositional vs. per-atom crystallographic occupancy). It also states a hard prerequisite — the table must be supplied and is never derived from an atom property — so the agent knows what input is mandatory rather than inferring it.

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