paleobiology-mcp-server: search fossil occurrences
paleobiology_search_occurrencesSearch 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 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. | |
| latmax | No | Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane. | |
| latmin | No | Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane. | |
| lngmax | No | Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither. | |
| lngmin | No | Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither. | |
| max_ma | No | 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. | |
| min_ma | No | 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. | |
| offset | No | 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. | |
| base_id | No | 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. | |
| interval | No | Named geologic interval bounding the age, e.g. "Cretaceous" or "Maastrichtian". Alternative to max_ma/min_ma. | |
| base_name | No | Clade-inclusive taxon filter — this taxon and all descendants, e.g. "Dinosauria". The usual choice. Supply this or base_id, never both. | |
| canvas_id | No | 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. | |
| taxon_name | No | Exact taxon filter — only this taxon, not descendants. Use instead of base_name when you want a single taxon. | |
| environment | No | Depositional environment: "marine", "terrestrial", or "freshwater" (lacustrine + fluvial). Omit for all. | |
| collection_no | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | 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. | |
| spilled | No | True when the result exceeded the inline preview and the staged occurrence set was written to the canvas. | |
| canvas_id | No | 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. | |
| row_count | No | 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. | |
| table_name | No | Canvas table holding the staged occurrence set. Present only when spilled is true. | |
| totalCount | No | Total occurrences matching the filters upstream — the number this call was drawn from, which may exceed the staged set. | |
| attribution | No | CC-BY data attribution for the Paleobiology Database. | |
| occurrences | No | 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). |