worms-marine-taxa-mcp-server

Worms Get Taxon

worms_get_taxon

Read-onlyIdempotent

Retrieve full Aphia records by numeric IDs or canonical WoRMS LSIDs in byte-budgeted segments. Resume nextInputOffset as inputOffset using unchanged aphiaIds and options; inputIndex preserves duplicate and missing positions. includeVernaculars (common names) or includeSources (original description, basis of record, and other sources) requires one submitted ID, one of the two per call; resume nextVernacularOffset as vernacularOffset or nextSourceOffset as sourceOffset, repeating the full primary record. sourceUse filters whole use values ignoring case before sourceOffset; populated values are not trimmed. Successful source results report sourceTotalCount before slicing and unfilteredSourceCount only with an effective filter. Optional failure retains the record without source counts; unknown facts remain omitted or null.

Input Schema

Name	Required	Description
`aphiaIds`	Yes	Nonempty original AphiaID list, with no total-input ceiling; at most 50 positions fetched per call. Resubmit unchanged with inputOffset, without deduplicating.
`sourceUse`	No	Case-insensitive whole-value source use, such as original description; populated values are not trimmed, blanks omitted. Filters before sourceOffset; inactive without includeSources.
`inputOffset`	No	Zero-based local position; resubmit unchanged selectors and options.
`sourceOffset`	No	Zero-based position in the sourceUse-selected list for the singleton ID; repeat unchanged options. Inactive without includeSources.
`includeSources`	No	Retrieve the taxon sources, such as its original description and basis of record; requires exactly one submitted ID and cannot combine with includeVernaculars.
`vernacularOffset`	No	Zero-based common-name position for the singleton ID; repeat unchanged options. Inactive without includeVernaculars.
`includeVernaculars`	No	Retrieve common names; requires exactly one submitted ID.

Output Schema

Name	Required	Description
`echo`	No	Effective options.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance for deferred work.
`results`	No	One positional result per processed ID.
`byteBudget`	No	Complete serialized response byte target.
`attribution`	No	WoRMS source attribution.
`budgetLimited`	No	Whether the byte budget ended this local page early.
`deferredCount`	No	Number of original ID positions still deferred.
`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.
`nextInputOffset`	No	Resume position in the unchanged original aphiaIds; null when consumed.
`nextSourceOffset`	No	Resume sources for the same singleton record; null when consumed or not requested.
`nextVernacularOffset`	No	Resume common names for the same singleton record; null when consumed or not requested.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 24, 2026

TDQS

A4/5.0

Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines4/5

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.

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.