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), temporal/geographic coverage, and the publishing organization key, which gbif_search_datasets takes as publishingOrg. 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

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

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 contacts held back, or requested/applied values when contactLimit was clamped. Absent when neither applies.
`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.
`recordCountNotice`	No	Explains an unavailable supplementary count and how to retry. Absent after a successful lookup or a declared count.
`temporalCoverages`	No	Temporal coverage declared by the dataset, preserving supplied dates and verbatim periods. May be absent.
`geographicCoverages`	No	Geographic coverage descriptions declared by the dataset. May be absent.
`temporalCoverageNotice`	No	Discloses unsupported or unusable temporal entries omitted from the response. May be absent.
`publishingOrganizationKey`	No	UUID of the organization that published the dataset. Pass it to gbif_search_datasets as publishingOrg for every dataset this organization published; gbif_search_datasets rows also carry the organization's name. Absent when GBIF omits it.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 1, 2026

addedOutput schema / properties / publishingOrganizationKey

Added value: +{
+  "description": "UUID of the organization that published the dataset. Pass it to gbif_search_datasets as publishingOrg for every dataset this organization published; gbif_search_datasets rows also carry the organization's name. Absent when GBIF omits it.",
+  "type": "string"
+}

Changed10 schema fields changedOct 24, 2026

changedInput schema / properties / contactLimit / maximum
```
Previous value: -100New value: +9007199254740991
```

changedOutput schema / properties / notice / description

Previous value: -"How to reach the contacts contactLimit held back. Absent when every contact was returned."New value: +"How to reach contacts held back, or requested/applied values when contactLimit was clamped. Absent when neither applies."

addedOutput schema / properties / recordCountNotice

Added value: +{
+  "description": "Explains an unavailable supplementary count and how to retry. Absent after a successful lookup or a declared count.",
+  "type": "string"
+}

addedOutput schema / properties / temporalCoverageNotice

Added value: +{
+  "description": "Discloses unsupported or unusable temporal entries omitted from the response. May be absent.",
+  "type": "string"
+}

changedOutput schema / properties / temporalCoverages / description

Previous value: -"Temporal coverage ranges declared by the dataset. May be absent."New value: +"Temporal coverage declared by the dataset, preserving supplied dates and verbatim periods. May be absent."

changedOutput schema / properties / temporalCoverages / items / description

Previous value: -"A temporal coverage range."New value: +"A temporal coverage range, single date, or verbatim period."

addedOutput schema / properties / temporalCoverages / items / properties / @type

Added value: +{
+  "description": "GBIF coverage representation: range, single, or verbatim. May be absent on legacy ranges.",
+  "type": "string"
+}

addedOutput schema / properties / temporalCoverages / items / properties / date

Added value: +{
+  "description": "Single coverage date as supplied by GBIF. May be absent.",
+  "type": "string"
+}

addedOutput schema / properties / temporalCoverages / items / properties / period

Added value: +{
+  "description": "Verbatim coverage period. May be absent.",
+  "type": "string"
+}

addedOutput schema / properties / temporalCoverages / items / properties / type

Added value: +{
+  "description": "Verbatim period type. May be absent.",
+  "type": "string"
+}

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 declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds genuinely new behavioral context: contacts are capped by contactLimit (default 10) and contactsTotal/contactsReturned report the untruncated count, which an agent could not infer from annotations alone.

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?

Three sentences, front-loaded with the core action, then the returned-field list, then usage routing and the contact-cap caveat. The field enumeration is long but each item is actionable data the caller needs.

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, annotations cover the safety profile, and both parameters are fully documented. The description fills the remaining gaps — provenance use case, sibling relationship, and truncation reporting — so an agent can call this correctly with no further reading.

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. The description adds a cross-tool semantic link the schema does not: the returned publishing organization key is the publishingOrg value gbif_search_datasets accepts, explaining why the agent might call this first.

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?

States a specific verb and resource ('Fetch full dataset metadata by UUID key') and enumerates the returned fields, so the agent knows exactly what comes back. It is clearly distinguishable from gbif_search_datasets, which is named as the discovery counterpart.

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?

Explicitly routes usage: 'Use after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail.' Both entry paths and the alternative tool are named, leaving nothing to inference.

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.