gbif-biodiversity-mcp-server

Match Species Name

gbif_match_species

Read-onlyIdempotent

Match a scientific name against the GBIF backbone taxonomy. Returns the best-matching taxon with full classification and a confidence score (0–100). This is the mandatory first step for any GBIF workflow — it returns the backbone taxonKey required by gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets. When the name GBIF matched is a synonym — the queried name, or the higher taxon a HIGHERRANK match falls back to — taxonKey is the accepted taxon it resolves to and matchedTaxonKey carries the synonym's own key; occurrence counts differ sharply between the two, so pass taxonKey. matchType HIGHERRANK is GBIF's label for a match made at a higher rank: a misspelled or unknown species falls back to its genus or even its kingdom, at a confidence that can exceed 90, and a bare genus name carries the label too, matched as that genus. taxonKey then covers that whole taxon, or its accepted taxon when it is a synonym, and a notice names it. Below confidence 80, the match should be reviewed. matchType NONE means no usable match was found — try removing the strict flag or broadening the name; when GBIF reports several equal matches, as for a genus name shared by an animal and a plant, set kingdom to pick one.

Input Schema

Name	Required	Description
`name`	Yes	Scientific name to match. Examples: "Parus major", "Agaricus bisporus", "Homo sapiens". Fuzzy matching handles minor spelling variations. Common names are not supported — use gbif_search_species for vernacular name searches.
`rank`	No	Expected taxonomic rank. Use to avoid matching a genus when you expect a species.
`strict`	No	When true, only return an exact match. When false (default), GBIF applies fuzzy matching — useful for minor spelling variations and abbreviated names.
`kingdom`	No	Narrow the match to a specific kingdom (e.g., "Animalia", "Plantae", "Fungi") to disambiguate names that appear in multiple kingdoms. Omit the field to match against the whole backbone — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the undisambiguated match, which is indistinguishable from a match that honored the kingdom.

Output Schema

Name	Required	Description
`rank`	No	Taxonomic rank of the matched taxon.
`class`	No	Class of the matched taxon.
`error`	No	Present when the call failed. Absent on success.
`genus`	No	Genus of the matched taxon.
`order`	No	Order of the matched taxon.
`family`	No	Family of the matched taxon.
`notice`	No	Guidance when matchType is HIGHERRANK — naming the taxon and rank GBIF matched and what taxonKey covers — or when the matched name was a synonym and taxonKey was resolved to the accepted taxon. A higher-rank match on a synonym carries both. Absent on an EXACT or FUZZY match of an accepted name.
`phylum`	No	Phylum of the matched taxon.
`status`	No	Taxonomic status: ACCEPTED, SYNONYM, or DOUBTFUL.
`kingdom`	No	Kingdom of the matched taxon.
`species`	No	Species canonical name of the matched taxon.
`classKey`	No	Backbone taxon key for the class.
`genusKey`	No	Backbone taxon key for the genus.
`orderKey`	No	Backbone taxon key for the order.
`taxonKey`	No	GBIF backbone taxon key to pass to downstream tools. The accepted taxon's key when the name GBIF matched is a synonym, otherwise the matched taxon's own key.
`familyKey`	No	Backbone taxon key for the family.
`matchType`	No	EXACT, FUZZY, HIGHERRANK, or NONE. HIGHERRANK means GBIF matched at a higher rank — a misspelled species falls back to its genus or kingdom, and a bare genus name carries it too — and taxonKey covers that whole taxon, or its accepted taxon when it is a synonym. NONE means no usable match.
`phylumKey`	No	Backbone taxon key for the phylum.
`confidence`	No	Match confidence score 0–100. Below 80 warrants review. A HIGHERRANK match can score above 90, so read matchType too.
`kingdomKey`	No	Backbone taxon key for the kingdom.
`speciesKey`	No	Backbone taxon key for the species.
`canonicalName`	No	Scientific name without authorship.
`scientificName`	No	Full scientific name with authorship.
`matchedTaxonKey`	No	Backbone key of the name that actually matched. Present only when it differs from taxonKey — that is, when a synonym was resolved to its accepted taxon.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedNov 1, 2026

changedOutput schema / properties / confidence / description

Previous value: -"Match confidence score 0–100. Below 80 warrants review."New value: +"Match confidence score 0–100. Below 80 warrants review. A HIGHERRANK match can score above 90, so read matchType too."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_match`: matchType is NONE — no candidate met the match threshold. `invalid_filter`: kingdom was supplied blank or whitespace-only, which disambiguates nothing. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_match`: matchType is NONE — no candidate met the match threshold, or several equal candidates tied; the message then carries GBIF's note. `invalid_filter`: kingdom was supplied blank or whitespace-only, which disambiguates nothing. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / matchType / description

