worms-marine-taxa-mcp-server

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral context: identifiers stay opaque (including leading zeros and LSIDs), no IDs cannot establish taxon absence, IUCN identifiers are not threat categories, and typeTotals separates absence from another-segment IDs. These are meaningful operational caveats beyond the annotations.

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 and every clause carries useful information. It is somewhat dense and semicolon-packed, but there is no obvious filler or repetition.

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?

With an output schema present, the description need not explain return values. It covers the key gaps: selector rules, reverse/forward behavior, pagination resumption, opaque ID handling, and absence semantics.

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 schema already documents the four parameters well. The description still adds value by clarifying selector exclusivity, forward-vs-reverse type behavior, and the meaning of resultOffset as a position across identifier types.

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 description states a specific verb and resource: crosswalk an AphiaID to/from external identifier systems. It also distinguishes the tool from worms_resolve_taxon and worms_list_reference, so an agent can identify its role without opening the 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?

It explicitly says to supply exactly one selector, that type is required for reverse lookup and omitted for forward lookup across all nine types, and that AphiaID comes from worms_resolve_taxon. It also gives pagination guidance for resultOffset and nextResultOffset.

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

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

Beyond the read-only/idempotent annotations, the description discloses non-obvious behavior: missing ranks remain unknown, child filters are inactive without includeChildren, a full 50-row child page has uncertain continuation, and accepted-ID notices distinguish alternative representations. These are meaningful operational caveats for an open-world taxonomic lookup.

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 and the dense pagination details are relevant, but the second and final sentences are long and syntactically complex. It earns its length through operational content, though clearer structure would improve readability.

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?

Given the available output schema, full parameter schema coverage, and safety annotations, the description is complete for correct invocation. It covers the tricky pagination lifecycle and edge cases that an agent would otherwise likely mishandle.

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 adds real value by explaining that resultOffset indexes lineage first and then fetched children, and by clarifying the interaction between nextResultOffset, page.nextOffset, and resetting resultOffset.

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 description states a specific verb and resource: retrieve root-to-tip classification and optional direct children for an AphiaID or LSID. It clearly distinguishes what data is returned, though it does not explicitly contrast itself with sibling tools such as worms_get_taxon or worms_get_synonyms.

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 explains pagination mechanics but does not state when to use this tool instead of alternatives like worms_get_taxon, worms_get_synonyms, or worms_get_traits. It also omits the prerequisite, present only in the schema, that the AphiaID should come from worms_resolve_taxon.

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

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

Annotations cover safety (readOnly/openWorld/idempotent), and the description goes well beyond them: byte-budgeted segmentation, the exact resumption order between nextResultOffset and synonymOffset, the 10-synonym-per-call cap, duplicate retention and source ordering, and the caveat that zero rows does not prove absence. That is unusually rich behavioral disclosure.

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 core purpose and pagination contract are front-loaded and nearly every clause carries unique information. Sentences are long and multi-clause, which costs readability slightly, but there is little filler.

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-format explanation is unnecessary, yet the description still explains the pagination cursors, filter semantics, synonym union behavior and the misleading-empty-result caveat. Nothing an agent needs to call this 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?

Schema coverage is 100%, so the 3 baseline is already met; the description adds real value by contrasting recordStatus normalization (case and whitespace trimmed) against the other filters' untrimmed case-insensitive whole-value matching, and by spelling out the two-offset advancement sequence. It still defers observed filter values to worms_list_reference rather than defining them.

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 and resource (retrieve recorded distributions) plus the accepted identifier forms, which clearly separates it from get_traits, get_synonyms and get_classification. It does not explicitly name a sibling alternative, so it falls short of a 5.

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?

It gives a clear rule for when to set includeSynonyms (WoRMS attaches records per name usage, so synonym rows are otherwise missed) and a precise resume protocol. It offers no explicit when-not-to-use or sibling routing guidance beyond the AphiaID requirement.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds genuinely non-obvious behavior: 50-row paging, empty pages, and uncertain continuation on a full page. The offset/resultOffset interplay is stated but in dense, hard-to-parse prose that stops short of explaining why the two offsets differ.

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?

Four sentences, front-loaded with the core purpose and no filler. The second sentence is jargon-heavy ('Consume nextResultOffset within the same upstream offset...') and costs more parse effort than its length suggests.

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, and the description covers the ingestion path, the no-accepted-ID case, and the paging edge case. What remains unaddressed is why two offset parameters coexist, which is the one thing an agent is most likely to get wrong.

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 an extra point by explaining the relationship between resultOffset and the upstream offset, which the schema documents only in isolation. It does not, however, clarify the syntax of the ID forms beyond what the schema already spells out.

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 (retrieve) and resource (synonyms) tied to a precise input (an AphiaID from worms_resolve_taxon), and implicitly distinguishes itself from worms_get_taxon, which is named for the contrasting case. An agent can tell what this returns without opening the 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?

