inaturalist-mcp-server

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

With only readOnlyHint and openWorldHint annotations, the description carries the behavioral burden and does so richly: it discloses prefix matching, antimeridian handling, the per_page double-list behavior, and that geometry is stripped with a concrete payload-size example. None of this is available from annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the primary purpose, then efficiently covers the two modes, output contents, and an important performance behavior. Every sentence contributes information; there is no filler or repetition of schema details.

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

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

For a tool with two modes, six parameters, an output schema, and read-only annotations, the description is complete enough for an agent to invoke it correctly. It explains the constraint that exactly one mode must be used, what results contain, and a notable payload optimization, leaving no critical gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by framing q and the four corners as mutually exclusive modes and clarifying that all four corners must be supplied together. It also adds context around per_page applying only to the bounding-box arm, which is valuable semantic guidance.

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

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

The description states a specific verb and resource: resolving a place name to a place id or listing places covering a map area. It clearly distinguishes the two operational modes and gives the criteria for each, which is enough to tell this tool apart from siblings.

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

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

It explicitly explains when to pass q versus the four bounding-box coordinates, and warns that exactly one mode must be used, never both. It does not name sibling alternatives or say when to prefer this tool over them, but the internal usage guidance is clear and actionable.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. The description adds valuable behavioral context beyond annotations: it discloses that the upstream applies a default start date to absolute intervals, that the response is capped at 800 buckets kept from the start of the range, that a non-numeric place_id answers HTTP 500 upstream, and that term_value_id sent alone is ignored upstream. It also states defaults (research-grade, wild-only) and that they are echoed back. Minor gap: it doesn't describe the exact response shape, but an output schema exists, so that burden is lifted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph that front-loads the core purpose and default behavior, then covers area forms, taxon omission, annotation narrowing, and defaults. Every sentence earns its place, but the paragraph is long and packs many distinct facts together; a bit of structural separation (e.g., listing the three area forms) would improve scannability. Still, it is efficient and information-dense without fluff.

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

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

For a complex tool with 18 optional parameters, no required parameters, and an output schema, the description covers all the essential decision points: how to specify an area (three mutually exclusive forms), how to choose an interval, how to narrow by taxon/annotation/iconic_taxa, what the defaults are, and what upstream quirks to expect (500 km cap, 800-bucket cap, HTTP 500 on non-numeric place_id, ignored term_value_id). The output schema handles return values, and annotations handle safety. Nothing critical is missing for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the semantic distinction between month_of_year/week_of_year (folded seasonal curve) and absolute intervals, by clarifying that the bounding box can cross the antimeridian, by noting the 500 km radius is a server-imposed verified ceiling, and by explaining that term_value_id requires term_id. It also gives concrete examples (Life Stage = Larva, Flowers and Fruits = Flowers) that make the annotation pair concept tangible. It doesn't fully compensate for the fact that 18 parameters is a lot, but the schema already documents each parameter well.

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

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

The description opens with a specific verb ('Build a phenology histogram') and names the resource (a taxon in an area) and the bucketing intervals (months, weeks, years). It clearly distinguishes this from sibling tools like inaturalist_get_species_counts or inaturalist_search_observations by focusing on temporal distribution rather than counts or raw observations.

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

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

The description explicitly states the area must be given in exactly one form (place_id, lat/lng/radius, or bounding box), explains when to omit taxon_id, and describes how to narrow by annotation pairs or iconic_taxa. It also gives concrete guidance on interval selection (month_of_year for seasonal questions, absolute intervals for real dates) and warns about the 800-bucket cap with day/hour intervals. This is rich, actionable usage guidance.

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

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.

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.

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.

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.

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.

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.

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

While annotations already mark this as readOnly/openWorld/idempotent, the description adds substantial behavioral detail: one upstream request per batch, results in requested order, per-id missing handling, the failure condition (only when nothing resolves), budget-based truncation (40/40/40 for one id, 4 each for ten), and size reporting for each truncated array. This is exactly the kind of context annotations cannot provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place. The main capability is front-loaded, followed by cost, failure semantics, and truncation behavior. No filler or repetition; the detail about missing ids and budget sharing is essential for correct invocation and interpretation.

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

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

