Skip to main content
Glama

gbif-biodiversity-mcp-server

by io.github.cyanheads

Get Dataset

gbif_get_dataset
Read-onlyIdempotent

Fetch full dataset metadata by UUID key — title, description, citation text, contacts, license, DOI, record count, numConstituents (sub-datasets), and temporal/geographic coverage. Use after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail. Contacts are capped by contactLimit (default 10); contactsTotal and contactsReturned report the full count.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
datasetKeyYesDataset UUID (8-4-4-4-12 hex) from gbif_search_datasets or an occurrence record.
contactLimitNoMaximum number of contacts to include (default 10, max 100). Set to 0 to omit contact detail while still reporting contactsTotal — useful when citation, license, and record count are all you need from a high-contact dataset like eBird.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNocontactLimit applied when the list was capped. Raise it (max 100) to see more. Absent otherwise.
doiNoDOI for citation. May be absent.
keyNoDataset UUID.
typeNoDataset type (OCCURRENCE, CHECKLIST, etc.).
errorNoPresent when the call failed. Absent on success.
shownNoContacts included in this response when the list was capped. Absent otherwise.
titleNoDataset title.
noticeNoHow to reach the contacts contactLimit held back. Absent when every contact was returned.
licenseNoLicense identifier. May be absent.
contactsNoDataset contacts, capped at contactLimit. Absent when the dataset has no contacts or contactLimit is 0.
truncatedNoTrue when the dataset carries more contacts than contactLimit allowed through. Absent when every contact was returned.
descriptionNoFull dataset description. May be absent.
recordCountNoOccurrence records GBIF has indexed for this dataset, matching the figure gbif_search_datasets reports. Spans every occurrenceStatus: absence records — surveys that looked for a taxon and did not find it — are counted alongside sightings, and on some datasets they are the overwhelming majority. gbif_count_occurrences with this datasetKey answers the other question, defaulting to occurrenceStatus PRESENT, so the two figures are expected to differ rather than one being wrong. Fetched separately because the detail endpoint omits it; absent when that lookup does not return in time.
citationTextNoFull citation text for academic reference. May be absent.
contactsTotalNoTotal contacts on the dataset before applying contactLimit. Present when the dataset has any contacts.
numConstituentsNoNumber of constituent sub-datasets. May be absent.
contactsReturnedNoNumber of contacts included in this response (≤ contactLimit). Present when the dataset has any contacts.
publishingCountryNoCountry code of the publishing organization.
temporalCoveragesNoTemporal coverage ranges declared by the dataset. May be absent.
geographicCoveragesNoGeographic coverage descriptions declared by the dataset. May be absent.

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds concrete behavioral detail: contacts are capped by contactLimit (default 10), and contactsTotal/contactsReturned report the full count. This goes beyond the annotations and gives the agent expectations about pagination-like behavior, earning a strong score above baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence front-loads the core purpose and main fields; the second provides usage context and the contact cap nuance. Every word earns its place, well-structured for quick comprehension.

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?

Given the output schema exists (noted in signals), the description needn't detail return structure, and it doesn't. It covers what metadata is returned, when to use it, and the contactLimit behavior. For a 2-parameter tool with full schema coverage, this is complete and leaves no obvious information gap for the agent.

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 description coverage is 100%, so both parameters are documented in the schema. However, the description adds value for contactLimit by explaining the 'set to 0' use case and its trade-off (omit contact detail while still reporting contactsTotal), which is not in the schema. It also reinforces datasetKey's source (from search or occurrence record), matching the schema but reaffirming context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches full dataset metadata by UUID key, listing specific fields (title, description, citation, contacts, license, DOI, record count, etc.). It distinguishes itself from sibling tools by explicitly mentioning it is used after gbif_search_datasets or when provenance detail is needed, making it unambiguous which tool this is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'Use after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail.' It implicitly excludes searching/finding datasets (that's gbif_search_datasets) and occurrence-level retrieval (gbif_get_occurrence), providing clear contextual routing without being verbose.

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

All gbif-biodiversity-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0
Disambiguation5/5

Each tool targets a distinct action and resource pair: matching (single and batch), retrieving species details, hierarchy traversal, searching occurrences, counting, aggregating by facets, and searching datasets/publishers. There is no functional overlap or ambiguity between tools.

Naming Consistency4/5

The naming is largely consistent with the gbif_ prefix followed by a verb and noun (e.g., gbif_match_species, gbif_count_occurrences, gbif_get_dataset). However, a few tools use a search_<noun> pattern (e.g., gbif_search_datasets) and one uses a noun phrase without a verb (gbif_occurrence_facets), introducing a minor inconsistency.

Tool Count5/5

13 tools is well within the optimal range for a domain-specific API. The tools cover taxonomy resolution, species lookup and hierarchy, occurrence search/count/aggregation, and dataset/publisher discovery—no unnecessary bloat or sparse coverage.

Completeness4/5

The surface covers the core GBIF workflows: match → search/get occurrences, get species details and classification, and find datasets/publishers. Missing bulk download is explicitly acknowledged and not served by this tool, and searching datasets by taxon is indirect (via occurrence datasetKey), but these are workable gaps rather than blockers.

Resources