inaturalist-mcp-server

Inaturalist Get Leaderboard

inaturalist_get_leaderboard

Read-only

Rank the most active observers or identifiers for an area, period, and taxon — who knows this place or this group. kind selects which: observers are ranked by how many observations they recorded, identifiers by how many identifications they made. An area is given in exactly one form: place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box. Both endpoints rank only the top 500 entries, so page multiplied by per_page must stay at or below 500 — narrow the area, period, or taxon to bring someone further down into reach. For the most-recorded species rather than the most active people, use inaturalist_get_species_counts.

Input Schema

Name	Required	Description
`d1`	No	Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2.
`d2`	No	Latest observation date, YYYY-MM-DD. Inclusive.
`lat`	No	Latitude of the search centre, in decimal degrees. Requires lng and radius.
`lng`	No	Longitude of the search centre, in decimal degrees. Requires lat and radius.
`kind`	Yes	Which leaderboard: "observers" ranks by observations recorded, "identifiers" by identifications made.
`page`	No	Page number. Defaults to 1.
`nelat`	No	North-east corner latitude of the bounding box, at or north of swlat. All four corners or none.
`nelng`	No	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.
`swlat`	No	South-west corner latitude of the bounding box. All four corners or none.
`swlng`	No	South-west corner longitude of the bounding box. All four corners or none.
`radius`	No	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.
`per_page`	No	Entries per page. Two ceiling-sized pages cover the 500-entry window. Ceiling: 250; oversized values are clamped.
`place_id`	No	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.
`taxon_id`	No	Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name.
`quality_grade`	No	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.

Output Schema

Name	Required	Description
`cap`	No	The per_page that was applied.
`kind`	No	Which leaderboard was ranked.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	How many entries this page carries.
`notice`	No	Guidance when nobody matched, when the page is past the last one holding entries, or how to reach further down the ranking.
`entries`	No	The ranked members, most active first.
`truncated`	No	True when the page filled per_page and more entries follow.
`count_metric`	No	What the count on each entry measures.
`total_results`	No	How many people upstream reports as matching. Far larger than the 500 this leaderboard can actually address.
`applied_filters`	No	The server-applied default that determines what this answer means.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 26, 2026

changedInput schema / properties / per_page / description

Previous value: -"Entries per page, maximum 250. An entry costs roughly 140 bytes across structuredContent and the rendered text together, so 250 is a full page near 34 KB — and two such pages cover the whole 500-entry window these endpoints rank."New value: +"Entries per page. Two ceiling-sized pages cover the 500-entry window. Ceiling: 250; oversized values are clamped."

addedInput schema / properties / per_page / exclusiveMinimum
```
Added value: +0
```
changedInput schema / properties / per_page / maximum
```
Previous value: -250New value: +9007199254740991
```
removedInput schema / properties / per_page / 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. `leaderboard_window_exceeded`: page multiplied by per_page would reach past the 500 entries these endpoints rank. `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: `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. `leaderboard_window_exceeded`: page multiplied by per_page would reach past the 500 entries these endpoints rank. `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",
-  "inverted_date_range",
-  "leaderboard_window_exceeded",
-  "unknown_taxon_id"
-]New value: +[
+  "unknown_place_id",
+  "invalid_geography",
+  "inverted_date_range",
+  "leaderboard_window_exceeded",
+  "unknown_taxon_id"
+]

Changed1 schema field changedSep 24, 2026

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nobody matched, or how to reach further down the ranking."New value: +"Guidance when nobody matched, when the page is past the last one holding entries, or how to reach further down the ranking."

Changed7 schema fields changedSep 22, 2026

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. `leaderboard_window_exceeded`: page multiplied by per_page would reach past the 500 entries these endpoints rank. `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. `leaderboard_window_exceeded`: page multiplied by per_page would reach past the 500 entries these endpoints rank. `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",
-  "leaderboard_window_exceeded",
-  "unknown_taxon_id"
-]New value: +[
+  "invalid_geography",
+  "inverted_date_range",
+  "leaderboard_window_exceeded",
+  "unknown_taxon_id"
+]

First observedSep 20, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover safety (readOnlyHint) and open-world behavior, so the description's real contribution is the ranking-window cap — only the top 500 entries are ranked, which silently truncates results — plus the advice to narrow area/period/taxon to reach lower ranks. That is substantive behavioral context an agent could not infer from the schema; it stops short of five only because auth and rate-limit behavior go unmentioned.

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?

Four sentences, front-loaded with the purpose, then the mode selector, then the area rule, then the cap and alternative. Every sentence carries weight, though the sentence explaining how observers vs identifiers are ranked repeats what the `kind` enum description already says.

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 15-parameter tool, the description covers the parts the schema cannot express structurally: mutually exclusive area forms, the hard 500-entry ranking limit, and the sibling route for species counts. Return shape is handled by the existing output schema, so the remaining gaps (quality_grade defaults, taxon_id resolution path) are already documented in the schema itself.

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?

With 100% schema coverage the baseline is 3, and the description earns above that by stating the cross-parameter constraint (page × per_page ≤ 500) that the schema documents only piecewise via per_page's 'two ceiling-sized pages' note. It also restates the exactly-one-area rule more crisply than the schema's per-field 'mutually exclusive' wording, though the `kind` explanation largely duplicates the enum's own description.

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 and resource — ranking the most active observers or identifiers — and immediately qualifies it by area, period, and taxon. It also explicitly disambiguates from the sibling tool that ranks species rather than people (inaturalist_get_species_counts).

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?

Names the choice that selects the two modes via `kind`, states that an area must be given in exactly one of three forms (place_id, lat/lng/radius, or bounding box), and warns that the 500-entry window means page×per_page must stay at or below 500, with a suggested remedy. It also routes the agent to inaturalist_get_species_counts when the intent is species rather than people.

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 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.