gbif-biodiversity-mcp-server

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

Name	Required	Description	Default
`datasetKey`	Yes	Dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets or an occurrence record.
`contactLimit`	No	Maximum 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

Name	Required	Description
`cap`	No	contactLimit applied when the list was capped. Raise it (max 100) to see more. Absent otherwise.
`doi`	No	DOI for citation. May be absent.
`key`	No	Dataset UUID.
`type`	No	Dataset type (OCCURRENCE, CHECKLIST, etc.).
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Contacts included in this response when the list was capped. Absent otherwise.
`title`	No	Dataset title.
`notice`	No	How to reach the contacts contactLimit held back. Absent when every contact was returned.
`license`	No	License identifier. May be absent.
`contacts`	No	Dataset contacts, capped at contactLimit. Absent when the dataset has no contacts or contactLimit is 0.
`truncated`	No	True when the dataset carries more contacts than contactLimit allowed through. Absent when every contact was returned.
`description`	No	Full dataset description. May be absent.
`recordCount`	No	Occurrence 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.
`citationText`	No	Full citation text for academic reference. May be absent.
`contactsTotal`	No	Total contacts on the dataset before applying contactLimit. Present when the dataset has any contacts.
`numConstituents`	No	Number of constituent sub-datasets. May be absent.
`contactsReturned`	No	Number of contacts included in this response (≤ contactLimit). Present when the dataset has any contacts.
`publishingCountry`	No	Country code of the publishing organization.
`temporalCoverages`	No	Temporal coverage ranges declared by the dataset. May be absent.
`geographicCoverages`	No	Geographic coverage descriptions declared by the dataset. May be absent.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    }
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / cap

Added value: +{
+  "description": "contactLimit applied when the list was capped. Raise it (max 100) to see more. Absent otherwise.",
+  "type": "number"
+}

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The datasetKey UUID does not match any dataset in GBIF. `invalid_filter`: datasetKey is not a UUID, or GBIF rejected the request as malformed. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found",
+            "invalid_filter"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "How to reach the contacts contactLimit held back. Absent when every contact was returned.",
+  "type": "string"
+}

addedOutput schema / properties / shown

Added value: +{
+  "description": "Contacts included in this response when the list was capped. Absent otherwise.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the dataset carries more contacts than contactLimit allowed through. Absent when every contact was returned.",
+  "type": "boolean"
+}

Changed1 schema field changedAug 6, 2026

changedOutput schema / properties / recordCount / description

Previous value: -"Occurrence records GBIF has indexed for this dataset, matching the figure gbif_search_datasets reports. Fetched separately for OCCURRENCE datasets because the detail endpoint omits it; absent for other dataset types and when that lookup does not return in time."New value: +"Occurrence 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."

Changed2 schema fields changedAug 6, 2026

changedInput schema / properties / datasetKey / description

Previous value: -"Dataset UUID from gbif_search_datasets or an occurrence record."New value: +"Dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets or an occurrence record."

changedOutput schema / properties / recordCount / description

Previous value: -"Number of records in the dataset. May be absent."New value: +"Occurrence records GBIF has indexed for this dataset, matching the figure gbif_search_datasets reports. Fetched separately for OCCURRENCE datasets because the detail endpoint omits it; absent for other dataset types and when that lookup does not return in time."

Changed2 schema fields changedJul 13, 2026

addedOutput schema / properties / geographicCoverages

Added value: +{
+  "description": "Geographic coverage descriptions declared by the dataset. May be absent.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A geographic coverage entry.",
+    "properties": {
+      "description": {
+        "description": "Geographic coverage description (e.g. \"Worldwide\"). May be absent.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / temporalCoverages

Added value: +{
+  "description": "Temporal coverage ranges declared by the dataset. May be absent.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A temporal coverage range.",
+    "properties": {
+      "end": {
+        "description": "Coverage end as an ISO 8601 date-time. May be absent.",
+        "type": "string"
+      },
+      "start": {
+        "description": "Coverage start as an ISO 8601 date-time. May be absent.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

Changed4 schema fields changedJun 30, 2026

addedInput schema / properties / contactLimit

Added value: +{
+  "default": 10,
+  "description": "Maximum 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.",
+  "maximum": 100,
+  "minimum": 0,
+  "type": "integer"
+}

changedOutput schema / properties / contacts / description

Previous value: -"Dataset contacts. May be absent."New value: +"Dataset contacts, capped at contactLimit. Absent when the dataset has no contacts or contactLimit is 0."

addedOutput schema / properties / contactsReturned

Added value: +{
+  "description": "Number of contacts included in this response (≤ contactLimit). Present when the dataset has any contacts.",
+  "type": "number"
+}

addedOutput schema / properties / contactsTotal

Added value: +{
+  "description": "Total contacts on the dataset before applying contactLimit. Present when the dataset has any contacts.",
+  "type": "number"
+}

First observedMay 25, 2026

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 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.