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 queried name is a synonym, 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. 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.

Input Schema

TableJSON 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

TableJSON 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 the queried name was a synonym and taxonKey was resolved to the accepted taxon. Absent when the matched name is already the accepted one.
`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 queried name 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. NONE means no usable match.
`phylumKey`	No	Backbone taxon key for the phylum.
`confidence`	No	Match confidence score 0–100. Below 80 warrants review.
`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 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.7/5.0

Behavior5/5

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already signal safety. The description adds high-value behavioral details like synonym resolution (taxonKey vs matchedTaxonKey), the 80-confidence review threshold, and the meaning of matchType NONE—all beyond what annotations convey.

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?

Well-structured and front-loaded: purpose first, then critical workflow context, then edge-case behavior. Every sentence serves a purpose—no filler. Approximately 200 words, acceptable given the richness of information.

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?

With an output schema present, the description complements it by explaining key output fields (taxonKey, matchedTaxonKey, matchType, confidence) and how to interpret them. Covers synonyms, confidence thresholds, and failure cases. Nothing essential for correct invocation 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 description coverage is 100%, so all parameters are well-documented. The description largely restates schema content (e.g., rank to avoid genus matching, strict flag behavior) without adding new meaning. It maintains baseline adequacy but does not elevate understanding beyond the schema.

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 ('Match'), a precise resource ('scientific name against the GBIF backbone taxonomy'), and describes the output (taxon with classification and confidence). It differentiates from siblings by naming the mandatory first-step role and explicitly routing vernacular name searches to gbif_search_species.

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 declares this as the mandatory first step for GBIF workflows, lists dependent tools, names the alternative (gbif_search_species) for common names, and provides concrete troubleshooting for matchType NONE (remove strict flag or broaden name). Guidance is direct and actionable.

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.