worms-marine-taxa-mcp-server

Worms Get Distributions

worms_get_distributions

Read-onlyIdempotent

Retrieve recorded distributions for an AphiaID or canonical WoRMS LSID in byte-budgeted segments; resume nextResultOffset as resultOffset with unchanged selectors and filters. WoRMS attaches records to individual name usages, so one AphiaID's rows can miss those of its synonyms: includeSynonyms combines the accepted taxon's rows with those of up to 10 synonyms per call, each row tagged sourceAphiaId; consume nextResultOffset before advancing synonymOffset to synonymUnion.nextSynonymOffset with resultOffset 0. Filters apply to the complete fetched set before pagination and combine by conjunction: recordStatus normalizes case and surrounding whitespace before exact matching; others use case-insensitive whole-value equality without trimming. Rows retain duplicates and source order; no rows does not prove biological or taxon absence. A notice names the linked accepted ID, distinguishing an accepted alternative representation from its preferred ID.

Input Schema

Name	Required	Description
`aphiaId`	Yes	Positive safe-integer AphiaID, decimal string, or canonical urn:lsid:marinespecies.org:taxname:<AphiaID>; outputs remain numeric.
`occurrence`	No	Case-insensitive whole-value occurrence filter, such as Established; blank omitted. Observed values: worms_list_reference topic: distribution_terms.
`invasiveness`	No	Case-insensitive whole-value invasiveness filter, such as Invasive; blank omitted. Observed values: worms_list_reference topic: distribution_terms.
`recordStatus`	No	Record status valid, doubtful, or inaccurate; ignores case and surrounding whitespace; blank means no filter.
`resultOffset`	No	Zero-based local position; resubmit unchanged selectors and options.
`synonymOffset`	No	Zero-based synonym position; once nextResultOffset is null, resubmit synonymUnion.nextSynonymOffset here with resultOffset 0. Inactive without includeSynonyms.
`includeSynonyms`	No	Combine the accepted taxon's records with its synonyms', 10 synonyms per call; rows then carry sourceAphiaId.
`establishmentMeans`	No	Case-insensitive whole-value establishment filter, such as Alien; blank omitted. Observed values: worms_list_reference topic: distribution_terms.

Output Schema

Name	Required	Description
`echo`	No	Only effective filters; recordStatus is canonical lowercase, other populated values are unchanged.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Linked accepted/preferred-AphiaID and empty-evidence guidance, in that order.
`aphiaId`	No	Positive safe-integer AphiaID; obtain from worms_resolve_taxon.
`byteBudget`	No	Complete serialized response byte target.
`totalCount`	No	Known local sequence length before pagination.
`attribution`	No	WoRMS source attribution.
`statusError`	No	Failed taxonomic-status read; evidence is unaffected, but whether the AphiaID is its accepted name is unknown.
`resultOffset`	No	Zero-based starting position in the complete local sequence.
`synonymUnion`	No	Synonym union window; present only with includeSynonyms.
`budgetLimited`	No	Whether the byte budget ended this local page early.
`distributions`	No	Whole matching rows in this segment, in source order.
`filteredCount`	No	Rows passing every effective filter.
`oversizedItem`	No	One indivisible scientific item exceeds the target; retained intact with forward progress.
`requiredBytes`	No	Serialized paired-surface result bytes for an oversized item, excluding transport-added metadata.
`returnedCount`	No	Whole scientific items returned on this segment.
`unfilteredCount`	No	All recorded rows before filtering; with includeSynonyms, those of this window.
`nextResultOffset`	No	Next local position; null when consumed.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 24, 2026

TDQS

A4.3/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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.

All worms-marine-taxa-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.