Skip to main content
Glama

paleobiology-mcp-server: diversity through time

paleobiology_get_diversity
Read-onlyIdempotent

Compute a diversity / origination / extinction curve for a clade across geologic time, binned by period, epoch, or age — answers "plot dinosaur genus diversity across the Mesozoic." Pass a clade-inclusive base_name (or base_id, the same clade by resolved taxon id — exactly one of the two) and bound the span by a named interval (e.g. "Mesozoic") or a max_ma/min_ma range; choose what to count (genera, species, or families) and the bin resolution. The full bin set returns inline — a diversity series is a bounded set of geologic intervals — so you read the curve, the turnover, and the per-bin origination/extinction directly. Counts reflect SAMPLED diversity, biased by collection effort and rock availability, not true past diversity.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "paleobiology_get_diversity"
  }
}

Input Schema

NameRequiredDescriptionDefault
countNoWhat to count per bin: "genera" (default), "species", or "families".genera
latmaxNoNorthern latitude edge in degrees; valid alone as a half-plane. PBDB normalizes inverted latitude bounds.
latminNoSouthern latitude edge in degrees; valid alone as a half-plane.
lngmaxNoEastern longitude edge in degrees; requires lngmin.
lngminNoWestern longitude edge in degrees; requires lngmax. A pair may cross the antimeridian.
max_maNoOlder bound of the span in millions of years ago. Alternative to interval. When paired with min_ma it must be strictly greater — max_ma is the deeper-time end of the span.
min_maNoYounger bound of the span in millions of years ago. Alternative to interval. When paired with max_ma it must be strictly smaller — min_ma is the nearer-to-present end of the span.
recentNoWhen true, extend taxa PBDB knows are extant to the present instead of ending their ranges at the latest selected fossil. Default false preserves fossil-only counts; selection-boundary effects still apply.
base_idNoClade-inclusive taxon to count, by PBDB taxon id — use accepted_no from paleobiology_get_taxon or an occurrence row for an accepted-clade search. Supply this or base_name (exactly one is required, never both).
countryNoPBDB country or continent codes, e.g. "US", "NOA,^US", or "!EUR,^IS".
intervalNoNamed geologic interval bounding the span, e.g. "Mesozoic". Alternative to max_ma/min_ma.
base_nameNoClade-inclusive taxon to count, e.g. "Dinosauria" or "Ammonoidea" — this taxon and all descendants. Supply this or base_id (exactly one is required, never both).
formationNoStored formation name, e.g. "Hell Creek"; comma lists and SQL wildcards are passed unchanged. Do not append Formation unless it is part of the stored name.
resolutionNoBin resolution: "period" (default, coarse), "epoch", or "age" (finest).period
environmentNoDepositional environment: marine, terrestrial, or freshwater (lacustrine + fluvial).

Output Schema