With an output schema present and only two parameters, the description covers all necessary runtime behaviors: batching, ordering, failure modes, truncation budgets, and per-record size reporting. There are no gaps an agent needs to call this tool correctly or interpret its results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Though schema coverage is 100%, the description meaningfully extends both parameters. It explains the include default and what 'identifications' carries (the thread), warns that other includes cost context, and reveals the shared 40-entry budget mechanism. For observation_id it explains the 1-10 limit and points to the sibling search tool for finding current ids. The description adds real decision-making value beyond the schema.

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

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

The description opens with a specific verb+resource ('Fetch up to 10 observations by id') and states the key differentiator: it returns the community identification thread (who identified, agreement status, consensus taxon). This clearly separates it from search-based siblings like inaturalist_search_observations, which the description explicitly references for finding ids.

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

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

The description gives explicit when-to-use context: batch resolution is cheaper than ten separate lookups, missing ids are handled per-id instead of failing the batch, and the batch fails only when nothing resolves. It also provides concrete selection guidance for the include parameter (check photo_count and sound_count first) and warns that large batches truncate thread data, recommending a single id for the full 40-entry view.

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

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

Even with readOnlyHint and openWorldHint annotations present, the description adds substantial behavioral detail: ranking by identifier corrections, global vs. regional confusion sets, the taxon-rank restriction (genus or finer), and the upstream's refusal to supply confusion sets for coarser taxa. It also surfaces the prerequisite of resolving names first. This exceeds what annotations alone provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three dense sentences with zero fluff. The core action is front-loaded, followed by scoping rules, then the taxon constraint and prerequisite. Every sentence carries distinct value, and the structure guides the agent from what → how → when.

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

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

Given the tool's complexity (14 parameters, rich schema, and an output schema), the description covers the critical decision points: purpose, area scoping modes, taxon rank restriction, and the resolve-name prerequisite. It leaves detailed per-parameter semantics to the schema, which is appropriate. It could mention the default behavior of limit or quality_grade, but those are fully documented in the schema, so the omission is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful group semantics beyond the schema: it clarifies that area scoping accepts exactly one of three forms, that omitting the area yields the global set, and that the taxon must be genus or finer. It also ties the spatial parameters together conceptually, which the schema conveys only through individual mutual-exclusion notes.

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

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

The description opens with a specific verb and resource: 'List the taxa this one is most often misidentified as, ranked by how many times identifiers made the correction.' This clearly distinguishes it from sibling tools like inaturalist_get_histogram or inaturalist_get_species_counts, which serve different analytical purposes. The field-identification framing leaves no ambiguity about the tool's role.

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

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

The description gives clear context for when to use the tool: as a field-identification check before committing to a look-alike. It explicitly instructs the agent to resolve names first with inaturalist_resolve_name and explains the three mutually exclusive area scoping options. It does not explicitly name sibling alternatives or state 'do not use for X,' so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful behavior beyond that: it returns a ranked aggregation rather than individual sightings, defaults to research-grade wild-only records, and 'echoes those defaults back' in the response. It does not cover error behavior or pagination details, but the output schema and annotations lower that burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences front-load the core purpose and answer shape, then cover area form exclusivity, common filters, defaults, and the key sibling alternative. Every clause earns its place and there is no filler.

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

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

For a 21-parameter tool with a rich output schema and read-only/open-world annotations, the description covers all high-level decisions an agent must make: which area form, which optional filters, what defaults apply, and when to choose a different tool. Detailed parameter constraints live in the fully-covered schema, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds a valuable high-level grouping: the three mutually exclusive area forms, the clade filter, observer/project filters, and the leaderboard distinction. It composes parameters into coherent use-case patterns rather than merely repeating the schema's per-field notes.

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

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

