Skip to main content
Glama

inaturalist-mcp-server

Inaturalist Resolve Name

inaturalist_resolve_name
Read-only

Resolve organism, place, project, or observer names to identifiers. Taxon lookup matches word starts within a name, not only its beginning; other types use cross-kind search with limited spelling tolerance. Without page, candidates retain relevance order. Explicit taxon pages browse name matches in ascending taxon-ID order; this can differ from autocomplete matching across languages. A miss returns found false with recovery guidance.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "q": "<q>"
    },
    "name": "inaturalist_resolve_name"
  }
}

Input Schema

NameRequiredDescriptionDefault
qYesThe name to resolve. Taxon queries match word starts within a name or an exact numeric taxon id; other types match record text with limited spelling tolerance.
pageNoOptional page for browsing beyond relevance-ranked suggestions. Taxon name pages use ascending taxon-ID order from page 1; numeric taxon IDs have only one page. Keep limit unchanged while paging. page × applied limit must not exceed 10,000.
rankNoRestrict taxon candidates to one rank. Honoured only on type "taxon" — the cross-kind search has no rank filter.
typeNoWhich kind of record to resolve. "taxon" uses autocomplete unless an explicit page browses name matches in taxon-ID order; numeric taxon IDs always use autocomplete. Other types use scored cross-kind search, and "any" searches all kinds. For place geometry and containment, use inaturalist_find_places.taxon
limitNoMaximum candidates to return, applied to every type. Ceiling: 30; oversized values are clamped.

Output Schema

