gbif-biodiversity-mcp-server

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent) to explain per-name independent matching, input-order results, NONE for no match, ERROR for per-name failures, batch-level success despite individual failures, synonym handling, and the semantics of taxonKey vs. matchedTaxonKey. This matches the annotations and adds essential behavior not otherwise conveyed.

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 well-structured and front-loaded with the core purpose, then expands into behavior and exclusions. Every sentence adds value—covering batch capability, result ordering, error handling, synonym resolution, unsupported names, and confidence guidance—without redundancy or 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 complexity (batch handling, per-name outcomes, error types, synonym behavior) and the existence of a rich output schema, the description covers all critical aspects an agent needs to call it correctly and interpret results. The presence of an output schema means return values don't need to be re-explained, and the description fills in behavioral nuances comprehensively.

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% for both parameters (names and strict), with detailed descriptions including defaults and behavior. The tool description adds no additional parameter-specific semantics beyond what the schema already provides, so it correctly stays at the baseline of 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 clearly states the verb 'resolve', the resource 'scientific names to GBIF backbone taxon keys', and explicitly distinguishes it as the batch counterpart to gbif_match_species. It also specifies the target workflows (checklist, inventory, species-list), making its purpose unambiguous and distinct 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 states when to use the tool (batch workflows needing multiple names) and provides a clear exclusion: common names are not supported, with the alternative gbif_search_species recommended. It also gives a confidence threshold (`Below confidence 80, review the match`) which guides post-call actions.

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 and idempotentHint annotations, the description discloses critical behavioral nuances: the default occurrenceStatus of PRESENT, the absence-record caveat, the blank/whitespace rejection (vs. treating as no filter), and the difference from dataset recordCount. These are non-obvious and essential for correct use.

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 long but every sentence earns its place. It is front-loaded with the purpose, then flows logically into usage, then details each parameter's semantics. The density is high with zero filler, and the structure aids comprehension for a complex tool.

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 an output schema (exempting return-value explanations) and 9 optional parameters, the description covers all necessary edge cases, default behaviors, and integration points with sibling tools. Nothing an agent needs to correctly invoke it 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?

