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

Annotations already cover readOnly/idempotent/openWorld, and the description goes well beyond them: it separates offline-available topics (identifier codes, statuses, environment flags, distribution terms) from live ones (ranks, trait definitions), discloses that trait definitions keep complete-tree preorder indices across pages with parents possibly on earlier pages, and warns that null flags mean not recorded and IUCN identifiers are not threat categories.

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?

Topic enumeration and pagination contract are front-loaded and every clause carries information, but the prose is dense and run-on, and the offline-availability sentence partially restates what the topic list already implies. It is efficiently sized for six topics plus pagination caveats, just not easy to scan.

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 need not be described, and the description covers all six topics, the paging invariant, and the semantic traps (null flags, IUCN codes, status granularity). What is missing is only minor: page-size behavior and a hint about which sibling tool consumes each topic.

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% with an enum on topic, so the baseline is 3; the description adds meaning beyond the schema by characterizing what each topic yields and by clarifying how statuses may be expressed ('junior subjective synonym' rather than 'unaccepted'). It also explains the offset contract (resubmit unchanged selectors and options), though it never states how large pages are.

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?

Names a specific verb (list) and resource (reference vocabularies), then enumerates the exact topic set that maps one-to-one onto the schema enum (external identifier systems, taxonomic-status guide, environment-flag semantics, distribution filter values, ranks, trait definitions). An agent can tell this is a lookup-of-controlled-vocabulary tool and distinguish it from siblings like worms_get_taxon or worms_get_traits, which return data rather than definitions.

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 pagination instruction ('Resume nextResultOffset as resultOffset with the same topic') is real usage guidance, and naming worms_get_distributions ties one topic to a concrete consumer. But there is no explicit statement of when to reach for this tool versus its siblings, nor prerequisites or exclusions — the when-to-use is left to inference from the topic enumeration.

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