gbif-biodiversity-mcp-server

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

Even with annotations declaring readOnlyHint, openWorldHint, and idempotentHint, the description goes far beyond them by explaining per-name independence, input-order preservation, matchType NONE/ERROR semantics, batch-wide success despite individual failures, and synonym handling. This rich behavioral detail is 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 concise but information-dense, with every sentence serving a distinct purpose: main action, batch context, failure/synonym behavior, exclusion, and confidence note. It is front-loaded with the primary action and contains zero wasted words.

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 covers the tool's edge cases: no-match (NONE), per-name errors (ERROR), batch success despite failures, synonym resolution, and input ordering. It also mentions the confidence threshold. With an output schema present, no return-value explanation is needed, making this description complete for a tool of this 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%, and both parameters (names, strict) already have descriptions in the schema. The description adds the constraint that common names are not supported, which slightly clarifies the 'names' parameter, but it does not materially extend parameter semantics beyond the schema. Baseline 3 is appropriate.

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 'Resolve' and resource 'scientific names to GBIF backbone taxon keys', immediately clarifying the tool's function. It further distinguishes itself from the sibling gbif_match_species by explicitly labeling it as the 'batch counterpart', making the purpose unmistakable.

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 exactly when to use the tool ('for checklist, inventory, and species-list workflows that would otherwise need one round trip per name'). It also provides a clear exclusion and alternative: 'Common names are not supported — use gbif_search_species for vernacular searches.' The confidence threshold adds further practical 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses important behaviors: default occurrenceStatus is PRESENT, GBIF indexes absence records which can dominate some taxa, blank or whitespace-only values are rejected for year/country/stateProvince/datasetKey, and the count may differ from dataset recordCount. These details are crucial for accurate interpretation and go far beyond the structured metadata.

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. It starts with the core purpose, then explains usage context, lists parameters, and covers edge cases. No redundant or filler sentences; the length is justified by the tool's complexity and the need to communicate critical caveats.

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 has 9 optional parameters and an output schema, the description covers all essential aspects: purpose, use cases, alternative tools, parameter semantics, and behavioral quirks. The output schema handles return value details, so the description does not need to repeat them. It is fully complete 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?

Even though schema coverage is 100%, the description adds substantial meaning. For example, it explains the difference between country and publishingCountry with a concrete statistic, warns that lowercase/alpha-3 forms match nothing, details exact case-sensitive matching for stateProvince, and clarifies the behavior of blank values vs. omission. Each parameter's pitfalls and correct usage are articulated well beyond the schema definitions.

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: 'Count occurrences matching a taxon + location filter without fetching records.' This clearly distinguishes it from gbif_search_occurrences, which fetches records, and from other sibling tools. The scope is explicit and the tool's purpose is unmistakable.

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 when to use this tool: 'Use for quick totals' and 'or before deciding whether to paginate a full search.' It also names the alternative tool gbif_search_occurrences and explains the limitation at offset 100,001, directing the user to gbif_occurrence_facets for partitioned searches. This is clear when-to-use and when-not-to-use 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 readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral details beyond annotations, such as the contactLimit cap, contactsTotal/contactsReturned counts, and the ability to set contactLimit to 0 to omit contact detail while still reporting totals. This provides transparency about output limits without contradicting 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 three sentences, each earning its place: the first states what the tool returns, the second provides usage context, and the third explains contact behavior. It is front-loaded and free of 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?

