Skip to main content
Glama

inaturalist-mcp-server

Inaturalist Get Similar Species

inaturalist_get_similar_species
Read-only

List related taxa ranked by observations carrying current identifications of both taxa. This is co-identification evidence, not a directional correction count or an exhaustive list of visually similar organisms. Scope it to an area in exactly one form (place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box), or leave the area off for global results. The taxon must be a genus or finer (genus, species, or below). Resolve the organism name to a taxon id with inaturalist_resolve_name first.

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": {
      "taxon_id": "<taxon_id>"
    },
    "name": "inaturalist_get_similar_species"
  }
}

Input Schema

NameRequiredDescriptionDefault
d1NoEarliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.
d2NoLatest observation date, YYYY-MM-DD. Inclusive.
latNoLatitude of the search centre, in decimal degrees. Requires lng and radius.
lngNoLongitude of the search centre, in decimal degrees. Requires lat and radius.
limitNoMaximum related taxa to return. Served ceiling: 24; requests above it are reduced to 24. Positive safe integer requests are accepted.
nelatNoNorth-east corner latitude of the bounding box, at or north of swlat. All four corners or none.
nelngNoNorth-east corner longitude of the bounding box. All four corners or none. West of swlng is accepted: it describes a box crossing the antimeridian.
swlatNoSouth-west corner latitude of the bounding box. All four corners or none.
swlngNoSouth-west corner longitude of the bounding box. All four corners or none.
radiusNoSearch radius around lat/lng, in KILOMETRES, greater than 0. Requires lat and lng. Ceiling: 20040; oversized values are clamped with notice.
captiveNoTrue returns captive and cultivated records only — zoo animals, garden plantings; false returns wild records only. Defaults to false. Captive records are graded casual, so pair true with "casual" in quality_grade.
place_idNoNumeric iNaturalist place id from inaturalist_find_places. Mutually exclusive with the lat/lng/radius triple and the bounding box.
taxon_idYesNumeric taxon id to find look-alikes for, at genus or finer — a genus, species, or subspecies; a family or anything coarser is refused. Resolve a name to an id with inaturalist_resolve_name.
quality_gradeNoIdentification confidence tiers to include, normalized to unique values in first-appearance order. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.

Output Schema