Despite 100% schema coverage, the description adds substantial meaning: it explains why only uppercase two-letter country codes are accepted, the verbatim case-sensitive matching for stateProvince, the interaction between country and publishingCountry, and the default-and-rejection behavior for datasetKey and stateProvince. This goes far beyond repeating 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 differentiates it from sibling gbif_search_occurrences, which fetches records, and states the tool's core function precisely. The scope is 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 states when to use the tool ('quick totals', 'before deciding whether to paginate') and when not to, via the 100,001 offset limitation and the recommendation to partition using gbif_occurrence_facets. It also references the sibling search tool's behavior, providing concrete, actionable 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 provide readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds concrete behavioral detail: contacts are capped by contactLimit (default 10), and contactsTotal/contactsReturned report the full count. This goes beyond the annotations and gives the agent expectations about pagination-like behavior, earning a strong score above baseline.

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 sentences with no filler. The first sentence front-loads the core purpose and main fields; the second provides usage context and the contact cap nuance. Every word earns its place, well-structured for quick comprehension.

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 output schema exists (noted in signals), the description needn't detail return structure, and it doesn't. It covers what metadata is returned, when to use it, and the contactLimit behavior. For a 2-parameter tool with full schema coverage, this is complete and leaves no obvious information gap for the 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%, so both parameters are documented in the schema. However, the description adds value for contactLimit by explaining the 'set to 0' use case and its trade-off (omit contact detail while still reporting contactsTotal), which is not in the schema. It also reinforces datasetKey's source (from search or occurrence record), matching the schema but reaffirming context.

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 it fetches full dataset metadata by UUID key, listing specific fields (title, description, citation, contacts, license, DOI, record count, etc.). It distinguishes itself from sibling tools by explicitly mentioning it is used after gbif_search_datasets or when provenance detail is needed, making it unambiguous which tool this is.

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: 'Use after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail.' It implicitly excludes searching/finding datasets (that's gbif_search_datasets) and occurrence-level retrieval (gbif_get_occurrence), providing clear contextual routing without being verbose.

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, covering safety. The description adds valuable behavioral context: it lists the full Darwin Core record fields returned and explicitly explains the ABSENT occurrenceStatus semantic. This goes beyond the annotations and helps the agent interpret results correctly.

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 well-structured sentences: the first states purpose, the second lists contents, the third gives a critical interpretation warning. No filler, no repetition, and all information is actionable. The most important constraint (check occurrenceStatus) is front-loaded after the purpose.

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-record fetch with an output schema and safety annotations, the description covers the essential workflow (search → get), the return envelope, and the classification nuance. Minor omissions like error behavior or rate limits are not critical for this simple read operation, so it's nearly 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?

The schema already provides full coverage (100%) of the single parameter occurrenceKey with the description 'GBIF occurrence key from gbif_search_occurrences results.' The tool description repeats this same information without adding new syntax, format, or edge-case details. Since the schema carries the load, 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 opens with a clear and specific verb-resource pair: 'Fetch a single occurrence record by its GBIF occurrence key.' It enumerates exactly what the record contains (coordinates, GADM levels, dates, etc.), which distinguishes it from sibling getters like gbif_get_dataset or gbif_get_species. No ambiguity about what this tool does.

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 direct workflow guidance: 'Use the occurrence key from gbif_search_occurrences results' ties it to the search step. It also warns to check occurrenceStatus and explains the meaning of ABSENT, which is critical for correct interpretation. It does not explicitly name alternatives or say when not to use it, but given the tool is the only occurrence getter and has a distinct role, this is adequate.

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 and idempotentHint, covering safety. The description adds valuable non-obvious behavior: the synonym/acceptedKey field relationship and the extinct field's absence semantics. These details are not derivable from schema or annotations and help an agent interpret results correctly. No contradictions.

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 sentences, no extraneous fluff. The core action and return value are front-loaded, followed by usage context and edge-case clarifications. Every sentence earns its place; nothing repetitive or vague.

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 tool has a rich output schema, so the description need not explain return values. It covers purpose, usage trigger, and unusual field behavior. For a single-parameter read-only tool with this much context, nothing critical 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% — the only parameter (taxonKey) has a descriptive schema. The description does not add extra parameter-level meaning, but given the schema already documents the parameter clearly, 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?

Description states a specific verb ('Fetch'), resource ('single backbone taxon'), and the key identifier ('by its GBIF taxon key'). It also enumerates the returned content (classification, authorship, status, vernacular name, descendant count, publication reference), which distinguishes it clearly from sibling tools like gbif_match_species (which returns a match summary) and gbif_get_species_children (which returns children). No 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?

Explicitly says 'Use after gbif_match_species when you need the complete record rather than the match summary,' providing a clear trigger and pointing to the relevant sibling. It does not state when NOT to use it (e.g., 'do not use for bulk matching'), but the positive guidance is sufficient for typical agent routing.

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 useful behavioral context about pagination (offset iteration) and that results are direct children only, which is beyond the annotations. No contradiction 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 two sentences with no redundancy. The purpose is front-loaded, and the usage guidance is concise. Every word earns its place.

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 format is already documented. The description provides the full workflow: get key, list children, paginate. For a simple read-only list tool, nothing an agent needs to call it correctly 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 coverage is 100%, so baseline is 3. The description adds meaning by linking taxonKey to gbif_match_species output and explaining offset for pagination, which goes beyond the schema descriptions. This clarifies how to use the parameters in a realistic workflow.

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 lists direct children of a backbone taxon, with concrete examples (genera within a family, species within a genus). It differentiates from siblings like gbif_get_species_classification by focusing on children rather than ancestors, and mentions the dependency on gbif_match_species for the taxonKey.

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 says to use gbif_match_species to get the taxonKey first and to iterate with offset for large groups, giving clear when-to-use and how-to-use guidance. It doesn't explicitly name alternatives to avoid, but the context of listing children is unambiguous given the sibling set.

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, covering safety and repeatability. The description adds behavioral details beyond these: the array is returned root-first, the queried taxon is excluded, and each entry includes rank, canonical name, and taxon key. This provides a precise contract of the output. 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 filler. The first sentence defines the output and its fields, the second clarifies ordering and exclusion, and the third states the use case. Every sentence adds value and the most critical information is front-loaded.

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 tool has a simple single-parameter interface, and the description fully covers the output format (array, ordering, fields), the exclusion rule, and how to obtain the taxon's own record. Given the presence of an output schema, an agent has everything needed to call this tool correctly without ambiguity.

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 has full coverage (100%) for the single parameter taxonKey, with a clear description: 'GBIF backbone taxon key from gbif_match_species or another taxonomy tool.' The tool description does not add additional semantic meaning beyond this, so the baseline score of 3 is appropriate given that the schema already carries the parameter documentation.

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 exactly what the tool does: 'Return the parent chain for a taxon' and specifies the scope (kingdom to immediate parent), the output format (ordered array with rank, canonical name, taxon key), and explicitly excludes the queried taxon. It clearly differentiates from sibling gbif_get_species by noting that the queried taxon is not included.

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 mentions when to use the tool ('Useful for building taxonomic trees or understanding placement') and provides an alternative: 'call gbif_get_species for its own record.' It also implies efficiency by avoiding level-by-level navigation through the backbone. This gives clear guidance on when to use this tool versus 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 (readOnlyHint, openWorldHint, idempotentHint) already signal safety. The description adds high-value behavioral details like synonym resolution (taxonKey vs matchedTaxonKey), the 80-confidence review threshold, and the meaning of matchType NONE—all beyond what annotations convey.

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?

Well-structured and front-loaded: purpose first, then critical workflow context, then edge-case behavior. Every sentence serves a purpose—no filler. Approximately 200 words, acceptable given the richness of information.

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 complements it by explaining key output fields (taxonKey, matchedTaxonKey, matchType, confidence) and how to interpret them. Covers synonyms, confidence thresholds, and failure cases. Nothing essential for correct invocation 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 all parameters are well-documented. The description largely restates schema content (e.g., rank to avoid genus matching, strict flag behavior) without adding new meaning. It maintains baseline adequacy but does not elevate understanding 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?

States a specific verb ('Match'), a precise resource ('scientific name against the GBIF backbone taxonomy'), and describes the output (taxon with classification and confidence). It differentiates from siblings by naming the mandatory first-step role and explicitly routing vernacular name searches to gbif_search_species.

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 declares this as the mandatory first step for GBIF workflows, lists dependent tools, names the alternative (gbif_search_species) for common names, and provides concrete troubleshooting for matchType NONE (remove strict flag or broaden name). Guidance is direct 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?

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral context: it explains the paging ranking and offset semantics, warns that some dimensions silently drop records (the YEAR example with 883,550 undated records), notes that stateProvince is matched verbatim and case-sensitive, and explains that blank values are rejected rather than dropped by GBIF. These are critical execution behaviors not captured by 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 compact yet dense; every sentence earns its place. It front-loads the core purpose and examples, then adds the large-set splitting strategy and edge-case behaviors. Despite covering many nuances, there is no filler or redundant repetition of schema content. The structure (purpose → examples → caveats) is logical and scannable.

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 13 parameters and an output schema, the description covers all critical usage aspects: the paging mechanism (facetLimit, facetOffset), the default occurrenceStatus behavior, the splitting workaround for large result sets, and the data-loss caveats for certain dimensions. It also points to sibling tools for obtaining datasetKey. Nothing an agent needs to correctly call this tool 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. The description provides tool-level guidance (paging, splitting, default scope) but does not add per-parameter semantic detail beyond what the schema already documents. The schema descriptions themselves are exhaustive, so the description's role is more about usage context than parameter semantics.

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: 'Aggregate occurrence counts across a dimension' and lists the dimensions explicitly (COUNTRY, YEAR, DATASET_KEY, etc.). It differentiates from siblings by contrasting with gbif_search_occurrences ('No record payloads returned') and notes it complements gbif_count_occurrences. The 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?

It provides explicit when-to-use scenarios: 'Core tool for distribution analysis and trend queries' with concrete example questions, and a specific alternative routing: 'Also the way to split a result set too large for gbif_search_occurrences to page (offset+limit caps at 100,001): facet by DATASET_KEY, then search each datasetKey on its own.' It also clarifies the default occurrenceStatus to match sibling tools, giving the agent clear decision criteria.

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 (readOnly, openWorld, idempotent), the description discloses crucial behavioral nuances: case-sensitive UUID matching, rejection of blank q values and the upstream consequences, and that the two organization filters are intersected, not combined. These details go well beyond annotations and materially affect invocation.

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?

A single dense paragraph that front-loads the core purpose and then delivers usage guidance. Though lengthy, every sentence carries distinct value (purpose, filter distinction, return list, use cases). It could be split into bullet points, but it remains efficient for the 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?

For a read-only, entirely optional-parameter search tool with a rich output schema, the description comprehensively covers purpose, filters, return fields, and the non-obvious behaviors (case sensitivity, filter intersection, blank q handling). Combined with the schema and annotations, an agent has everything needed to select and call 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?

The schema already provides 100% coverage with exhaustive per-parameter descriptions (formats, examples, rejection rules). The description adds meta-level semantics that the schema does not: which filter answers 'whose data it is' versus 'whose installation serves it,' and the recommendation to use publishingOrg for publisher keys. This enriches meaning 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 ('Search') and resource ('GBIF datasets'), and enumerates the exact criteria (keyword, type, country, publishing/hosting organization). It also states what it returns (title, description, license, record count, DOI) and gives concrete use cases, differentiating it from sibling tools that search other resources.

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 use cases are given ('find the source dataset behind a set of records, or explore what data collections are available...'). The description also routes the agent to the correct organization filter by noting that a key from gbif_search_publishers 'usually wants publishingOrg,' distinguishing it from the alternative. It does not explicitly exclude other search tools, but the 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 carry readOnlyHint, openWorldHint, and idempotentHint, so the description rightly spends no time re-declaring safety. It adds genuinely new behavioral value: the sightings-only-by-default behavior with occurrenceStatus controlling absence records, the hard 100,001 offset+limit cap with no cursor/scroll, and the no-bulk-download limitation — all critical facts an agent needs and none derivable from 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?

Five dense sentences front-loaded with purpose, then filters, default behavior, pagination, and the bulk-download limitation in logical order. The length is earned by the tool's 19-parameter complexity and the real gotchas it must convey; it is heavy but not padded with 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?

With an output schema covering return values and 100% schema coverage, nearly everything an agent needs is present. The description closes the remaining gaps: presence-only default, pagination ceiling and partitioning remedy, and bulk-download alternatives. For a tool of this complexity, no material calling concern is left unaddressed.

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 exceptionally rich per-parameter descriptions, so baseline 3 applies. The description adds strategic semantic value on top: recommending taxonKey over scientificName, the DATASET_KEY partitioning strategy for pagination, and the country-vs-publishingCountry distinction. The marginal addition is real but largely synthetic, with most param detail correctly living in 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 states a specific verb (Search), a precise resource (3.9B+ GBIF occurrence records), and a scope (Darwin Core filters). This clearly distinguishes it from siblings like gbif_count_occurrences (counting), gbif_occurrence_facets (facet aggregation), and gbif_get_occurrence (single-record retrieval), so an agent can pick it without inspecting schemas.

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 routes to gbif_match_species for taxonKey, gbif_occurrence_facets for partitioning large result sets, and the GBIF Download API / AWS Open Data for bulk download, with clear when-not guidance ('This server cannot download a result set in bulk'). It could have explicitly pointed to gbif_count_occurrences for count-only needs or gbif_get_occurrence for a single record, but the exclusions and alternatives given are strong.

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 indicate readOnly, openWorld, and idempotent hints. The description adds behavioral nuances beyond these: blank or whitespace values for 'q' are rejected rather than sent, empty country strings are rejected, and invalid country codes error instead of returning empty lists. These specifics help an agent avoid mistakes. No contradiction 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?

Three well-structured sentences: the first states the core function, the second explains return value and chain usage, the third adds an important caveat. No filler, all sentences earn their place, and key information is front-loaded.

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 focuses on use context, which it covers thoroughly: what it returns, how to chain it, which chain is most common, and edge-case handling. The description is complete for an agent to call it correctly and interpret 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?

Schema coverage is 100%, so baseline is 3. The description goes further by clarifying edge cases: omitting 'q' browses without a term, blank 'q' is rejected, country accepts alpha-2 and alpha-3 forms and is case-insensitive, and invalid country codes error. This adds meaningful semantic detail beyond the schema's 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 a specific verb ('Search') and resource ('organizations registered with GBIF') and clarifies scope ('by name fragment or country'). It also names the return fields and distinguishes itself from sibling tools (e.g., search_datasets) by its focus on publishers. This gives clear purpose and 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 explicitly explains when to use the tool: to chain into gbif_search_datasets as publishingOrg or hostingOrg, and gives a concrete rule of thumb (publishingOrg is usual, hostingOrg matches nothing for most). It also conveys the purpose for regional analysis. This is explicit, 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?

The description goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations, disclosing concrete behaviors: higher-taxon names are resolved to backbone keys, alternative names resolve to synonyms, unmatched names fail rather than returning everything, matching is exact and capitalization-sensitive, blank values are rejected, and pagination works via limit/offset. All of this adds value beyond the annotations, and there is 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?

Although long, every sentence is information-dense and earns its place. The structure front-loads purpose, then usage, then behavioral nuances, and then parameter specifics. It is not padded or redundant; the length is justified by the complexity of GBIF's matching and scoping behavior.

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 9 parameters, an output schema exists, and annotations cover safety, the description thoroughly covers the operational context: matching rules, synonym resolution, exact capitalization, blank-value pitfalls, pagination, and failure modes. No critical information an agent needs to call this correctly 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 coverage is 100%, yet the description adds substantial meaning to every parameter: it explains why blank values are rejected (GBIF returns the whole 46M-name index), how genus/family/kingdom interact and disambiguate (e.g., 'Prunella'), how synonym resolution works (Compositae → Asteraceae), and constraints like genus-specific families. This is far more than the schema provides, richly compensating for the 9-parameter surface.

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 pair ('Search or browse the GBIF backbone taxonomy') and immediately clarifies what it accepts (name fragments, rank filters, higher-taxon constraints). It distinguishes itself from a sibling by stating it is useful 'when gbif_match_species returns too narrow a result,' so an agent can tell them apart without inspecting schemas.

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 usage contexts are given: exploring what species exist under a higher taxon, simple name-fragment searches, and as a fallback when gbif_match_species is too narrow. It also differentiates browsing vs searching and explains when higher-taxon scope applies, giving 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.