paleobiology-mcp-server

Search fossil occurrences filtered by taxon, geologic time, geography, and depositional environment — the flagship. Use base_name for a clade and all its descendants (what "Tyrannosaurus occurrences" usually means), base_id for that same clade by resolved taxon id, or taxon_name for an exact taxon. Bound the age by a named interval (e.g. "Maastrichtian") or a max_ma/min_ma range, and/or a lng/lat bounding box; scope to a single locality with collection_no (take it from a paleobiology_search_collections row). At least one filter is required — taxon, time, place, environment, or collection_no. Every row carries two distinct coordinate systems — modern lng/lat (where the rock is today) and paleo lng/lat (where the landmass sat at deposition) — plus the formation, age interval, and higher classification (phylum through genus); never plot a deep-time occurrence on a modern coastline. Resolve a name with paleobiology_get_taxon first if unsure. Broad queries return many rows: an inline preview answers the immediate question, and when the set outgrows that preview the matching occurrences — up to the per-call cap — stage on a DataCanvas (canvas_id + table_name, returned only then) for SQL via paleobiology_dataframe_query (count by interval, group by formation/country, map by region). The response reports how many occurrences matched in total, which rows this page covers, and the offset that reaches the next page — page through the whole match set with limit/offset.

{
  "type": "object",
  "properties": {
    "base_name": {
      "description": "Clade-inclusive taxon filter — this taxon and all descendants, e.g. \"Dinosauria\". The usual choice. Supply this or base_id, never both.",
      "type": "string"
    },
    "base_id": {
      "description": "Clade-inclusive taxon filter by PBDB taxon id — the taxon_no from paleobiology_get_taxon, or accepted_no on an occurrence row. Same clade-inclusive semantics as base_name, but unambiguous where a name is not (homonyms, synonyms, unresolved spellings). Supply this or base_name, never both.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "taxon_name": {
      "description": "Exact taxon filter — only this taxon, not descendants. Use instead of base_name when you want a single taxon.",
      "type": "string"
    },
    "collection_no": {
      "description": "Restrict to one collection (locality) by its PBDB collection_no — the fauna found together at that site. Take the id from a paleobiology_search_collections row to drill from a locality into its occurrences.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "interval": {
      "description": "Named geologic interval bounding the age, e.g. \"Cretaceous\" or \"Maastrichtian\". Alternative to max_ma/min_ma.",
      "type": "string"
    },
    "max_ma": {
      "description": "Older age bound 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 window.",
      "type": "number",
      "minimum": 0
    },
    "min_ma": {
      "description": "Younger age bound 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 window.",
      "type": "number",
      "minimum": 0
    },
    "lngmin": {
      "description": "Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "lngmax": {
      "description": "Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "latmin": {
      "description": "Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "latmax": {
      "description": "Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "environment": {
      "description": "Depositional environment: \"marine\", \"terrestrial\", or \"freshwater\" (lacustrine + fluvial). Omit for all.",
      "type": "string",
      "enum": [
        "marine",
        "terrestrial",
        "freshwater"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Maximum occurrences to pull per page (1–500). Caps the pull (further bounded by PBDB_MAX_OCCURRENCES); broad queries stage that page on the canvas for SQL. Pair with offset to walk the whole match set.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 0,
      "description": "Number of matching occurrences to skip before this page — page with limit by advancing offset. The response notice names the exact offset that reaches the next page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "canvas_id": {
      "description": "Canvas id from a prior call to re-stage onto the same workspace. Reusing it REPLACES (overwrites) the prior occurrence table — each search restages the full result, it does not append to or accumulate across earlier ones. Omit to start fresh; the response returns a new id.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "occurrences": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "occurrence_no": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "PBDB occurrence id — read the full record via the paleobiology://occurrence/{occurrence_no} resource."
          },
          "collection_no": {
            "description": "Locality this came from — chain into paleobiology_search_collections.",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "identified_name": {
            "description": "The original field/published identification.",
            "type": "string"
          },
          "identified_rank": {
            "description": "Rank of the identified name.",
            "type": "string"
          },
          "accepted_name": {
            "description": "PBDB accepted name (may differ from the identification under synonymy).",
            "type": "string"
          },
          "accepted_rank": {
            "description": "Rank of the accepted name.",
            "type": "string"
          },
          "accepted_no": {
            "description": "PBDB taxon id of the accepted name — chain into paleobiology_get_taxon.",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "early_interval": {
            "description": "Named geologic interval of the older age bound, e.g. \"Late Maastrichtian\".",
            "type": "string"
          },
          "late_interval": {
            "description": "Named interval of the younger bound — present only when the age spans two intervals.",
            "type": "string"
          },
          "max_ma": {
            "description": "Older age bound in millions of years ago.",
            "type": "number"
          },
          "min_ma": {
            "description": "Younger age bound in millions of years ago.",
            "type": "number"
          },
          "lng": {
            "description": "MODERN longitude — where the rock sits today. Not where the organism lived.",
            "type": "number"
          },
          "lat": {
            "description": "MODERN latitude — where the rock sits today. Not where the organism lived.",
            "type": "number"
          },
          "paleolng": {
            "description": "PALEO longitude — where the landmass sat at deposition. Omitted when PBDB has no reconstruction.",
            "type": "number"
          },
          "paleolat": {
            "description": "PALEO latitude — where the landmass sat at deposition. Omitted when PBDB has no reconstruction.",
            "type": "number"
          },
          "paleomodel": {
            "description": "Plate-tectonic model used for the paleo-coordinates (e.g. \"gplates\"). They are model-dependent.",
            "type": "string"
          },
          "geoplate": {
            "description": "Tectonic plate id under the paleo-model, when reported.",
            "type": "string"
          },
          "formation": {
            "description": "Geologic formation, when recorded.",
            "type": "string"
          },
          "geological_group": {
            "description": "Geologic group, when recorded.",
            "type": "string"
          },
          "member": {
            "description": "Geologic member, when recorded.",
            "type": "string"
          },
          "cc": {
            "description": "ISO 3166-1 alpha-2 country code of the modern locality, when known.",
            "type": "string"
          },
          "state": {
            "description": "State/province of the modern locality, when known.",
            "type": "string"
          },
          "county": {
            "description": "County of the modern locality, when known.",
            "type": "string"
          },
          "classification": {
            "description": "Higher classification of the accepted name (phylum → genus) — group rows by family or order without a per-row paleobiology_get_taxon call. Each level is present only when PBDB resolves it; omitted entirely when PBDB resolves none.",
            "type": "object",
            "properties": {
              "phylum": {
                "description": "Phylum, when classified.",
                "type": "string"
              },
              "class": {
                "description": "Class, when classified.",
                "type": "string"
              },
              "order": {
                "description": "Order, when classified (PBDB sentinel orders are omitted).",
                "type": "string"
              },
              "family": {
                "description": "Family, when classified.",
                "type": "string"
              },
              "genus": {
                "description": "Genus, when classified.",
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "reference_no": {
            "description": "PBDB bibliographic reference id for provenance.",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "occurrence_no"
        ],
        "additionalProperties": false,
        "description": "A single fossil occurrence with modern and paleo coordinates, age, strata, and classification."
      },
      "description": "Inline preview of matching occurrences for the requested page. The staged occurrence set is on the canvas when spilled is true — it is one page of the match set rather than every match (the notice states which rows this page covers, how many matched upstream, and the offset that reaches the next page)."
    },
    "spilled": {
      "type": "boolean",
      "description": "True when the result exceeded the inline preview and the staged occurrence set was written to the canvas."
    },
    "canvas_id": {
      "description": "Canvas id holding the staged occurrence set — pass to paleobiology_dataframe_query. Present only when spilled is true; a result that fit inline stages nothing, so there is no table to query.",
      "type": "string"
    },
    "table_name": {
      "description": "Canvas table holding the staged occurrence set. Present only when spilled is true.",
      "type": "string"
    },
    "row_count": {
      "type": "number",
      "description": "Rows staged on the canvas when spilled; otherwise the preview length. Capped at the per-call limit (PBDB_MAX_OCCURRENCES) — compare against the totalCount enrichment for how many matched upstream."
    },
    "totalCount": {
      "type": "number",
      "description": "Total occurrences matching the filters upstream — the number this call was drawn from, which may exceed the staged set."
    },
    "notice": {
      "description": "Guidance when no occurrence matched, when results spilled to the canvas, when occurrences remain past this page (naming the offset that reaches the next one), when offset ran past the end of the match set, when a filter value was not recognized and ignored, or when DataCanvas is off.",
      "type": "string"
    },
    "attribution": {
      "type": "string",
      "description": "CC-BY data attribution for the Paleobiology Database."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `missing_filter`: The call carried only pagination fields — no taxon, time, place, environment, or collection filter. `conflicting_taxon_filter`: Both base_name and base_id were supplied — PBDB accepts only one clade selector. `incomplete_bbox`: Exactly one of lngmin/lngmax was supplied — a longitude box needs both edges. `inverted_ma_range`: min_ma was greater than or equal to max_ma — the age window is inverted or empty. Other values are possible when a failure originates below the handler.",
              "examples": [
                "missing_filter",
                "conflicting_taxon_filter",
                "incomplete_bbox",
                "inverted_ma_range"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "occurrences",
        "spilled",
        "row_count",
        "totalCount",
        "attribution"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Resolve a taxon by name (e.g. "Tyrannosaurus") or by integer taxon_no to its accepted name, rank, higher classification, immediate parent, fossil occurrence count, and first/last appearance (FAD/LAD) range in millions of years — "when did this clade exist, and what is it." Run this first to resolve a name into the accepted name and taxon_no, then pass that id as base_id to paleobiology_search_occurrences, paleobiology_get_diversity, or paleobiology_search_collections for a clade-inclusive filter that carries no name ambiguity (the same id also appears as accepted_no on occurrence rows). Set show_children to also list immediate child taxa. PBDB taxonomy is opinionated and can differ from GBIF's backbone, so the accepted name may differ from the name you searched.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Taxon name to resolve, e.g. \"Tyrannosaurus\" or \"Ammonoidea\". Provide this or taxon_no.",
      "type": "string"
    },
    "taxon_no": {
      "description": "PBDB taxon id from a prior get_taxon, or accepted_no on an occurrence row. Provide this or name.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "show_children": {
      "default": false,
      "description": "When true, include a page of the immediate child taxa of this taxon (at most 200 per call — children_truncated says whether more remain).",
      "type": "boolean"
    },
    "children_offset": {
      "default": 0,
      "description": "Number of immediate children to skip before the returned page — used only when show_children is true. Advance it by 200 while children_truncated is true to walk the whole child list.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "taxon_no": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Accepted PBDB taxon id — the canonical id for this taxon. Pass it as base_id to paleobiology_search_occurrences, paleobiology_get_diversity, or paleobiology_search_collections to filter on this clade without re-sending a name."
    },
    "accepted_name": {
      "type": "string",
      "description": "PBDB accepted name (may differ from the searched name)."
    },
    "rank": {
      "type": "string",
      "description": "Taxonomic rank, e.g. \"genus\", \"family\", \"order\"."
    },
    "parent_no": {
      "description": "PBDB taxon id of the immediate parent, when known.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "parent_name": {
      "description": "Name of the immediate parent taxon, when known.",
      "type": "string"
    },
    "classification": {
      "type": "object",
      "properties": {
        "phylum": {
          "description": "Phylum, when classified.",
          "type": "string"
        },
        "class": {
          "description": "Class, when classified.",
          "type": "string"
        },
        "order": {
          "description": "Order, when classified (PBDB sentinel orders are omitted).",
          "type": "string"
        },
        "family": {
          "description": "Family, when classified.",
          "type": "string"
        },
        "genus": {
          "description": "Genus, when classified.",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "description": "Higher classification of the taxon. Each level is present only when PBDB resolves it."
    },
    "extant": {
      "type": "boolean",
      "description": "True if the clade survives to the present day; false if entirely extinct."
    },
    "occurrence_count": {
      "description": "Number of fossil occurrences recorded in PBDB, when reported.",
      "type": "number"
    },
    "first_appearance": {
      "type": "object",
      "properties": {
        "max_ma": {
          "description": "Older bound of the appearance window (Ma).",
          "type": "number"
        },
        "min_ma": {
          "description": "Younger bound of the appearance window (Ma).",
          "type": "number"
        },
        "interval": {
          "description": "Named geologic interval of this appearance, when known.",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "description": "A first- or last-appearance window. Empty when PBDB has no dated occurrences."
    },
    "last_appearance": {
      "type": "object",
      "properties": {
        "max_ma": {
          "description": "Older bound of the appearance window (Ma).",
          "type": "number"
        },
        "min_ma": {
          "description": "Younger bound of the appearance window (Ma).",
          "type": "number"
        },
        "interval": {
          "description": "Named geologic interval of this appearance, when known.",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "description": "A first- or last-appearance window. Empty when PBDB has no dated occurrences."
    },
    "children": {
      "description": "One page of immediate child taxa, at most 200 — present only when show_children was true. A taxon with more children than that returns a page, not the full list; read children_truncated before treating it as complete.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "taxon_no": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "PBDB taxon id of the child — chain into paleobiology_get_taxon."
          },
          "name": {
            "description": "Child taxon name.",
            "type": "string"
          },
          "rank": {
            "description": "Child taxon rank, e.g. \"genus\" or \"subfamily\".",
            "type": "string"
          },
          "occurrence_count": {
            "description": "Fossil occurrence count for the child, when reported.",
            "type": "number"
          },
          "synonym_of": {
            "description": "Present when this child is a synonym; names the accepted taxon it folds into.",
            "type": "string"
          }
        },
        "required": [
          "taxon_no"
        ],
        "additionalProperties": false,
        "description": "An immediate child taxon stub."
      }
    },
    "children_offset": {
      "description": "Position in the child list this page started at (0 is the first child). Present only when show_children was true.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "children_truncated": {
      "description": "True when more immediate children remain past this page — re-call with children_offset advanced by 200 to read the next. False means this page runs to the end of the child list. Present only when show_children was true.",
      "type": "boolean"
    },
    "notice": {
      "description": "Guidance when the child list was cut off at the per-page cap (naming the children_offset that reaches the next page), or when children_offset ran past the end of the child list.",
      "type": "string"
    },
    "attribution": {
      "type": "string",
      "description": "CC-BY data attribution for the Paleobiology Database."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `taxon_not_found`: The name or taxon_no resolved to no PBDB taxon. `missing_selector`: Neither name nor taxon_no was provided. Other values are possible when a failure originates below the handler.",
              "examples": [
                "taxon_not_found",
                "missing_selector"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "taxon_no",
        "accepted_name",
        "rank",
        "classification",
        "extant",
        "first_appearance",
        "last_appearance",
        "attribution"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "base_name": {
      "description": "Clade-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).",
      "type": "string"
    },
    "base_id": {
      "description": "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).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "count": {
      "default": "genera",
      "description": "What to count per bin: \"genera\" (default), \"species\", or \"families\".",
      "type": "string",
      "enum": [
        "genera",
        "species",
        "families"
      ]
    },
    "resolution": {
      "default": "period",
      "description": "Bin resolution: \"period\" (default, coarse), \"epoch\", or \"age\" (finest).",
      "type": "string",
      "enum": [
        "period",
        "epoch",
        "age"
      ]
    },
    "interval": {
      "description": "Named geologic interval bounding the span, e.g. \"Mesozoic\". Alternative to max_ma/min_ma.",
      "type": "string"
    },
    "max_ma": {
      "description": "Older 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.",
      "type": "number",
      "minimum": 0
    },
    "min_ma": {
      "description": "Younger 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.",
      "type": "number",
      "minimum": 0
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "bins": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "interval": {
            "type": "string",
            "description": "Geologic interval (bin) name, e.g. \"Cretaceous\"."
          },
          "max_ma": {
            "type": "number",
            "description": "Older boundary of the bin in millions of years ago."
          },
          "min_ma": {
            "type": "number",
            "description": "Younger boundary of the bin in millions of years ago."
          },
          "sampled_in_bin": {
            "type": "number",
            "description": "Taxa with at least one occurrence inside this bin."
          },
          "implied": {
            "type": "number",
            "description": "Range-through taxa implied present in the bin but without an occurrence in it."
          },
          "originations": {
            "type": "number",
            "description": "Taxa whose first appearance is in this bin (new FADs, including bin-only singletons)."
          },
          "extinctions": {
            "type": "number",
            "description": "Taxa whose last appearance is in this bin (LADs, including bin-only singletons)."
          },
          "range_through": {
            "type": "number",
            "description": "Taxa whose range crosses both boundaries of this bin (present before and after)."
          },
          "n_occurrences": {
            "type": "number",
            "description": "Total fossil occurrences counted in this bin."
          }
        },
        "required": [
          "interval",
          "max_ma",
          "min_ma",
          "sampled_in_bin",
          "implied",
          "originations",
          "extinctions",
          "range_through",
          "n_occurrences"
        ],
        "additionalProperties": false,
        "description": "One diversity bin (a single geologic interval) with turnover counts."
      },
      "description": "Per-interval diversity bins over the span, ordered oldest-first (oldest geologic interval, highest max_ma, first)."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of geologic-interval bins returned."
    },
    "notice": {
      "description": "Guidance when the clade or span produced no bins, or when the taxon name could not be resolved and was ignored.",
      "type": "string"
    },
    "attribution": {
      "type": "string",
      "description": "CC-BY data attribution for the Paleobiology Database."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "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.",
              "examples": [
                "missing_filter",
                "conflicting_taxon_filter",
                "inverted_ma_range"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "bins",
        "totalCount",
        "attribution"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Look up the geologic time scale — eons, eras, periods, epochs, and ages with their absolute-age boundaries in millions of years (Ma) and nesting. This is the reference that grounds every temporal filter on the other tools and translates a named interval like "Late Cretaceous" to its 100.5–66.0 Ma boundaries (and back). Filter by a name substring, a Ma range (overlap match), and/or a level; call with no filters to browse the full scale. Browsing and every name on the bundled ICS international-scale snapshot are answered offline. A name the snapshot does not carry — the sub-stage and regional names that occurrence and collection rows report, such as "Late Maastrichtian" or "Lancian" — costs one PBDB lookup across its other time scales; the response names which source answered and which scale the interval belongs to.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Case-insensitive substring of the interval name, e.g. \"cretaceous\" or \"Jurassic\". A name the bundled international scale does not carry is matched exactly against PBDB's other time scales.",
      "type": "string"
    },
    "min_ma": {
      "description": "Younger bound of an age window (Ma); intervals overlapping [min_ma, max_ma] match.",
      "type": "number",
      "minimum": 0
    },
    "max_ma": {
      "description": "Older bound of an age window (Ma); intervals overlapping [min_ma, max_ma] match.",
      "type": "number",
      "minimum": 0
    },
    "level": {
      "description": "Restrict to one rank of the international scale: eon, era, period, epoch, or age (finest). Browsing is bounded to that scale, so the sub-stage and regional ranks are not selectable here.",
      "type": "string",
      "enum": [
        "eon",
        "era",
        "period",
        "epoch",
        "age"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "intervals": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "interval_no": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "PBDB interval id for this geologic interval."
          },
          "name": {
            "type": "string",
            "description": "Interval name, e.g. \"Maastrichtian\" or \"Late Maastrichtian\"."
          },
          "level": {
            "type": "string",
            "description": "Rank of the interval in its time scale. The international scale uses eon > era > period > epoch > age (finest); other PBDB scales also use subepoch, subage, zone, subzone, chron, subchron, and bin."
          },
          "max_ma": {
            "type": "number",
            "description": "Older (bottom) boundary in millions of years ago."
          },
          "min_ma": {
            "type": "number",
            "description": "Younger (top) boundary in millions of years ago."
          },
          "parent_no": {
            "description": "PBDB id of the containing interval (epoch→period→era→eon). Omitted at the top.",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "abbrev": {
            "description": "Standard abbreviation (e.g. \"K\" for Cretaceous), when defined.",
            "type": "string"
          },
          "color": {
            "description": "ICS chart hex color for this interval, when defined.",
            "type": "string"
          },
          "scale": {
            "description": "The PBDB time scale carrying this interval, e.g. \"Mesozoic Subages\" or \"North American Land Mammal Ages\". Present only on an interval resolved upstream — every bundled interval is on the international scale, which snapshot_version names.",
            "type": "string"
          }
        },
        "required": [
          "interval_no",
          "name",
          "level",
          "max_ma",
          "min_ma"
        ],
        "additionalProperties": false,
        "description": "A geologic time interval with its rank, Ma boundaries, and parent."
      },
      "description": "Matching geologic intervals, sorted oldest-first."
    },
    "source": {
      "type": "string",
      "enum": [
        "bundled_ics",
        "pbdb_upstream"
      ],
      "description": "Which source answered: \"bundled_ics\" for the offline international-scale snapshot, \"pbdb_upstream\" for a name resolved live against PBDB's other time scales."
    },
    "snapshot_version": {
      "type": "string",
      "description": "ICS chart version and generation date of the bundled time scale, for citation."
    },
    "totalCount": {
      "type": "number",
      "description": "Number of intervals matched by the filters."
    },
    "notice": {
      "description": "Guidance when no interval matched the filters.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `interval_not_found`: A named interval filter matched nothing — neither the bundled international scale (after any level or Ma filters) nor a PBDB lookup across its other time scales. `interval_lookup_unavailable`: The name is outside the bundled international scale and the PBDB lookup that covers the other time scales could not be reached. Other values are possible when a failure originates below the handler.",
              "examples": [
                "interval_not_found",
                "interval_lookup_unavailable"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "intervals",
        "source",
        "snapshot_version",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Find fossil collections (localities) by area and geologic time — "what has been dug up here, and from what rock." Each locality returns its location, age (named interval and Ma), formation and strata, lithology, depositional environment, and the count of co-occurring fossils. Filter by a clade-inclusive base_name (or base_id, the same clade by resolved taxon id), a named interval or max_ma/min_ma range, a lng/lat bounding box, a formation or lithology name, and/or an environment. Results page inline via limit/offset (the response discloses when more remain). Take a collection_no from a row and pass it — or the same bbox+interval — to paleobiology_search_occurrences to see the actual fauna found together.

{
  "type": "object",
  "properties": {
    "base_name": {
      "description": "Clade-inclusive taxon filter — localities yielding this taxon or its descendants, e.g. \"Dinosauria\". Supply this or base_id, never both.",
      "type": "string"
    },
    "base_id": {
      "description": "Clade-inclusive taxon filter 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, never both.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "interval": {
      "description": "Named geologic interval bounding the age, e.g. \"Maastrichtian\". Alternative to max_ma/min_ma.",
      "type": "string"
    },
    "max_ma": {
      "description": "Older age bound in millions of years ago. When paired with min_ma it must be strictly greater — max_ma is the deeper-time end of the window.",
      "type": "number",
      "minimum": 0
    },
    "min_ma": {
      "description": "Younger age bound in millions of years ago. When paired with max_ma it must be strictly smaller — min_ma is the nearer-to-present end of the window.",
      "type": "number",
      "minimum": 0
    },
    "lngmin": {
      "description": "Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "lngmax": {
      "description": "Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "latmin": {
      "description": "Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "latmax": {
      "description": "Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "formation": {
      "description": "Geologic formation name to filter by, e.g. \"Hell Creek\".",
      "type": "string"
    },
    "lithology": {
      "description": "Lithology (rock type) to filter by, e.g. \"sandstone\".",
      "type": "string"
    },
    "environment": {
      "description": "Depositional environment: \"marine\", \"terrestrial\", or \"freshwater\" (lacustrine + fluvial). Omit for all.",
      "type": "string",
      "enum": [
        "marine",
        "terrestrial",
        "freshwater"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Maximum localities to return per page (1–500).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 0,
      "description": "Number of localities to skip — page with limit by advancing offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "collections": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "collection_no": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "PBDB collection (locality) id — scope paleobiology_search_occurrences to it for the fauna found here."
          },
          "collection_name": {
            "description": "Locality name, when recorded.",
            "type": "string"
          },
          "lng": {
            "description": "MODERN longitude of the locality (where the rock is today).",
            "type": "number"
          },
          "lat": {
            "description": "MODERN latitude of the locality (where the rock is today).",
            "type": "number"
          },
          "early_interval": {
            "description": "Named interval of the older age bound, e.g. \"Late Maastrichtian\".",
            "type": "string"
          },
          "late_interval": {
            "description": "Named interval of the younger bound — present when the age spans two intervals.",
            "type": "string"
          },
          "max_ma": {
            "description": "Older age bound in millions of years ago.",
            "type": "number"
          },
          "min_ma": {
            "description": "Younger age bound in millions of years ago.",
            "type": "number"
          },
          "formation": {
            "description": "Geologic formation, when recorded.",
            "type": "string"
          },
          "geological_group": {
            "description": "Geologic group, when recorded.",
            "type": "string"
          },
          "member": {
            "description": "Geologic member, when recorded.",
            "type": "string"
          },
          "lithology": {
            "description": "Primary lithology (rock type), when recorded.",
            "type": "string"
          },
          "lithology_description": {
            "description": "Free-text lithology description, when recorded.",
            "type": "string"
          },
          "environment": {
            "description": "Depositional environment as PBDB recorded it (finer than the filter enum), when known.",
            "type": "string"
          },
          "cc": {
            "description": "ISO 3166-1 alpha-2 country code, when known.",
            "type": "string"
          },
          "state": {
            "description": "State/province, when known.",
            "type": "string"
          },
          "county": {
            "description": "County, when known.",
            "type": "string"
          },
          "n_occs": {
            "description": "Number of fossil occurrences (co-occurring taxa) recorded at this locality.",
            "type": "number"
          },
          "reference_no": {
            "description": "PBDB bibliographic reference id for provenance.",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "collection_no"
        ],
        "additionalProperties": false,
        "description": "A fossil collection (locality) with its age, strata, lithology, and environment."
      },
      "description": "Matching localities for this page."
    },
    "totalCount": {
      "description": "Total localities matching the filters upstream, across all pages.",
      "type": "number"
    },
    "truncated": {
      "description": "True when localities remain past this page — advance offset for more.",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of localities returned in this page (set when truncated).",
      "type": "number"
    },
    "cap": {
      "description": "The per-page limit that was applied (set when truncated).",
      "type": "number"
    },
    "notice": {
      "description": "Guidance when no locality matched, when localities remain past this page, or when a filter value was not recognized and ignored.",
      "type": "string"
    },
    "attribution": {
      "type": "string",
      "description": "CC-BY data attribution for the Paleobiology Database."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `missing_filter`: The call carried only pagination fields — no taxon, time, place, formation, lithology, or environment filter. `conflicting_taxon_filter`: Both base_name and base_id were supplied — PBDB accepts only one clade selector. `incomplete_bbox`: Exactly one of lngmin/lngmax was supplied — a longitude box needs both edges. `inverted_ma_range`: min_ma was greater than or equal to max_ma — the age window is inverted or empty. Other values are possible when a failure originates below the handler.",
              "examples": [
                "missing_filter",
                "conflicting_taxon_filter",
                "incomplete_bbox",
                "inverted_ma_range"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "collections",
        "attribution"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Run a read-only SQL SELECT against occurrence result sets staged on a DataCanvas by paleobiology_search_occurrences. This is how you analyze a large fossil set without re-fetching it: count occurrences by early_interval, group by formation, country (cc), or accepted_name, or filter by a paleo/modern coordinate range. The classification column is JSON — roll up by rank with json_extract_string(classification, '$.family') (also $.phylum, $.class, $.order, $.genus). Staged rows are occurrences, so collection-only fields such as lithology are not present. Reference tables by the table_name that search_occurrences returned — call paleobiology_dataframe_describe first if you do not know the table or column names. SELECT only; writes and file-reading functions are rejected.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas id returned by paleobiology_search_occurrences when its result spilled."
    },
    "sql": {
      "type": "string",
      "description": "A read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / _describe returned."
    }
  },
  "required": [
    "canvas_id",
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Result rows (capped at the canvas row limit). Keys are the selected column names."
    },
    "row_count": {
      "type": "number",
      "description": "Number of rows in the full result before any row cap."
    },
    "truncated": {
      "description": "True when the result exceeded the canvas row cap and rows were trimmed.",
      "type": "boolean"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not enabled on this deployment (CANVAS_PROVIDER_TYPE is not duckdb). Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_disabled"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "rows",
        "row_count"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List the tables and their columns staged on a DataCanvas by paleobiology_search_occurrences. Call this before paleobiology_dataframe_query to discover the exact table_name and column names to reference in SQL.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas id returned by paleobiology_search_occurrences when its result spilled."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "tables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Table name — reference this in paleobiology_dataframe_query SQL."
          },
          "kind": {
            "type": "string",
            "description": "Object kind: \"table\" or \"view\"."
          },
          "row_count": {
            "type": "number",
            "description": "Number of rows in the table."
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name."
                },
                "type": {
                  "type": "string",
                  "description": "SQL column type, e.g. VARCHAR, DOUBLE, BIGINT."
                },
                "nullable": {
                  "description": "True when the column may contain nulls.",
                  "type": "boolean"
                }
              },
              "required": [
                "name",
                "type"
              ],
              "additionalProperties": false,
              "description": "A column in the staged table."
            },
            "description": "Columns in the table."
          }
        },
        "required": [
          "name",
          "kind",
          "row_count",
          "columns"
        ],
        "additionalProperties": false,
        "description": "A table staged on the canvas, with its columns."
      },
      "description": "Tables staged on the canvas."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not enabled on this deployment (CANVAS_PROVIDER_TYPE is not duckdb). Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_disabled"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "tables"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}