paleobiology-mcp-server

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful context about what is listed, where the data comes from, and how the result should be used, 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?

Two sentences with clear front-loading: the action and resource are stated first, followed by the actionable usage guidance. No filler or redundant restatement of the tool name or title.

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 low-complexity introspection tool with an output schema and strong annotations, the description is complete. It tells the agent what the tool does, where the canvas_id comes from, and how to use the result, leaving no critical 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 schema already fully describes canvas_id, including its origin from paleobiology_search_occurrences when its result spilled. The description does not add new parameter-level semantics beyond restating the intended use context, so baseline 3 applies given 100% schema coverage.

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') and identifies the exact resource ('tables and their columns staged on a DataCanvas'). It also names the preceding tool, paleobiology_search_occurrences, making it clear what the tool does and how it fits into the workflow.

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 ('Call this before paleobiology_dataframe_query') and why: to discover table_name and column names for SQL. This gives an agent clear sequencing guidance versus its closest sibling 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 and idempotentHint, but the description adds substantial behavioral context beyond that: staged rows are occurrences so collection-only fields like lithology are absent, classification is JSON and requires json_extract_string for rank rollups, and writes/file-reading functions are rejected. It also clarifies the relationship between search_occurrences and this staging step. This is rich disclosure 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?

The description is appropriately sized for a complex query tool and is front-loaded with the core purpose. Every sentence provides distinct value: use case, column hints, schema notes, prerequisites, and constraints. No filler or repetition of obvious 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?

For a tool with two parameters and an output schema, this description covers all decision-relevant context: what the staged data is, how to reference it, what can be analyzed, what fields are missing, how to handle JSON classification, and when to call describe first. An agent has everything needed to invoke this tool safely and 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% and both parameters are already described in the input schema, including the read-only SQL constraint and the source of the canvas_id. The description restates those details but adds little new parameter-specific semantics beyond reinforcing that table names come from search_occurrences. Baseline 3 is appropriate because schema already covers the 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 and resource: 'Run a read-only SQL SELECT against occurrence result sets staged on a DataCanvas by paleobiology_search_occurrences.' It clearly distinguishes itself from sibling search/describe tools by positioning itself as the analysis step after staging data. The purpose is unambiguous and agents can immediately tell it apart from the sibling tools.

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: 'This is how you analyze a large fossil set without re-fetching it.' It also names the prerequisite alternative: 'call paleobiology_dataframe_describe first if you do not know the table or column names.' It sets clear boundaries with 'SELECT only; writes and file-reading functions are rejected,' which excludes misuse.

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 already declaring readOnlyHint, idempotentHint, and openWorldHint, the description adds substantial non-obvious behavioral context: 'Counts reflect SAMPLED diversity, biased by collection effort and rock availability, not true past diversity' — an interpretive caveat that prevents an agent from drawing false conclusions about the numbers. It also discloses return semantics ('The full bin set returns inline ... so you read the curve, the turnover, and the per-bin origination/extinction directly'), which is valuable beyond any structured field.

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 of about four sentences, and every sentence earns its place: function, required inputs, return semantics, and the sampling caveat. The core statement and example use case are front-loaded. It is appropriately sized for a 7-parameter tool, though slight paragraph breaks would improve scannability.

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 7 parameters, an output schema, and no required fields in the schema, the description covers every decision an agent must make: clade selection (with the exactly-one rule), time bounding (two alternative strategies), count target, bin resolution, return semantics, and the interpretive caveat. Nothing an agent needs to invoke 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 description coverage is 100%, and the individual parameter descriptions in the schema are exceptionally thorough — max_ma/min_ma even explain which is the deeper-time versus nearer-to-present bound. The tool description reinforces the exact-one-of-base_name/base_id constraint and the interval-vs-range alternative, but these are already present in the schema. Baseline 3 is appropriate: the schema carries 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 names a specific verb and resource: 'Compute a diversity / origination / extinction curve for a clade across geologic time, binned by period, epoch, or age.' It anchors the function with a concrete user query ('answers "plot dinosaur genus diversity across the Mesozoic"') and the scope is clearly distinct from every sibling — none of the dataframe, taxon, interval, collection, or occurrence tools compute curves.

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 input-routing guidance: 'Pass a clade-inclusive base_name (or base_id ... exactly one of the two)' and 'bound the span by a named interval ... or a max_ma/min_ma range.' It clearly separates the two alternative bounding strategies. It does not explicitly name a sibling to prefer in other cases, but the sibling set is functionally so different that an agent's routing is unambiguous.

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 readOnly and idempotent. The description adds useful behavioral context: PBDB taxonomy is opinionated, the accepted name may differ from GBIF, and the resolved id appears as accepted_no on occurrence rows. It doesn't describe unresolved-name failure behavior, but the output schema and annotations cover most safety and side-effect concerns.

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 reasonably dense but every sentence earns its place: what it returns, when to run it, how to chain it, when to use show_children, and a relevant caveat. It is front-loaded with the main purpose and avoids boilerplate.

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, idempotent tool with a complete input schema and output schema, this description covers all the essential context: purpose, workflow, sibling routing, optional children retrieval, and taxonomy differences. An agent has enough to select and invoke it 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 cover age is 100%, so the description doesn't need to re-explain parameters. It does add workflow context about choosing name vs taxon_no and using show_children, but this is more about orchestration than parameter syntax or 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 clearly states the tool's job: resolve a taxon by name or taxon_no and return accepted name, rank, higher classification, parent, occurrence count, and FAD/LAD range. It also names the sibling tools it belongs with, distinguishing this lookup-and-resolve step from the later search tools.

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 instructs the agent to run this tool first to resolve a name into accepted name and taxon_no, then pass that id as base_id to three named siblings. It also tells when to use show_children, and warns that accepted names may differ from the searched name due to PBDB taxonomy.

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 substantial non-obvious behavior beyond these: offline answers on the bundled ICS snapshot, a one-PBDB-lookup cost for unsupported names, and the response naming which source/scale answered. 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?