The description opens with a specific verb and resource: 'Rank the distinct species recorded in an area and period, most-observed first,' and it crystallizes the intent as the 'what lives here' answer. It clearly distinguishes itself from individual-sighting retrieval with 'without paging through individual sightings' and from the leaderboard sibling by name.

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

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

The description gives concrete selection guidance: exactly one area form is allowed, filters like taxon_id/user_id/user_login/project_id are listed, and defaults are stated. It explicitly redirects to inaturalist_get_leaderboard for a different question, giving the agent a clear branch between siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds substantial behavior not captured there: the 95 KB upstream projection, the overflow outline with byte sizes, and the selective-section re-call semantics. This materially changes how an agent should invoke the tool and interpret large responses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose, then moves through prerequisite, projection behavior, overflow handling, and valid section names in logical order. Every sentence earns its place, including the concrete 95 KB detail that justifies the projection step. No filler or redundancy.

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

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

The description fully equips an agent to use this tool correctly: it covers what the profile contains, how to resolve a name first, what happens on large records, how to recover from overflow, and which section names are valid. An output schema exists for return values, so the description doesn't need to restate them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description enriches both parameters beyond the JSON Schema. For taxon_id it warns about the upstream HTTP 422 on non-numeric values and explains why the integer is enforced. For sections it defines the omit-for-whole-profile behavior, overflow outline, and the need to sum byte sizes before requesting multiple sections.

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

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

The description opens with a specific verb and resource: 'Fetch a taxon profile', then enumerates the concrete content (taxonomic path, conservation listings, summary, photos, children, observation counts). This clearly differentiates it from siblings like inaturalist_get_observation and inaturalist_get_species_counts by focusing on the taxon entity and its composite sections.

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

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

It explicitly states the prerequisite workflow: 'Resolve a name to a taxon id with inaturalist_resolve_name first.' It also provides conditional guidance for overflow handling, telling the agent to re-call with section names when the projected profile still overflows. This gives clear when-to-use and how-to-proceed direction beyond the schema.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses critical non-obvious behavior: an unrecognized filter value is not rejected upstream but silently returns nothing, and the conservation codes are normalized search-filter values rather than the taxon record's own free-text status. These are exactly the kind of behavioral traps an agent needs disclosed, and they are consistent with the annotations (no contradiction).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, all substantive: purpose, critical silent-failure warning, conservation-code normalization caveat, and the taxon_id interaction. The most important behavioral warning is front-loaded in sentence two. It is dense rather than bloated, with only a minor flaw: the unexplained 'csi' acronym assumes domain knowledge.

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

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

For a 2-parameter reference tool with an output schema, readOnly and openWorld annotations already present, the description covers purpose, the key usage trap, cross-tool routing, and the one subtle semantic distinction (conservation codes). The only gap is the unexplained 'csi' acronym and no elaboration on the controlled_terms live-cache behavior, which the schema already documents. Overall quite complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 adds real semantic value by clarifying the conservation_status_codes topic — that it is the normalized csi search filter, distinct from a taxon's own conservation_statuses[].status — which the schema's enum label does not convey. It also reinforces the cross-parameter constraint that taxon_id only applies with topic controlled_terms and states the count-carrying output behavior.

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

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

The description opens with a specific verb and resource — 'Decode the vocabularies the other iNaturalist tools take as input' — and enumerates the exact vocabularies (annotation attributes/values, quality grades, license codes, ranks, iconic taxa, IUCN codes). This clearly differentiates it from the sibling data-retrieval tools (get_observation, search_observations, etc.) as the family's reference/decoder tool, with no tautology or ambiguity.

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

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

The description gives explicit when-to-use guidance: 'read the codes here before filtering', reinforced by the concrete consequence of not doing so (silent empty results). It also names an alternative tool for a related step ('Resolve a name to an id with inaturalist_resolve_name') and draws a precise when-not distinction between the normalized search-filter codes and the authority-specific conservation_statuses[].status field. Nothing is left to inference.

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

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