NameRequiredDescriptionDefault
capNoApplied candidate limit.
errorNoPresent when the call failed. Absent on success.
foundNoTrue when candidates matched, including an empty explicit page past an existing match set.
shownNoNumber of candidates returned on this slice.
noticeNoComposed clamp, continuation, or empty-page guidance.
guidanceNoWhy nothing matched and what to try instead. Present only when found is false — this is the primary result of a miss.
truncatedNoTrue when further matching candidates remain beyond this slice.
candidatesNoCandidates in relevance order, or ascending taxon-ID order on explicit taxon name pages.
totalCountNoTotal candidates upstream matched, before the limit was applied.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedOutput schema / properties / candidates / items / properties / current_synonymous_taxon_ids
      Added value: +{
      +  "description": "On inactive taxa only: the taxon ids that replace it; pass one as taxon_id for the current taxon. Empty when upstream records no successor, and several after a split, where the caller chooses.",
      +  "items": {
      +    "type": "number"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / candidates / items / properties / is_active
      Added value: +{
      +  "description": "On taxa: false for a taxon a taxonomic change retired, whose successors are in current_synonymous_taxon_ids.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `result_window_exceeded`: An explicit page multiplied by the applied limit exceeds 10,000. `rank_not_applicable`: rank was supplied with a type other than taxon. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `result_window_exceeded`: An explicit page multiplied by the applied limit exceeds 10,000. `rank_not_applicable`: rank was supplied with a type other than taxon. `rate_budget_exhausted`: This server has spent its daily iNaturalist request budget for the current UTC day. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "result_window_exceeded",
      -  "rank_not_applicable"
      -]New value: +[
      +  "result_window_exceeded",
      +  "rank_not_applicable",
      +  "rate_budget_exhausted"
      +]
  2. Changed12 schema fields changed
    • addedInput schema / properties / page
      Added value: +{
      +  "description": "Optional page for browsing beyond relevance-ranked suggestions. Taxon name pages use ascending taxon-ID order from page 1; numeric taxon IDs have only one page. Keep limit unchanged while paging. page × applied limit must not exceed 10,000.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • changedInput schema / properties / q / description
      Previous value: -"The name to resolve. On type \"taxon\" this is a name prefix or an exact taxon id; on the other types it is matched across the record text."New value: +"The name to resolve. Taxon queries match word starts within a name or an exact numeric taxon id; other types match record text with limited spelling tolerance."
    • changedInput schema / properties / type / description
      Previous value: -"Which kind of record to resolve. \"taxon\" uses the taxon autocomplete; the rest use the scored cross-kind search, and \"any\" searches every kind at once. For a place’s bounding box and containment chain rather than just its id, use inaturalist_find_places instead."New value: +"Which kind of record to resolve. \"taxon\" uses autocomplete unless an explicit page browses name matches in taxon-ID order; numeric taxon IDs always use autocomplete. Other types use scored cross-kind search, and \"any\" searches all kinds. For place geometry and containment, use inaturalist_find_places."
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "found",
      -      "candidates",
      -      "totalCount"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "found",
      +      "candidates",
      +      "totalCount",
      +      "truncated",
      +      "shown",
      +      "cap"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • changedOutput schema / properties / candidates / description
      Previous value: -"Ranked candidates, best match first."New value: +"Candidates in relevance order, or ascending taxon-ID order on explicit taxon name pages."
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "Applied candidate limit.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `rank_not_applicable`: rank was supplied with a type other than taxon. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `result_window_exceeded`: An explicit page multiplied by the applied limit exceeds 10,000. `rank_not_applicable`: rank was supplied with a type other than taxon. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "rank_not_applicable"
      -]New value: +[
      +  "result_window_exceeded",
      +  "rank_not_applicable"
      +]
    • changedOutput schema / properties / found / description
      Previous value: -"True when at least one candidate matched."New value: +"True when candidates matched, including an empty explicit page past an existing match set."
    • changedOutput schema / properties / notice / description
      Previous value: -"Requested and applied limits when an oversized limit was clamped."New value: +"Composed clamp, continuation, or empty-page guidance."
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of candidates returned on this slice.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when further matching candidates remain beyond this slice.",
      +  "type": "boolean"
      +}
  3. Changed1 schema field changed
    • changedInput schema / properties / rank / enum
      Previous value: -[
      -  "stateofmatter",
      -  "kingdom",
      -  "phylum",
      -  "subphylum",
      -  "superclass",
      -  "class",
      -  "subclass",
      -  "superorder",
      -  "order",
      -  "suborder",
      -  "infraorder",
      -  "superfamily",
      -  "epifamily",
      -  "family",
      -  "subfamily",
      -  "supertribe",
      -  "tribe",
      -  "subtribe",
      -  "genus",
      -  "genushybrid",
      -  "species",
      -  "hybrid",
      -  "subspecies",
      -  "variety",
      -  "form"
      -]New value: +[
      +  "stateofmatter",
      +  "kingdom",
      +  "phylum",
      +  "subphylum",
      +  "superclass",
      +  "class",
      +  "subclass",
      +  "infraclass",
      +  "subterclass",
      +  "superorder",
      +  "order",
      +  "suborder",
      +  "infraorder",
      +  "parvorder",
      +  "zoosection",
      +  "zoosubsection",
      +  "superfamily",
      +  "epifamily",
      +  "family",
      +  "subfamily",
      +  "supertribe",
      +  "tribe",
      +  "subtribe",
      +  "genus",
      +  "genushybrid",
      +  "subgenus",
      +  "section",
      +  "subsection",
      +  "complex",
      +  "species",
      +  "hybrid",
      +  "subspecies",
      +  "variety",
      +  "form",
      +  "infrahybrid"
      +]
  4. Changed8 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum candidates to return, applied to every type."New value: +"Maximum candidates to return, applied to every type. Ceiling: 30; oversized values are clamped."
    • addedInput schema / properties / limit / exclusiveMinimum
      Added value: +0
    • changedInput schema / properties / limit / maximum
      Previous value: -30New value: +9007199254740991
    • removedInput schema / properties / limit / minimum
      Removed value: -1
    • changedOutput schema / properties / candidates / items / properties / photo / properties / attribution / description
      Previous value: -"Attribution string, verbatim and never reformatted. Reproduce it with any use of the image."New value: +"Verbatim attribution; reproduce with any use of the image."
    • changedOutput schema / properties / candidates / items / properties / photo / properties / medium_url / description
      Previous value: -"Medium variant. Supplied by upstream where it publishes every size, otherwise derived by substituting the size qualifier in the path. Absent when the path did not match the documented shape."New value: +"Medium image URL; derived from the size path if needed. Absent when no variant is available."
    • changedOutput schema / properties / candidates / items / properties / photo / properties / open / description
      Previous value: -"True when the photo is served from the host the upstream reserves for open licences. A photo can move hosts when its licence changes, so this reflects fetch time."New value: +"True when served from the open-licence host at fetch time; licences can change."
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Requested and applied limits when an oversized limit was clamped.",
      +  "type": "string"
      +}
  5. Changed3 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum candidates to return."New value: +"Maximum candidates to return, applied to every type."
    • addedOutput schema / properties / candidates / items / properties / login
      Added value: +{
      +  "description": "Observer login, on users only — the value inaturalist_get_leaderboard entries and an observation’s observer carry.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / candidates / items / properties / name / description
      Previous value: -"Scientific name, place name, or login."New value: +"Scientific name on taxa, place name, project title, or an observer’s display name — which falls back to the login when the observer set none."
  6. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations only declare read-only and open-world, so the description carries real weight and delivers: word-start matching for taxa, spelling tolerance for cross-kind search, ordering differences between relevance and page browsing, and 'A miss returns found false with recovery guidance.' That is substantial beyond-annotation disclosure; it stops short of rate limits or cost notes.

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?

Front-loaded with purpose, then matching and ordering caveats in compact sentences with no filler. Density is high but each sentence carries distinct information; minor cost is that the paging/ordering sentence takes a second read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter tool with an output schema and only read-only annotations, the definition covers type semantics, matching rules, paging constraints, and the not-found shape. Remaining gaps (what identifiers are returned as, clamping) are handled by the output schema and parameter descriptions.

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 baseline is 3. The description restates the page-ordering semantics already documented in the page parameter and adds only a marginal nuance ('this can differ from autocomplete matching across languages'), so it doesn't meaningfully extend the schema.

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 and resource: 'Resolve organism, place, project, or observer names to identifiers.' It also enumerates the kinds (taxon/place/project/observer) that map to the type enum. It doesn't name a sibling to differentiate from in the description itself, though the schema routes place geometry to inaturalist_find_places.

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

Usage Guidelines3/5

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

Usage context is implied through behavioral notes: 'Without page, candidates retain relevance order' and 'Explicit taxon pages browse name matches in ascending taxon-ID order,' which tells the agent when to pass page. There is no explicit when-not or named alternative in the description; the closest guidance (use inaturalist_find_places for place geometry) lives in the schema, not the description.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.