Skip to main content
Glama

inaturalist-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Inaturalist List Reference

inaturalist_list_reference
Read-only

Look up annotation attributes/values, quality grades, licences, ranks, iconic taxa, and conservation codes before filtering; unknown values can silently return nothing. Conservation codes are the normalised csi filter, distinct from authority-specific taxon status text. With topic controlled_terms and taxon_id, also return observed annotation usage and counts.

Input Schema

NameRequiredDescriptionDefault
topicYesVocabulary to decode; controlled_terms is live/cached, the rest static.
taxon_idNoAdd annotation usage counts, most-used first; only with controlled_terms. Get the id from inaturalist_resolve_name.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
topicNoThe vocabulary that was decoded.
noticeNoGuidance when the requested taxon has no recorded annotations yet.
sourceNo"upstream" for fetched data, "static" for spec-derived tables.
entriesNoThe vocabulary, one entry per code or attribute.
observed_usageNoAnnotation usage, most-used first; present with taxon_id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • changedInput schema / properties / taxon_id / description
      Previous value: -"Add observed annotation usage for this taxon, ranked by how often each attribute/value pair has been recorded. Valid only with topic controlled_terms. Resolve a name to an id with inaturalist_resolve_name."New value: +"Add annotation usage counts, most-used first; only with controlled_terms. Get the id from inaturalist_resolve_name."
    • changedInput schema / properties / topic / description
      Previous value: -"Which vocabulary to decode. controlled_terms is fetched live and cached; the rest are spec-derived static tables."New value: +"Vocabulary to decode; controlled_terms is live/cached, the rest static."
    • changedOutput schema / properties / entries / items / properties / code / description
      Previous value: -"The literal filter value to pass, on the static topics — e.g. \"needs_id\", \"cc0\", \"Aves\"."New value: +"Static filter value, e.g. \"needs_id\", \"cc0\", \"Aves\"."
    • changedOutput schema / properties / observed_usage / description
      Previous value: -"Observed annotation usage for taxon_id, most-used first. Present only when taxon_id was given."New value: +"Annotation usage, most-used first; present with taxon_id."
    • changedOutput schema / properties / observed_usage / items / properties / term_id / description
      Previous value: -"Attribute id — pass it as term_id to filter search, species counts, or the histogram. Null when upstream omitted it."New value: +"Attribute id for term_id on search, species counts, or histogram; null when omitted upstream."
    • changedOutput schema / properties / observed_usage / items / properties / term_value_id / description
      Previous value: -"Value id — pass it as term_value_id alongside term_id. Null when upstream omitted it."New value: +"Value id for term_value_id alongside term_id; null when omitted upstream."
    • changedOutput schema / properties / observed_usage / items / properties / value / description
      Previous value: -"Annotation value label. Labels repeat across attributes, so filter by the ids rather than the label."New value: +"Value label; use ids for filtering because labels can repeat."
    • changedOutput schema / properties / source / description
      Previous value: -"\"upstream\" when the table was fetched from iNaturalist, \"static\" when spec-derived."New value: +"\"upstream\" for fetched data, \"static\" for spec-derived tables."
  2. Changed4 schema fields changed
    • addedOutput schema / properties / observed_usage / items / properties / term_id
      Added value: +{
+  "description": "Attribute id — pass it as term_id to filter search, species counts, or the histogram. Null when upstream omitted it.",
+  "type": [
+    "number",
+    "null"
+  ]
+}
    • addedOutput schema / properties / observed_usage / items / properties / term_value_id
      Added value: +{
+  "description": "Value id — pass it as term_value_id alongside term_id. Null when upstream omitted it.",
+  "type": [
+    "number",
+    "null"
+  ]
+}
    • changedOutput schema / properties / observed_usage / items / properties / value / description
      Previous value: -"Annotation value label."New value: +"Annotation value label. Labels repeat across attributes, so filter by the ids rather than the label."
    • changedOutput schema / properties / observed_usage / items / required
      Previous value: -[
-  "attribute",
-  "value",
-  "count"
-]New value: +[
+  "attribute",
+  "term_id",
+  "value",
+  "term_value_id",
+  "count"
+]
  3. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already mark this read-only/open-world, and the description adds real behavioral value beyond them: the silent-empty-result failure mode, the warning that conservation codes are the normalised csi filter rather than authority-specific taxon status text, and the conditional enrichment behaviour of taxon_id with controlled_terms. No contradiction with annotations.

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 tight sentences, front-loaded with the lookup purpose and immediately followed by the failure-mode warning; no filler and no repetition of schema verbatim except where it serves flow.

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?

For a two-parameter reference tool with an output schema, the description covers purpose, timing, failure mode, and the one non-obvious semantic trap. Nothing an agent needs to call it correctly is missing.

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 earns an extra point by clarifying that conservation_status_codes returns normalised csi values distinct from authority-specific status text, which the enum alone does not convey. The taxon_id/controlled_terms interaction is restated from the schema rather than newly explained.

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

Purpose4/5

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

States a specific verb ('look up') and an explicit resource set (annotation attributes/values, quality grades, licences, ranks, iconic taxa, conservation codes), making clear this is a vocabulary-reference tool rather than a data-search tool. Sibling tools are not named, so it falls just short of a 5, but the purpose is unambiguous against the search/get siblings.

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

Usage Guidelines4/5

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

'before filtering' plus 'unknown values can silently return nothing' tells the agent exactly when this tool belongs in a workflow and what goes wrong if skipped. It does not name a specific alternative tool to pair with, which is the only missing piece.

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

All inaturalist-mcp-server toolsInspect
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.

Resources