Given the tool's moderate complexity, complete parameter schema, and presence of an output schema, the description covers purpose, usage, and key behavior (contact capping) sufficiently. It does not need to explain return values since the output schema exists, and the annotations cover safety aspects.

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% with both parameters documented, but the description adds valuable context: datasetKey is sourced from search or occurrence records, and contactLimit's use case (e.g., high-contact datasets like eBird) is explained in the description, enriching the schema's baseline.

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 clearly states the tool fetches full dataset metadata by UUID key, listing the specific fields returned (title, description, citation, contacts, license, etc.). It differentiates from siblings by explicitly noting when to use it (after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail).

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 usage context: 'Use after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail.' It does not enumerate exclusions or alternatives, but the context is clear and sufficient for a get-by-ID tool.

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, openWorldHint, and idempotentHint, so the safety profile is known. The description adds behavioral context by enumerating the full returned payload and explaining that ABSENT means the taxon was not found, which goes beyond the annotations without contradicting them.

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 structured in three sentences: a clear first sentence stating purpose, a detailed enumeration of return contents, and a vital caution about ABSENT plus key sourcing. Every sentence earns its place, though the field list makes it slightly longer than strictly minimal.

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 single-parameter tool with an output schema and strong annotations, the description provides comprehensive context: it specifies the complete return payload, highlights an important interpretation pitfall, and tells the agent where to obtain the key. This is more than sufficient for correct invocation.

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 schema fully documents the single parameter and its description ('GBIF occurrence key from gbif_search_occurrences results') matches the tool description. The tool description adds no new parameter semantics beyond reinforcing the key source, so a baseline of 3 is appropriate.

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 action ('Fetch') and resource ('single occurrence record by its GBIF occurrence key'), and distinguishes it from sibling tools by emphasizing 'single record' and referencing gbif_search_occurrences for the key.

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 instructs to use the occurrence key from gbif_search_occurrences results, establishing a clear prerequisite. It also warns about ABSENT occurrenceStatus, which is a valuable interpretation guideline. It does not explicitly name alternatives, but the usage context is clear.

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 provide readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful context beyond these: specific return fields, synonym handling (acceptedKey/accepted), and the extinct field's optional presence, which are important behavioral traits for an agent to know.

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, each earning its place: function, return content, usage recommendation, and edge-case behavior. No redundancy or fluff, and critical information is front-loaded in the first sentence.

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 a single parameter, an output schema, and strong annotations, the description covers all necessary aspects: what it returns, when to use it, and special cases (synonyms, extinct field). It is complete enough for an agent to invoke correctly without further clarification.

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 the schema description already explains taxonKey as 'GBIF backbone taxon key from gbif_match_species or another taxonomy tool.' The tool description adds no new parameter detail beyond what the schema provides, so the baseline of 3 is appropriate.

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 clearly states the tool fetches a single backbone taxon by GBIF taxon key, which is a specific verb+resource+scope. It distinguishes from siblings like gbif_get_species_children and gbif_match_species by explicitly mentioning the complete record vs match summary.

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?

Explicitly directs users to use this after gbif_match_species when the complete record is needed, providing a clear when-to-use vs alternative. It also gives guidance on interpreting taxonomicStatus and the extinct field, which helps correct usage.

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 cover read-only, open-world, and idempotent behavior. The description adds valuable behavioral details: results are paginated, children are direct (not all descendants), and the workflow depends on a prior matching step. No contradictions with 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 three sentences with no redundancy. The first sentence states the purpose, the second notes pagination, and the third gives a workflow tip. Every sentence earns its place and is easy to scan.

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, return value details are unnecessary. The description covers what the tool does, how to obtain the required taxonKey, and how to handle pagination. It does not discuss error cases, but for a simple listing tool this is acceptable and annotations compensate for safety-related gaps.

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 covers all three parameters with clear descriptions (100% coverage), so the description does not need to repeat them. It adds a small amount of context by mentioning the offset iteration, but the schema already documents the pagination parameters adequately. Baseline 3 is appropriate.

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 uses a specific verb ('List') with a clear resource ('direct children of a backbone taxon') and provides concrete examples of children ranks (genera, species, subspecies). This fully distinguishes it from sibling tools like gbif_get_species_classification (which lists ancestors) and gbif_match_species (which matches names).

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 contextual guidance: it identifies the prerequisite of obtaining a taxonKey via gbif_match_species and explains pagination with offset. It does not explicitly name alternatives to avoid, but the usage context is unambiguous 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?

Beyond the annotations (read-only, idempotent), the description discloses the root-first ordering, the exclusion of the queried taxon, and the per-entry fields (rank, canonical name, taxon key). This is valuable behavioral detail for an AI agent.

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?

Two well-organized sentences convey purpose, specifics, and a use case with no wasted words.

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 a single parameter, complete schema coverage, and an output schema, the description effectively captures the ordering, exclusion, and content of the response, making the tool fully understandable.

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 schema fully describes taxonKey with 100% coverage, referencing gbif_match_species. The description adds the behavioral nuance that this key identifies the queried taxon whose own record is excluded, slightly enriching parameter understanding.

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 clearly states the tool returns the parent chain for a taxon from kingdom/domain down to the immediate parent, as an ordered array. It distinguishes itself from sibling tools by explicitly noting the queried taxon is excluded and directing users to gbif_get_species for that record.

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 provides explicit usage context ('building taxonomic trees or understanding placement') and names gbif_get_species as the alternative when the queried taxon's own record is needed. This tells the agent when to choose this tool over related 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?