Previous value: -"EXACT, FUZZY, HIGHERRANK, or NONE. NONE means no usable match."New value: +"EXACT, FUZZY, HIGHERRANK, or NONE. HIGHERRANK means GBIF matched at a higher rank — a misspelled species falls back to its genus or kingdom, and a bare genus name carries it too — and taxonKey covers that whole taxon, or its accepted taxon when it is a synonym. NONE means no usable match."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when the queried name was a synonym and taxonKey was resolved to the accepted taxon. Absent when the matched name is already the accepted one."New value: +"Guidance when matchType is HIGHERRANK — naming the taxon and rank GBIF matched and what taxonKey covers — or when the matched name was a synonym and taxonKey was resolved to the accepted taxon. A higher-rank match on a synonym carries both. Absent on an EXACT or FUZZY match of an accepted name."

changedOutput schema / properties / taxonKey / description

Previous value: -"GBIF backbone taxon key to pass to downstream tools. The accepted taxon's key when the queried name is a synonym, otherwise the matched taxon's own key."New value: +"GBIF backbone taxon key to pass to downstream tools. The accepted taxon's key when the name GBIF matched is a synonym, otherwise the matched taxon's own key."

Changed5 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 / 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: `no_match`: matchType is NONE — no candidate met the match threshold. `invalid_filter`: kingdom was supplied blank or whitespace-only, which disambiguates nothing. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_match",
+            "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"
+}

Changed1 schema field changedAug 7, 2026

changedInput schema / properties / kingdom / description

Previous value: -"Narrow the match to a specific kingdom (e.g., \"Animalia\", \"Plantae\", \"Fungi\") to disambiguate names that appear in multiple kingdoms."New value: +"Narrow the match to a specific kingdom (e.g., \"Animalia\", \"Plantae\", \"Fungi\") to disambiguate names that appear in multiple kingdoms. Omit the field to match against the whole backbone — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the undisambiguated match, which is indistinguishable from a match that honored the kingdom."

Changed3 schema fields changedAug 6, 2026

addedOutput schema / properties / matchedTaxonKey

Added value: +{
+  "description": "Backbone key of the name that actually matched. Present only when it differs from taxonKey — that is, when a synonym was resolved to its accepted taxon.",
+  "type": "number"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when the queried name was a synonym and taxonKey was resolved to the accepted taxon. Absent when the matched name is already the accepted one.",
+  "type": "string"
+}

changedOutput schema / properties / taxonKey / description

Previous value: -"GBIF backbone taxon key. Use this in downstream tools. Absent when matchType is NONE."New value: +"GBIF backbone taxon key to pass to downstream tools. The accepted taxon's key when the queried name is a synonym, otherwise the matched taxon's own key."

Changed1 schema field changedJun 30, 2026

changedOutput schema / properties / matchType / description

Previous value: -"EXACT, FUZZY, HIGHERORDER, or NONE. NONE means no usable match."New value: +"EXACT, FUZZY, HIGHERRANK, or NONE. NONE means no usable match."

First observedMay 25, 2026

TDQS

A4.6/5.0

Behavior5/5

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

The annotations already declare readOnly, openWorld, and idempotent behavior, and the description adds substantial context beyond them: confidence scores, synonym handling, HIGHERRANK fallback behavior, the difference between taxonKey and matchedTaxonKey, and the threshold for reviewing matches. Nothing contradicts the annotations.

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 description is front-loaded with purpose, required use, and downstream dependencies, and each section addresses a distinct behavior. It is still dense and could be tightened, but the length is justified by the tool's complex match semantics.

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, annotations, and four parameters, the description covers everything an agent needs: mandatory workflow role, confidence interpretation, synonym and HIGHERRANK behavior, failure handling, and disambiguation. No critical behavioral or routing information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents name, rank, strict, and kingdom, including the rejection of blank kingdom values. The description adds contextual advice about when to remove strict or set kingdom, but it does not materially deepen parameter semantics beyond what the schema provides.

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 says it matches a scientific name against the GBIF backbone and returns the best-matching taxon with classification and confidence. It also distinguishes this tool from siblings by naming gbif_search_occurrences, gbif_count_occurrences, gbif_occurrence_facets, and gbif_search_species as downstream or alternative tools.

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?

It explicitly says this is the mandatory first step for any GBIF workflow and names the tools that require the resulting taxonKey. It also gives concrete guidance for common names, strict matching, kingdom disambiguation, low-confidence review, and matchType NONE.

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.