Four sentences, front-loaded with purpose and role, followed by filtering options and then offline/online behavior. It is dense but every sentence carries distinct information with no filler or repetition of schema text.

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 lookup tool with zero required parameters, an output schema, full schema coverage, and safety annotations, the description covers filter combinations, offline vs online behavior, response provenance, and the tool's role relative to siblings. 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 a baseline of 3 applies, but the description enriches every parameter: case-insensitive substring matching vs exact PBDB matching for non-bundled names, overlap semantics of the Ma range, and the level restriction to eon/era/period/epoch/age. The no-filter browse behavior is also made explicit.

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 and resource: look up the geologic time scale with eons, eras, periods, epochs, and ages and their Ma boundaries. It also distinguishes itself from the sibling data-query tools by declaring that it grounds every temporal filter on the other tools, so an agent can route correctly.

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 tells the agent when to use the tool — as the reference grounding temporal filters on the other tools — and how to call it: filter by name substring, Ma range, level, or no filters to browse the full scale. It also clarifies the offline vs one-PBDB-lookup behavior for names not in the bundled snapshot, which is exactly the decision-relevant usage context.

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 cover read-only/idempotent/open-world safety, and the description adds behavior beyond that: inline limit/offset pagination with a disclosed 'more remaining' signal, clade-inclusive taxon semantics, and edge-case filter rules (lone latitude edge, closed longitude pair, strict max_ma/min_ma ordering). 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 long but information-dense, with the core purpose first, then return fields, filters, pagination, and sibling routing in logical order. Every clause serves a distinct role and there is no filler or tautology.

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 14-parameter, 0-required search tool, this is complete: it covers what results contain, all meaningful filter families, pagination behavior, and how to continue into paleobiology_search_occurrences. The output schema exists, so not detailing return structure here is appropriate.

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 already 100%, but the description adds relational meaning: base_name and base_id are mutually exclusive alternate spellings of the same clade filter, interval is an alternative to max_ma/min_ma, and collection_no from a row can be fed into the occurrence tool. This goes well beyond the per-parameter schema text.

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 ('Find') and resource ('fossil collections (localities)'), and immediately distinguishes the tool from siblings by scoping it to area and geologic time. It also states exactly what each returned locality contains, so an agent can tell this from search_occurrences.

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 enumerates the filter dimensions and gives concrete examples ('Dinosauria', 'Maastrichtian', 'Hell Creek'). It names the sibling paleobiology_search_occurrences and tells the agent when to move from collections to occurrences, which is clear routing 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 readOnly and idempotent hints, the description discloses important behavioral traits: the two distinct coordinate systems and the warning never to plot deep-time occurrences on a modern coastline, the staging of large result sets onto a DataCanvas, the per-call cap, and the fact that reusing a canvas_id replaces the prior table. It also explains pagination behavior with total counts, covered rows, and next-page offsets, adding real context the annotations alone do not 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?

Though long, the description is dense and every clause earns its place; there is no filler or restatement of the schema. It is front-loaded with the core purpose, then flows naturally from filter choices to output behavior to related tools, making the complexity navigable for an agent.

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 flagship search tool with many siblings, the description is unusually complete: it covers required filters, taxon resolution, age/geography/collection constraints, coordinate-system pitfalls, large-result staging, downstream SQL access, and pagination. The output schema can carry the return-value details, so the description need not restate them; 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?

The input schema already documents all 15 parameters at 100% coverage, but the description adds cross-parameter semantics that the schema cannot convey: the clade-inclusive meaning of base_name vs exact taxon_name, the mutual exclusivity of base_name and base_id, the relationship between max_ma/min_ma and named intervals, and the rule that longitude must be supplied as a closed pair. It also explains that location and time filters can work together and that a lone latitude edge is valid.

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 — 'Search fossil occurrences' — and enumerates the filter dimensions (taxon, time, geography, environment), so an agent immediately knows what the tool does. It also distinguishes itself from sibling tools like paleobiology_search_collections and paleobiology_get_taxon by positioning this as the occurrence-level search and referencing the others only for supporting steps.

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: resolve names with paleobiology_get_taxon first, take collection_no from paleobiology_search_collections rows, and route SQL-style analysis to paleobiology_dataframe_query. It also clarifies choice points among alternatives such as base_name vs base_id vs taxon_name and interval vs max_ma/min_ma, and states the hard requirement that at least one filter is supplied.

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