Beyond the readOnly/idempotent/openWorld annotations, the description discloses key behaviors: synonym resolution (taxonKey vs matchedTaxonKey), the significance of confidence scores ('Below confidence 80, the match should be reviewed'), and the meaning of matchType NONE. This provides actionable context for interpreting results without contradicting 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 information-dense yet well-structured: it opens with the primary purpose, then covers return value, mandatory usage, synonym edge case, confidence threshold, and failure handling. Every sentence contributes meaningful guidance with 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 and rich annotations, the description still adds essential context: the role in the workflow, synonym key semantics, confidence interpretation, and fallback strategies. It covers both normal use and edge cases, making the tool's behavior fully understandable for an agent.

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%, and the input schema already provides thorough descriptions for all four parameters. The tool description itself does not add parameter-specific semantics beyond what the schema offers, so the baseline of 3 is appropriate. The only param-related guidance ('pass taxonKey') concerns output fields, not input parameters.

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 clearly states the tool's function: 'Match a scientific name against the GBIF backbone taxonomy' and what it returns ('best-matching taxon with full classification and a confidence score'). It distinguishes itself from siblings by positioning itself as the 'mandatory first step' returning the taxonKey required by other GBIF tools, and contrasts with gbif_search_species for vernacular names.

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?

Explicit when-to-use: 'mandatory first step for any GBIF workflow' and names the dependent tools. It also gives exclusion guidance: 'Common names are not supported — use gbif_search_species for vernacular name searches.' Additionally, it advises remedial action when no match is found ('try removing the strict flag or broadening the name').

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 readOnly/openWorld/idempotent. The description adds that it returns one page of ranked facet values, no record payloads, and that it aggregates sightings only by default (matching sibling tools). It also explains paging semantics and how to measure presence/absence splitting, adding behavioral context beyond 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 dense but every sentence earns its place, covering purpose, paging, use cases, scoping, sibling differentiation, and defaults. It is front-loaded with the core function and logically organized, though slightly long.

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 rich parameter schema, the description completes the picture by covering when to use the tool, how pagination works, default behavior, and relationship to siblings. It is fully adequate for an agent to select and invoke the 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 coverage is 100% with detailed descriptions for all 13 parameters, including extensive guidance for facet. The main description adds high-level grouping of which parameters serve as filters, and the facet parameter's schema description explains gap-free vs lossy dimensions with a concrete example. This goes beyond the baseline.

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 clearly states the tool aggregates occurrence counts across a dimension, names example dimensions, and differentiates from sibling tools like gbif_search_occurrences and gbif_count_occurrences by mentioning no record payloads and its role in splitting large result sets. This is a specific verb+resource with clear scope.

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 tool is core for distribution and trend queries with example questions, and gives a concrete alternative scenario: when a result set is too large for gbif_search_occurrences to page, facet by DATASET_KEY and search each datasetKey. It also clarifies the default occurrenceStatus matches other occurrence tools, guiding when to adjust.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it specifies the return payload ("title, description, license, record count, and DOI") and explains the distinct semantics of the two organization filters ("publishingOrg matches the organization whose data it is, hostingOrg the organization whose installation serves it"). This goes beyond the basic annotations without contradicting them.

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, front-loaded with the core action, then provides org-filter clarification, return fields, and use cases. No sentence is wasted; every one adds semantic value. It is dense but not bloated, making it easy for an agent to parse quickly.

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 rich input schema (100% parameter coverage, enums, defaults), the strong annotations (read-only, open-world, idempotent), and the existence of an output schema, the description covers the essential contextual points: what the tool searches, what it returns, and when to use it. The only minor gap is not explicitly naming alternatives, but the use cases and filter guidance compensate. For a search tool of this complexity, it is complete.

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 value beyond the schema by guiding parameter choice: "an organization key from gbif_search_publishers usually wants publishingOrg" and by clarifying that publishing country must be uppercase ISO 3166-1 alpha-2. This is not redundant with the schema and helps disambiguate the two organization parameters.

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: "Search GBIF datasets by keyword, type, publishing country (uppercase ISO 3166-1 alpha-2), publishing organization, or hosting organization." It clearly states what the tool does and enumerates filter dimensions. It indirectly distinguishes from siblings by noting that an organization key from gbif_search_publishers usually wants publishingOrg, but it does not explicitly contrast with gbif_get_dataset or other search tools, so it misses the top score for explicit sibling differentiation.

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 explicit use cases: "Use to find the source dataset behind a set of records, or to explore what data collections are available for a taxon, country, or organization." It also gives a concrete cross-tool guideline about when to use publishingOrg vs hostingOrg. However, it does not state when not to use the tool or name an alternative (e.g., gbif_get_dataset for a specific dataset), so it stops 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?