NameRequiredDescriptionDefault
binsNoPer-interval diversity bins over the span, ordered oldest-first (oldest geologic interval, highest max_ma, first).
errorNoPresent when the call failed. Absent on success.
noticeNoSampled-turnover interpretation, effective extant-range policy, selection-boundary guidance, empty-result selectors and ignored-filter warnings.
totalCountNoNumber of geologic-interval bins returned.
attributionNoCC-BY data attribution for the Paleobiology Database.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • changedInput schema / properties / base_id / description
      Previous value: -"Clade-inclusive taxon to count, by PBDB taxon id — the taxon_no from paleobiology_get_taxon, or accepted_no on an occurrence row. Same semantics as base_name, but unambiguous where a name is not (homonyms, synonyms, unresolved spellings). Supply this or base_name (exactly one is required, never both)."New value: +"Clade-inclusive taxon to count, by PBDB taxon id — use accepted_no from paleobiology_get_taxon or an occurrence row for an accepted-clade search. Supply this or base_name (exactly one is required, never both)."
    • addedInput schema / properties / country
      Added value: +{
      +  "description": "PBDB country or continent codes, e.g. \"US\", \"NOA,^US\", or \"!EUR,^IS\".",
      +  "pattern": "^[!^]?(?:[A-Z]{2}|NOA|SOA|EUR|ASI|AFR|AUS|ATA|OCE|IOC)(?:,\\^?(?:[A-Z]{2}|NOA|SOA|EUR|ASI|AFR|AUS|ATA|OCE|IOC))*$",
      +  "type": "string"
      +}
    • addedInput schema / properties / environment
      Added value: +{
      +  "description": "Depositional environment: marine, terrestrial, or freshwater (lacustrine + fluvial).",
      +  "enum": [
      +    "marine",
      +    "terrestrial",
      +    "freshwater"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / formation
      Added value: +{
      +  "description": "Stored formation name, e.g. \"Hell Creek\"; comma lists and SQL wildcards are passed unchanged. Do not append Formation unless it is part of the stored name.",
      +  "type": "string"
      +}
    • addedInput schema / properties / latmax
      Added value: +{
      +  "description": "Northern latitude edge in degrees; valid alone as a half-plane. PBDB normalizes inverted latitude bounds.",
      +  "maximum": 90,
      +  "minimum": -90,
      +  "type": "number"
      +}
    • addedInput schema / properties / latmin
      Added value: +{
      +  "description": "Southern latitude edge in degrees; valid alone as a half-plane.",
      +  "maximum": 90,
      +  "minimum": -90,
      +  "type": "number"
      +}
    • addedInput schema / properties / lngmax
      Added value: +{
      +  "description": "Eastern longitude edge in degrees; requires lngmin.",
      +  "maximum": 180,
      +  "minimum": -180,
      +  "type": "number"
      +}
    • addedInput schema / properties / lngmin
      Added value: +{
      +  "description": "Western longitude edge in degrees; requires lngmax. A pair may cross the antimeridian.",
      +  "maximum": 180,
      +  "minimum": -180,
      +  "type": "number"
      +}
    • addedInput schema / properties / recent
      Added value: +{
      +  "default": false,
      +  "description": "When true, extend taxa PBDB knows are extant to the present instead of ending their ranges at the latest selected fossil. Default false preserves fossil-only counts; selection-boundary effects still apply.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / bins / items / properties / extinctions / description
      Previous value: -"Taxa whose last appearance is in this bin (LADs, including bin-only singletons)."New value: +"Last appearances within the selected occurrence set, including bin-only singletons; these are not established biological extinctions."
    • changedOutput schema / properties / bins / items / properties / originations / description
      Previous value: -"Taxa whose first appearance is in this bin (new FADs, including bin-only singletons)."New value: +"First appearances within the selected occurrence set, including bin-only singletons; selection boundaries can truncate ranges."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_filter`: Neither base_name nor base_id was supplied — a diversity curve needs a clade to count. `conflicting_taxon_filter`: Both base_name and base_id were supplied — PBDB accepts only one clade selector. `inverted_ma_range`: min_ma was greater than or equal to max_ma — the span is inverted or empty. `pbdb_invalid_parameter`: PBDB refused a filter value it could not use, such as an unknown interval name — the message quotes its reason. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `incomplete_bbox`: Exactly one of lngmin and lngmax was supplied. `missing_filter`: Neither base_name nor base_id was supplied — a diversity curve needs a clade to count. `conflicting_taxon_filter`: Both base_name and base_id were supplied — PBDB accepts only one clade selector. `inverted_ma_range`: min_ma was greater than or equal to max_ma — the span is inverted or empty. `pbdb_invalid_parameter`: PBDB refused a filter value it could not use, such as an unknown interval name — the message quotes its reason. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "missing_filter",
      -  "conflicting_taxon_filter",
      -  "inverted_ma_range",
      -  "pbdb_invalid_parameter"
      -]New value: +[
      +  "incomplete_bbox",
      +  "missing_filter",
      +  "conflicting_taxon_filter",
      +  "inverted_ma_range",
      +  "pbdb_invalid_parameter"
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the clade or span produced no bins, or when the taxon name could not be resolved and was ignored."New value: +"Sampled-turnover interpretation, effective extant-range policy, selection-boundary guidance, empty-result selectors and ignored-filter warnings."
  2. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_filter`: Neither base_name nor base_id was supplied — a diversity curve needs a clade to count. `conflicting_taxon_filter`: Both base_name and base_id were supplied — PBDB accepts only one clade selector. `inverted_ma_range`: min_ma was greater than or equal to max_ma — the span is inverted or empty. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_filter`: Neither base_name nor base_id was supplied — a diversity curve needs a clade to count. `conflicting_taxon_filter`: Both base_name and base_id were supplied — PBDB accepts only one clade selector. `inverted_ma_range`: min_ma was greater than or equal to max_ma — the span is inverted or empty. `pbdb_invalid_parameter`: PBDB refused a filter value it could not use, such as an unknown interval name — the message quotes its reason. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "missing_filter",
      -  "conflicting_taxon_filter",
      -  "inverted_ma_range"
      -]New value: +[
      +  "missing_filter",
      +  "conflicting_taxon_filter",
      +  "inverted_ma_range",
      +  "pbdb_invalid_parameter"
      +]
  3. First observed

TDQS

A3.9/5.0
Behavior5/5

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

Adds substantial context beyond the readOnly/idempotent annotations: the full bin set returns inline with no pagination concern, the response contains per-bin origination/extinction and turnover, and counts are SAMPLED diversity biased by collection effort and rock availability rather than true past diversity. That caveat is exactly the kind of interpretive warning an agent needs before reporting results.

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

Conciseness4/5

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

The core purpose is front-loaded in the first clause, and every sentence contributes (example, parameter pairing rules, inline return, sampling caveat). It is dense and runs as one long paragraph, but there is little wasted text.

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

Completeness4/5

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

For a 15-parameter tool with full schema coverage, an output schema, and safety annotations, the description covers purpose, the critical parameter pairings, return shape, and the sampling-bias caveat. Spatial/filter parameters are left entirely to the schema, which is acceptable given its richness.

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

Parameters3/5

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

Schema coverage is 100%, so all 15 parameters are already documented in the schema, and the description largely restates the key ones (count, resolution, base_name/base_id exclusivity, interval vs max_ma/min_ma). It adds relational framing but does not explain the spatial, country, formation, environment, or recent filters, leaving the schema to carry those.

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

Purpose4/5

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

States a precise verb and resource: compute a diversity/origination/extinction curve for a clade binned by period/epoch/age, with a concrete example question. The function is clearly distinct from sibling search tools, though it never explicitly names an alternative to route away from.

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

Usage Guidelines3/5

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

The example ('plot dinosaur genus diversity across the Mesozoic') implies when this tool applies, and it clarifies in-tool alternatives (interval vs max_ma/min_ma, base_name vs base_id). However, there is no explicit guidance on when to prefer this over paleobiology_search_occurrences or the dataframe tools, and no stated exclusions.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.