Skip to main content
Glama

paleobiology-mcp-server: search fossil occurrences

paleobiology_search_occurrences
Read-onlyIdempotent

Search fossil occurrences by clade-inclusive base_name or base_id, exact taxon_name, interval or max_ma/min_ma, modern geographic bounds, country, formation, environment, or collection_no. At least one filter is required. Formation matches PBDB stored names and preserves list/wildcard syntax; suffixes are not removed. Resolve uncertain taxon names with paleobiology_get_taxon. Rows carry modern lng/lat, reconstructed paleolng/paleolat, age, strata, classification, and source reference_no; keep the coordinate systems distinct. Every served page row is returned, with total matches and the offset that continues the page. When this deployment has DataCanvas enabled, a first page with additional matches stages up to 50,000 occurrences on a canvas: use paleobiology_dataframe_describe for columns, then paleobiology_dataframe_query for SQL over the staged set; the notice distinguishes complete from partial coverage. Later offsets and complete pages stage nothing and leave any supplied canvas untouched.

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_search_occurrences"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum occurrences to return per page, up to 10000, subject to PBDB_MAX_OCCURRENCES. Every fetched page row is returned; the notice discloses a lower configured cap. Pair with offset to walk the match set.
latmaxNoNorthern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.
latminNoSouthern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.
lngmaxNoEastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither.
lngminNoWestern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither.
max_maNoOlder 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_maNoYounger 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.
offsetNoNumber 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_idNoClade-inclusive taxon filter by PBDB taxon id — the accepted_no from paleobiology_get_taxon or 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.
countryNoPBDB country/continent codes, comma-separated; ! excludes a list and ^ subtracts a code, e.g. NOA,^US.
intervalNoNamed geologic interval bounding the age, e.g. "Cretaceous" or "Maastrichtian". Alternative to max_ma/min_ma.
base_nameNoClade-inclusive taxon filter — this taxon and all descendants, e.g. "Dinosauria". The usual choice. Supply this or base_id, never both.
canvas_idNoCanvas id from a prior call to restage onto the same workspace. Used only on a first page with matches beyond that page: replaces the prior occurrence table atomically with a bounded matching set, without appending. Later offsets and complete pages leave it untouched. Omit to start fresh.
formationNoStored formation name or PBDB list/wildcard expression, passed unchanged; suffixes such as Formation are not removed.
taxon_nameNoExact taxon filter — only this taxon, not descendants. Use instead of base_name when you want a single taxon.
environmentNoDepositional environment: "marine", "terrestrial", or "freshwater" (lacustrine + fluvial). Omit for all.
collection_noNoRestrict 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

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
noticeNoApplied filters and empty/past-end guidance, page continuation, ignored upstream filters, staged-set coverage, or optional staging unavailability.
spilledNoTrue when the first page had additional matches and the bounded matching set was written to the canvas.
canvas_idNoCanvas id holding the staged occurrence set — pass it to paleobiology_dataframe_describe for columns, then paleobiology_dataframe_query for SQL. Present only when spilled is true; complete pages and later offsets stage nothing.
row_countNoRows staged on the canvas when spilled (at most 50,000); otherwise occurrences returned inline. Compare against totalCount for full-match coverage.
table_nameNoCanvas table holding the staged occurrence set — the FROM target in paleobiology_dataframe_query SQL, and the table paleobiology_dataframe_describe reports columns for. Present only when spilled is true.
totalCountNoTotal occurrences matching the filters upstream — the number this call was drawn from, which may exceed the staged set.
attributionNoCC-BY data attribution for the Paleobiology Database.
occurrencesNoEvery occurrence in the requested page, subject to the configured page cap. When spilled is true, the canvas holds the bounded matching set independently of this page; the notice states whether staging covers every match.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changed
    • changedInput schema / properties / base_id / description
      Previous value: -"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."New value: +"Clade-inclusive taxon filter by PBDB taxon id — the accepted_no from paleobiology_get_taxon or 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."
    • changedInput schema / properties / canvas_id / description
      Previous value: -"Canvas id from a prior call to re-stage onto the same workspace. Used only when this page spills: reusing it REPLACES (overwrites) the prior occurrence table — each search restages the full result, it does not append to or accumulate across earlier ones — while a page that fits inline leaves that canvas untouched. Omit to start fresh; a spilled response returns a new id."New value: +"Canvas id from a prior call to restage onto the same workspace. Used only on a first page with matches beyond that page: replaces the prior occurrence table atomically with a bounded matching set, without appending. Later offsets and complete pages leave it untouched. Omit to start fresh."
    • addedInput schema / properties / country
      Added value: +{
      +  "description": "PBDB country/continent codes, comma-separated; ! excludes a list and ^ subtracts a code, e.g. NOA,^US.",
      +  "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 / formation
      Added value: +{
      +  "description": "Stored formation name or PBDB list/wildcard expression, passed unchanged; suffixes such as Formation are not removed.",
      +  "type": "string"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum occurrences to pull per page. Up to 500 are pulled per call; a larger value is served at 500, and the paging notice names that cap when more matches remain. A page can show fewer rows than it pulled when more would exceed the inline response size — the notice then names the offset that continues. Pair with offset to walk the whole match set."New value: +"Maximum occurrences to return per page, up to 10000, subject to PBDB_MAX_OCCURRENCES. Every fetched page row is returned; the notice discloses a lower configured cap. Pair with offset to walk the match set."
    • changedOutput schema / properties / canvas_id / description
      Previous value: -"Canvas id holding the staged occurrence set — pass it to paleobiology_dataframe_describe for the table and column names, then to paleobiology_dataframe_query to run SQL against them. Present only when spilled is true; a result that fit inline stages nothing, so there is no table to query."New value: +"Canvas id holding the staged occurrence set — pass it to paleobiology_dataframe_describe for columns, then paleobiology_dataframe_query for SQL. Present only when spilled is true; complete pages and later offsets stage nothing."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"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. `pbdb_invalid_parameter`: PBDB refused a filter value it could not use, such as an unknown interval name — the message quotes its reason. `canvas_capacity_exhausted`: The page outgrew the inline response size and no canvas_id was passed, but every canvas slot open to this caller is already taken. Other values are possible when a failure originates below the handler."New value: +"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. `pbdb_invalid_parameter`: PBDB refused a filter value it could not use, such as an unknown interval name — the message quotes its reason. `canvas_capacity_exhausted`: The first page has additional matches to stage and no canvas_id was passed, but every canvas slot open to this caller is already taken. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / notice / description
      Previous value: -"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 a page cut to the inline response size could not be staged because this deployment has no DataCanvas."New value: +"Applied filters and empty/past-end guidance, page continuation, ignored upstream filters, staged-set coverage, or optional staging unavailability."
    • changedOutput schema / properties / occurrences / description
      Previous value: -"Inline preview of matching occurrences for the requested page, ending at a whole row where more would exceed the inline response size. 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)."New value: +"Every occurrence in the requested page, subject to the configured page cap. When spilled is true, the canvas holds the bounded matching set independently of this page; the notice states whether staging covers every match."
    • changedOutput schema / properties / occurrences / items / properties / classification / properties / order / description
      Previous value: -"Order, when classified (PBDB sentinel orders are omitted)."New value: +"Order, when classified."
    • changedOutput schema / properties / row_count / description
      Previous value: -"Rows staged on the canvas when spilled; otherwise the number of occurrences shown inline. At most 500 per call — compare against the totalCount enrichment for how many matched upstream."New value: +"Rows staged on the canvas when spilled (at most 50,000); otherwise occurrences returned inline. Compare against totalCount for full-match coverage."
    • changedOutput schema / properties / spilled / description
      Previous value: -"True when the result exceeded the inline preview and the staged occurrence set was written to the canvas."New value: +"True when the first page had additional matches and the bounded matching set was written to the canvas."
  2. Changed11 schema fields changed
    • changedInput schema / properties / canvas_id / description
      Previous value: -"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."New value: +"Canvas id from a prior call to re-stage onto the same workspace. Used only when this page spills: reusing it REPLACES (overwrites) the prior occurrence table — each search restages the full result, it does not append to or accumulate across earlier ones — while a page that fits inline leaves that canvas untouched. Omit to start fresh; a spilled response returns a new id."
    • changedInput schema / properties / limit / description
      Previous value: -"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."New value: +"Maximum occurrences to pull per page. Up to 500 are pulled per call; a larger value is served at 500, and the paging notice names that cap when more matches remain. A page can show fewer rows than it pulled when more would exceed the inline response size — the notice then names the offset that continues. Pair with offset to walk the whole match set."
    • changedInput schema / properties / limit / maximum
      Previous value: -500New value: +10000
    • changedOutput schema / properties / canvas_id / description
      Previous value: -"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."New value: +"Canvas id holding the staged occurrence set — pass it to paleobiology_dataframe_describe for the table and column names, then to paleobiology_dataframe_query to run SQL against them. Present only when spilled is true; a result that fit inline stages nothing, so there is no table to query."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"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."New value: +"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. `pbdb_invalid_parameter`: PBDB refused a filter value it could not use, such as an unknown interval name — the message quotes its reason. `canvas_capacity_exhausted`: The page outgrew the inline response size and no canvas_id was passed, but every canvas slot open to this caller is already taken. 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",
      -  "incomplete_bbox",
      -  "inverted_ma_range"
      -]New value: +[
      +  "missing_filter",
      +  "conflicting_taxon_filter",
      +  "incomplete_bbox",
      +  "inverted_ma_range",
      +  "pbdb_invalid_parameter",
      +  "canvas_capacity_exhausted"
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"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."New value: +"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 a page cut to the inline response size could not be staged because this deployment has no DataCanvas."
    • changedOutput schema / properties / occurrences / description
      Previous value: -"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)."New value: +"Inline preview of matching occurrences for the requested page, ending at a whole row where more would exceed the inline response size. 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)."
    • changedOutput schema / properties / occurrences / items / properties / reference_no / description
      Previous value: -"PBDB bibliographic reference id for provenance."New value: +"PBDB bibliographic reference id — the publication this occurrence was entered from. Resolve it to a full citation with paleobiology_get_references."
    • changedOutput schema / properties / row_count / description
      Previous value: -"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."New value: +"Rows staged on the canvas when spilled; otherwise the number of occurrences shown inline. At most 500 per call — compare against the totalCount enrichment for how many matched upstream."
    • changedOutput schema / properties / table_name / description
      Previous value: -"Canvas table holding the staged occurrence set. Present only when spilled is true."New value: +"Canvas table holding the staged occurrence set — the FROM target in paleobiology_dataframe_query SQL, and the table paleobiology_dataframe_describe reports columns for. Present only when spilled is true."
  3. Changed1 schema field changed
    • addedInput schema / properties / canvas_id / pattern
      Added value: +"^[A-Za-z0-9_-]{10}$"
  4. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent and open-world, so the bar is lower, and the description clears it comfortably. It discloses non-obvious behavior that no structured field carries: the required-filter rule, the ~50,000-row canvas staging side effect with atomic replace, the distinction between complete and partial coverage in the notice, and that later offsets and complete pages stage nothing and leave a supplied canvas untouched.

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?

Purpose and the required-filter rule are front-loaded, and every sentence concerns correct invocation. It is dense but long, and a few clauses duplicate schema text verbatim (formation suffix behavior, offset paging semantics), which costs some efficiency.

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

Completeness5/5

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

With 17 optional parameters, a full output schema, and annotations covering safety, this description supplies the remaining pieces an agent needs: how filters interact, what the returned row carries, how paging continues, and how the DataCanvas side effect behaves. Nothing material for a correct call is missing.

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 description coverage is 100%, so the baseline is 3. The description restates the key parameter distinctions (clade-inclusive base_name/base_id vs exact taxon_name, formation suffix/wildcard handling, offset paging) but adds little that the schema does not already say; its one novel parameter-adjacent point is the warning to keep modern lng/lat and reconstructed paleolng/paleolat distinct, which concerns the returned rows.

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

Purpose5/5

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

Opening sentence names a specific verb (search) and resource (fossil occurrences) and enumerates the exact filter axes the tool accepts: clade-inclusive base_name/base_id, exact taxon_name, interval or max_ma/min_ma, geographic bounds, country, formation, environment, collection_no. It also distinguishes itself from siblings by name (paleobiology_get_taxon for resolution, dataframe_describe/query for staged sets), so an agent can separate it from search_collections and its other siblings without opening a schema.

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

Usage Guidelines4/5

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

Explicit constraints are given: at least one filter is required, uncertain names should be resolved with paleobiology_get_taxon first, and the DataCanvas path names the follow-up tools to use. The description also makes clear that staging only happens on a first page with additional matches. It stops short of stating when not to use this tool (e.g., use search_collections to find a locality first), so it is clear context plus alternatives rather than full when/when-not routing.

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.