NameRequiredDescriptionDefault
capNoThe limit that was applied.
errorNoPresent when the call failed. Absent on success.
shownNoHow many look-alikes this response carries.
noticeNoGuidance when no look-alikes are recorded, or when the limit cut the set.
taxon_idNoThe taxon the look-alikes were found for.
truncatedNoTrue when the local limit cut the list or upstream reached its ceiling, so more related taxa may exist.
totalCountNoHow many look-alikes upstream returned, before the limit was applied.
similar_speciesNoLook-alikes ranked by misidentification_count, most-confused first.
truncationCeilingNoMisidentification count of the last look-alike shown. The ranking is descending, so no omitted look-alike exceeds it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / captive / description
      Previous value: -"True returns captive and cultivated records only — zoo animals, garden plantings; false returns wild records only. Defaults to false."New value: +"True returns captive and cultivated records only — zoo animals, garden plantings; false returns wild records only. Defaults to false. Captive records are graded casual, so pair true with \"casual\" in quality_grade."
    • changedInput schema / properties / place_id / description
      Previous value: -"Numeric iNaturalist place id from inaturalist_find_places. Mutually exclusive with the lat/lng/radius triple and the bounding box. A non-numeric value answers HTTP 500 upstream."New value: +"Numeric iNaturalist place id from inaturalist_find_places. Mutually exclusive with the lat/lng/radius triple and the bounding box."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `unknown_place_id`: iNaturalist answered 422 because place_id does not exist. `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. `taxon_rank_too_coarse`: iNaturalist answered 422 because the taxon is coarser than genus, such as a family, order, or class. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `unknown_place_id`: iNaturalist answered 422 because place_id does not exist. `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. `taxon_rank_too_coarse`: iNaturalist answered 422 because the taxon is coarser than genus, such as a family, order, or class. `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: -[
      -  "unknown_place_id",
      -  "invalid_geography",
      -  "inverted_date_range",
      -  "unknown_taxon_id",
      -  "taxon_rank_too_coarse"
      -]New value: +[
      +  "unknown_place_id",
      +  "invalid_geography",
      +  "inverted_date_range",
      +  "unknown_taxon_id",
      +  "taxon_rank_too_coarse",
      +  "rate_budget_exhausted"
      +]
  2. Changed3 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum look-alikes to return. Applied in-process to the whole upstream confusion set. Ceiling: 50; oversized values are clamped."New value: +"Maximum related taxa to return. Served ceiling: 24; requests above it are reduced to 24. Positive safe integer requests are accepted."
    • changedOutput schema / properties / similar_species / items / properties / misidentification_count / description
      Previous value: -"How many times identifiers corrected this taxon to the queried one. The ranking key."New value: +"Observations identified as both taxa under the call’s filters: a symmetric count of current, non-hidden identifications, including finer taxa through their ancestors. Withdrawn identifications are excluded. The ranking key."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the limit cut the confusion set."New value: +"True when the local limit cut the list or upstream reached its ceiling, so more related taxa may exist."
  3. Changed2 schema fields changed
    • changedInput schema / properties / radius / description
      Previous value: -"Search radius around lat/lng, in KILOMETRES, greater than 0. Requires lat and lng. The upstream publishes no bound; 500 is a verified ceiling this server imposes."New value: +"Search radius around lat/lng, in KILOMETRES, greater than 0. Requires lat and lng. Ceiling: 20040; oversized values are clamped with notice."
    • removedInput schema / properties / radius / maximum
      Removed value: -500
  4. Changed11 schema fields changed
    • changedInput schema / properties / captive / description
      Previous value: -"Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only."New value: +"True returns captive and cultivated records only — zoo animals, garden plantings; false returns wild records only. Defaults to false."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum look-alikes to return. Applied in-process — the upstream endpoint publishes no page size and returns its whole confusion set."New value: +"Maximum look-alikes to return. Applied in-process to the whole upstream confusion set. Ceiling: 50; oversized values are clamped."
    • addedInput schema / properties / limit / exclusiveMinimum
      Added value: +0
    • changedInput schema / properties / limit / maximum
      Previous value: -50New value: +9007199254740991
    • removedInput schema / properties / limit / minimum
      Removed value: -1
    • changedInput schema / properties / quality_grade / description
      Previous value: -"Identification confidence tiers to include. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence."New value: +"Identification confidence tiers to include, normalized to unique values in first-appearance order. Defaults to research-grade only; adding \"needs_id\" roughly doubles the corpus and lowers identification confidence."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. `taxon_rank_too_coarse`: iNaturalist answered 422 because the taxon is coarser than genus, such as a family, order, or class. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `unknown_place_id`: iNaturalist answered 422 because place_id does not exist. `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. `taxon_rank_too_coarse`: iNaturalist answered 422 because the taxon is coarser than genus, such as a family, order, or class. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_geography",
      -  "inverted_date_range",
      -  "unknown_taxon_id",
      -  "taxon_rank_too_coarse"
      -]New value: +[
      +  "unknown_place_id",
      +  "invalid_geography",
      +  "inverted_date_range",
      +  "unknown_taxon_id",
      +  "taxon_rank_too_coarse"
      +]
    • changedOutput schema / properties / similar_species / 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 / similar_species / 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 / similar_species / 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."
  5. Changed3 schema fields changed
    • changedInput schema / properties / taxon_id / description
      Previous value: -"Numeric taxon id to find look-alikes for. Resolve a name to an id with inaturalist_resolve_name."New value: +"Numeric taxon id to find look-alikes for, at genus or finer — a genus, species, or subspecies; a family or anything coarser is refused. Resolve a name to an id with inaturalist_resolve_name."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. `taxon_rank_too_coarse`: iNaturalist answered 422 because the taxon is coarser than genus, such as a family, order, or class. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_geography",
      -  "inverted_date_range",
      -  "unknown_taxon_id"
      -]New value: +[
      +  "invalid_geography",
      +  "inverted_date_range",
      +  "unknown_taxon_id",
      +  "taxon_rank_too_coarse"
      +]
  6. Changed7 schema fields changed
    • changedInput schema / properties / d1 / description
      Previous value: -"Earliest observation date, YYYY-MM-DD. Inclusive."New value: +"Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2."
    • changedInput schema / properties / nelat / description
      Previous value: -"North-east corner latitude of the bounding box. All four corners or none."New value: +"North-east corner latitude of the bounding box, at or north of swlat. All four corners or none."
    • changedInput schema / properties / nelng / description
      Previous value: -"North-east corner longitude of the bounding box. All four corners or none."New value: +"North-east corner longitude of the bounding box. All four corners or none. West of swlng is accepted: it describes a box crossing the antimeridian."
    • changedInput schema / properties / radius / description
      Previous value: -"Search radius around lat/lng, in KILOMETRES. Requires lat and lng. The upstream publishes no bound; 500 is a verified ceiling this server imposes."New value: +"Search radius around lat/lng, in KILOMETRES, greater than 0. Requires lat and lng. The upstream publishes no bound; 500 is a verified ceiling this server imposes."
    • removedInput schema / properties / radius / minimum
      Removed value: -0
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially or in two forms at once. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_geography`: An area was given partially, in two forms at once, with a radius of 0 or less, or with nelat south of swlat. `inverted_date_range`: d1 is after d2. `unknown_taxon_id`: iNaturalist answered 422 because the taxon_id does not exist. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_geography",
      -  "unknown_taxon_id"
      -]New value: +[
      +  "invalid_geography",
      +  "inverted_date_range",
      +  "unknown_taxon_id"
      +]
  7. First observed

TDQS

A4.5/5.0
Behavior5/5

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

The annotations already establish read-only and open-world behavior, and the description adds important semantic behavior beyond that: results are based on co-identification evidence, ranked by observations, and are neither directional correction counts nor exhaustive visual-similarity lists. This tells the agent how to interpret the output rather than just what parameters exist.

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?

The description is front-loaded, compact, and organized around the most important distinctions: what is ranked, what it is not, how to scope the area, and what prerequisite to satisfy. Every sentence carries useful information for an agent.

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 rich schema, full parameter descriptions, output schema, and annotations, the description covers the critical conceptual and operational constraints an agent needs. It does not need to repeat return-value details because an output schema exists.

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 the schema already documents parameters thoroughly. The description reinforces key constraints such as the exactly-one area form, global fallback, and genus-or-finer taxon requirement, but it largely repeats what the schema already provides and does not add much parameter-level detail.

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 states a specific verb and resource: it lists related taxa ranked by observations where both taxa carry current identifications. It also explicitly distinguishes this from a directional correction count and from an exhaustive list of visually similar organisms, so the agent can understand what the tool actually returns.

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?

The description gives clear prerequisites and usage constraints: resolve the name with inaturalist_resolve_name first, the taxon must be genus or finer, and the area should be specified in exactly one form or omitted for global results. It does not name a direct alternative tool for similar-species queries, but it does clarify what this tool is not.

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.