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

Annotations already establish readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description goes beyond them with real operational context: subject is REQUIRED and the backend 400s without it, and values are ASSUMED volts so µV-native files read 1e6x too large, with the unitsScale fix named. It does not describe cost or latency, but the added caveats are substantial.

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 what the summary contains, then rationale, then hard preconditions. Dense and slightly parenthesis-heavy (the units aside is long), but every sentence carries information an agent needs and 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?

An output schema exists so return structure needn't be explained, and annotations cover the safety profile. The description still supplies the precondition (subject required), the subject-sourcing path, the mode enumeration, and the units pitfall — everything needed to call it correctly the first time.

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, but the description adds meaning beyond the schema: the 400 error consequence of omitting subject, the cohort semantics of a comma-list ('S01,S03'), and the units-scale caveat tied to downstream config. That is a genuine increment over the schema's own text.

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+resource ('Exploratory summary of a public EEG dataset') and enumerates exactly what is produced: channels, sampling rate, trial/class balance, per-channel µV stats, band powers, PSD overview. This distinguishes it from the sibling data.inspect_file, which covers files rather than packed datasets.

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?

Explicitly tells the agent to run it BEFORE building pipelines and gives the reason (class balance drives stratification; flatlined channels signal a montage/reference problem). It also routes to catalog.datasets for the subject list, naming both the when and the alternative source.

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