Gives an explicit exclusion ('A present name without an accepted ID has no synonym lookup') plus the alternative to use instead (worms_get_taxon), and prescribes a pagination protocol ordering nextResultOffset consumption ahead of advancing page.nextOffset. Both when-to-use and when-not-to-use are covered.

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

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

Well beyond the readOnly/idempotent annotations, it discloses segment budgeting, the one-of-two-per-call restriction, filter-before-offset ordering, and partial-failure behavior ('retains the record without source counts; unknown facts remain omitted or null'). The phrasing is compressed enough that the failure/count semantics take effort to parse, which keeps it from a 5.

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 the first sentence and every subsequent sentence carries real information about offsets, filters, or failure modes. Some sentences are over-compressed into jargon ('sourceUse filters whole use values ignoring case before sourceOffset'), which costs readability for a complex contract.

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 7-parameter tool with an output schema, the description covers the hard parts: chunking, unchanged-resubmission rule, conditional option constraints, filter ordering, and degraded-failure results. Missing only the explicit routing versus sibling tools such as worms_get_synonyms and worms_get_traits.

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, and the description earns above that by adding cross-parameter semantics the schema cannot express: inputIndex preserves duplicate and missing positions, sourceUse matching is case-insensitive on whole values and untrimmed, and offsets resume against the filtered list. It does not restate defaults or types.

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 sentence gives a specific verb and resource ('Retrieve full Aphia records') plus the accepted identifier forms and the segmented-fetch framing. 'Full Aphia records' implicitly separates it from narrow siblings like worms_get_synonyms or worms_get_distributions, but no sibling is ever named, so differentiation is inferred rather than stated.

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?

Strong invocation guidance: it states the resumption recipe (nextInputOffset as inputOffset with unchanged aphiaIds/options), the one-ID requirement for includeVernaculars/includeSources, and that the two cannot be combined. It stops short of telling the agent when to pick this tool over the sibling retrieval tools.

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

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

Annotations establish read-only, idempotent, open-world behavior, and the description adds substantial behavioral detail beyond them: inherited-attribute semantics, stable preorder indices across pages, measurementType subtree/ancestor retention, totalCount versus unfilteredCount, synonym attribute inclusion with inheritedFrom markers, and caveats about missing traits and IUCN list membership.

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 description is dense but front-loads the core purpose and avoids filler. Each sentence carries operational information, though some later sentences are packed with multiple caveats and could be easier 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?

With an output schema available, the description does not need to explain return values; it instead covers behavior, filtering, pagination, inheritance, and important interpretive caveats. The definition is complete enough for an agent to invoke the tool correctly.

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?

Although schema coverage is already 100%, the description adds meaning beyond the schema by explaining how resultOffset resumes from nextResultOffset, how measurementType preserves matching nodes with subtrees and ancestors, how counts are affected, and how includeInherited interacts with synonym attributes.

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 description states a specific verb and resource: retrieving recorded attributes for an AphiaID or canonical WoRMS LSID, with inherited attributes included by default. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as worms_get_taxon or worms_get_classification.

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 gives concrete operational guidance for resuming pagination and for using measurementType, and points to worms_list_reference for trait type names. However, it does not state when to choose this tool over the other trait/taxon siblings or describe exclusions.

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

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.

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds real caveats beyond them: full 50-match upstream groups are completeness-unknown, and accepted-name fields do not disambiguate an ambiguous match. Those are non-obvious result-integrity warnings an agent would otherwise miss.

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, but the body is a single dense block of run-on clauses dense with internal jargon (inputOffset, nextMatchOffset, partialGroup) that is never unpacked. It is information-rich but poorly structured for an agent scanning under time pressure.

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?

With an output schema present, return values need not be described, and the description still covers the resume protocol, completeness caveat, and ambiguity caveat. Only the unexplained output-side identifiers (inputIndex, partialGroup, nextResultOffset) keep it from being fully self-contained.

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 baseline is 3; the description earns above that by explaining the cross-parameter pagination protocol (consume nextResultOffset within the same upstream offset before advancing page.nextOffset and resetting resultOffset) and the meaning of inputIndex/partialGroup, which are not derivable from the input schema alone.

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?

Starts with a specific verb+resource: "Resolve exact or explicitly fuzzy scientific names, or search one vernacular name...", which distinguishes this from worms_get_taxon or worms_get_synonyms. The dual mode (scientific list vs. single vernacular) is stated, though the second half of the sentence is tangled enough that an agent must re-read to parse it.

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?

Gives in-tool usage constraints (names vs. vernacular mutual exclusivity, vernacular cannot filter, scientific names accept only offset 1), which is genuinely useful. However it never says when to choose this tool over siblings like worms_get_taxon or worms_crosswalk_id, so the alternatives guidance is only implied.

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