The description discloses key behaviors beyond the read-only and open-world annotations: miss semantics ('found comes back false with guidance naming why'), prefix matching ('Taxon lookup matches a name PREFIX, not words inside a name'), and that rank is only honored on taxon type. These are critical behavioral traits that the agent needs to know, and they are not present in 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, each earning its place: purpose, tool-relationship, miss behavior, and prefix rule. It is front-loaded with the core action and immediately gives the most important behavioral caveat. There is no redundancy or filler.

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

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

With an output schema present, the description does not need to detail return values. It covers the non-obvious usage caveats (prefix matching, miss semantics, rank scoping) and points to the sibling tool for a different need. The description is sufficiently complete for the tool's complexity, complementing the rich schema and annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all parameters with 100% coverage, including the prefix behavior and rank restrictions. However, the description adds a clarifying example ('monarch butterfly' misses where 'monarch' hits) that reinforces the non-obvious substring-matching pitfall, which goes slightly beyond the schema's wording. This extra clarification earns a 4 rather than the baseline 3.

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

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

The description opens with a specific verb and resource: 'Resolve a common or scientific name to a taxon id, or a place, project, or observer name to its id.' It distinguishes the tool from siblings by stating it returns 'the identifiers every other tool takes' and by naming inaturalist_find_places as the alternative for bounding boxes and containment chains. This is unambiguous and not a tautology.

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

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

The description provides clear context: use this tool to get IDs for other tools, and explicitly names when to use inaturalist_find_places instead ('For a place’s bounding box and containment chain rather than just its id'). It also gives an implicit usage rule with the prefix example. However, it does not comprehensively contrast against all sibling tools (e.g., inaturalist_get_taxon or search_observations), so it falls short of a full when/when-not guide.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=true, so the description must carry behavioral detail, and it does thoroughly. It discloses that the default research-grade/wild-only filtering is echoed on every call, that expanding identifications/comments is deliberately blocked (28 KB thread size), that pagination is limited to 10,000 under most orderings, that cursor forces id descending, and that 'term_value_id' sent alone is ignored upstream and returns the unfiltered corpus. It also documents a server-imposed 500 km radius ceiling when the upstream publishes no bound, and warns about HTTP 500 for non-numeric place_id. These are exactly the kind of operational gotchas an agent needs and go far beyond 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Despite its length, the description is remarkably dense with non-redundant, high-value information. It front-loads the core purpose and area constraints, then efficiently covers pagination, expansion limits, and cost estimates. Every sentence earns its place – there is no filler or repetition. For a tool with 38 parameters, this is an appropriately concise and well-structured definition.

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

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

Given the tool's complexity (38 parameters, many mutual exclusions, pagination edge cases, cost considerations) and that an output schema exists, the description is complete. It covers the area forms, defaults, expansion prohibitions, pagination strategy, cost guidance, and key parameter relationships. It also references companion tools for resolving IDs and licenses, leaving no obvious gap an agent would need to discover at runtime. The presence of an output schema means the description need not detail return fields, which it appropriately does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already has a description, but the tool description adds substantial value beyond that baseline. For example, per_page explains the cost in KB and advises using page/cursor rather than larger pages; radius clarifies the 500 km server-imposed ceiling; cursor explains it is sent as id_below; include advises checking photo_count/sound_count first; and term_value_id warns it is ignored unless term_id is present. These enrich parameter semantics far beyond the schema, guiding correct usage and cost awareness.

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

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

The description states a clear, specific purpose: 'Search georeferenced wildlife sightings by area, date, taxon, quality grade, annotation, conservation status, observer, project, and licence.' It specifies the return shape (projected record with coordinates, licence, first photo, identification counts) and distinguishes itself from the sibling inaturalist_get_observation by explicitly stating that identifications and comments are deliberately not expandable and should be fetched there. This differentiation is explicit and actionable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance. It states the three mutually exclusive area forms, explains defaults (research-grade, wild-only), tells the agent to fetch details via inaturalist_get_observation for identifications/comments, and provides a precise pagination strategy beyond 10,000 results (order by id descending, use next_cursor). It also references companion tools like inaturalist_resolve_name and inaturalist_find_places for parameter resolution, making usage unambiguous.

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