Despite annotations providing readOnly/openWorld/idempotent hints, the description adds substantial behavioral context: pagination capped at offset+limit=100,001, no cursor/scroll, blank values rejected (not dropped), occurrenceStatus defaults to PRESENT, stateProvince exact case-sensitive matching, scientificName OR semantics with taxonKey, and the inability to bulk-download from this server. No annotation 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?

The description is information-dense yet well-organized, front-loaded with the core purpose, and every sentence adds value — including caveats and cross-references to sibling tools. It is appropriately sized for a complex tool with 19 parameters.

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 (19 parameters, output schema exists), the description covers all critical aspects: filtering options, default behavior, pagination constraints, large-result handling, and bulk download limitations. No gaps detected.

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% but the description enriches parameters with non-obvious semantics: e.g., stateProvince is exact match, country/publishingCountry are distinct and frequently disagree, offset/limit reach a hard ceiling, scientificName ORs with taxonKey instead of AND, and blank/whitespace values rejected. This goes far beyond the schema's basic descriptions.

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 'Search 3.9B+ GBIF occurrence records with Darwin Core filters' — a specific verb, resource, and scope. It clearly differentiates from sibling tools like gbif_count_occurrences and gbif_facets by its focus on occurrence search/retrieval.

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?

Description provides explicit guidance: recommends using taxonKey from gbif_match_species, mentions using gbif_occurrence_facets for large result sets, and directs bulk download needs to the GBIF Download API or AWS Open Data. Also differentiates country vs publishingCountry and when to use facets for partitioning.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds behavioral context by specifying the return format ('organization key, title, and country') and explaining the data-availability nuance about hostingOrg, which is beyond 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?

Three sentences, each with a distinct purpose: purpose statement, return value, and chaining guidance. No redundant phrasing.

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 read-only search tool with 4 optional parameters, full schema coverage, and an output schema, the description provides sufficient context for selecting and invoking it. It covers the core use and the most important pitfall (hostingOrg matching nothing).

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%, with detailed descriptions for q, limit, offset, and country. The description only mentions 'by name fragment or country' and does not add parameter syntax or edge cases beyond the schema, so it neither compensates nor repeats—the schema does the heavy lifting.

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 the tool's function clearly: 'Search organizations registered with GBIF by name fragment or country.' It also distinguishes it from siblings by mentioning the returned key/title/country and the chaining to gbif_search_datasets, making the purpose unambiguous.

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 use this tool and how to chain it: 'sufficient to chain into gbif_search_datasets as publishingOrg... or as hostingOrg.' It also clarifies the common pattern ('publishingOrg is the usual chain') and warns that 'hostingOrg matches nothing for them,' giving practical 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 readOnlyHint, openWorldHint, and idempotentHint, and the description adds substantial behavioral context beyond those: how kingdom/family/genus scoping resolves to backbone keys, synonym resolution, exact-capitalization matching, failure behavior for unmatched names, pagination, and rejection of blank values. This gives the agent a clear model of the tool's execution.

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 but is well-structured: purpose first, then usage scenarios, then key behavioral notes (scoping, capitalization, pagination). Every sentence contributes meaningful information without redundancy. It is appropriately sized for the tool's complexity.

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 9 parameters, no required fields, and a rich output schema, the description covers all critical operational aspects: pagination, scoping behavior, matching semantics, and blank-value handling. It does not need to explain return values because the output schema exists. The tool is fully contextualized within its sibling set.

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 main description adds some context about the interplay of kingdom/family/genus (narrowest scope wins, disambiguation), but each parameter's schema description already contains detailed semantics. The description does not materially enrich what the schema already provides.

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: 'Search or browse the GBIF backbone taxonomy.' It clearly distinguishes itself from the sibling gbif_match_species by explaining it is useful 'when gbif_match_species returns too narrow a result' and for exploring higher-taxon lists. This makes the tool's unique role unambiguous.

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 when to use the tool: exploring species under a higher taxon, simple name-fragment searches, and as an alternative when gbif_match_species is too narrow. It also provides behavioral exclusions, such as name matching being exact and capitalized, and that blank values are rejected, guiding correct usage.

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