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

TableJSON 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, 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.
`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. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence.

Output Schema

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

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.6/5.0

Behavior4/5

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

Annotations already declare this a read-only, open-world call, and the description adds a consequential behavioral fact not in the schema: both endpoints cap rankings at 500 entries, which drives the pagination constraint. It also clarifies that kind changes the metric being ranked. No contradiction with the 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?

Four dense sentences, with the core purpose front-loaded before the selection guidance and fallback tool. Every sentence carries either a functional definition, a constraint, or an actionable alternative; there is no filler or schema repetition.

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 with an output schema, this description covers the selection axis, the area exclusivity rule, the pagination ceiling, and the key sibling. The only residual ambiguity is that 'An area is given in exactly one form' does not explicitly say that area, period, and taxon filters are optional, though the schema's required-only-kind signal implies this.

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 met by the parameter descriptions. The description adds value beyond the schema by grouping area parameters into three mutually exclusive forms and by tying page and per_page together through the 500-entry cap.

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 first sentence names a concrete verb ('Rank'), a specific resource ('most active observers or identifiers'), and the filtering axes (area, period, taxon). The kind distinction is explained and the description explicitly differentiates itself from inaturalist_get_species_counts, so an agent can select it without ambiguity.

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?

The description states the exact competing tool and the condition to choose it: 'For the most-recorded species rather than the most active people, use inaturalist_get_species_counts.' It also gives operational rules: area must be supplied in exactly one form, and page × per_page must stay at or below 500, with advice to narrow filters to reach lower ranks.

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.