Skip to main content
Glama

paleobiology-mcp-server: query staged occurrences with SQL

paleobiology_dataframe_query
Read-onlyIdempotent

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 paleobiology_search_occurrences returned — call paleobiology_dataframe_describe first if you do not know the table or column names. Every row supplied by the canvas is returned; choose smaller pages with SQL LIMIT/OFFSET. Results exceeding the canvas row cap include a notice naming the stable ORDER BY … LIMIT/OFFSET continuation. SELECT only; writes and file-reading functions are rejected.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "canvas_id": "<canvas_id>",
      "sql": "<sql>"
    },
    "name": "paleobiology_dataframe_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqlYesA read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / paleobiology_dataframe_describe returned.
canvas_idYesCanvas id returned by paleobiology_search_occurrences when its result spilled.

Output Schema

NameRequiredDescriptionDefault
rowsNoEvery result row supplied by the canvas, in query order. Keys are the selected column names. Use SQL LIMIT/OFFSET to choose smaller pages.
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance when row_count stopped at the canvas row cap, including SQL LIMIT/OFFSET continuation.
row_countNoRows the query produced, counted up to the canvas row cap — exact unless truncated is true, when it equals the cap and the result is larger.
truncatedNoTrue when the query produced more rows than the canvas row cap, so row_count stopped counting at the cap.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the result was cut to fit the inline response size (rows shown, the LIMIT/OFFSET that continues, and when to stop), when a single row was too large to show, or when row_count stopped at the canvas row cap."New value: +"Guidance when row_count stopped at the canvas row cap, including SQL LIMIT/OFFSET continuation."
    • changedOutput schema / properties / rows / description
      Previous value: -"Result rows in query order, ending at a whole row where more would exceed the inline response size. Keys are the selected column names. When rows were left out, the notice says how many are shown and the LIMIT/OFFSET that reads the rest."New value: +"Every result row supplied by the canvas, in query order. Keys are the selected column names. Use SQL LIMIT/OFFSET to choose smaller pages."
  2. Changed5 schema fields changed
    • changedInput schema / properties / sql / description
      Previous value: -"A read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / _describe returned."New value: +"A read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / paleobiology_dataframe_describe returned."
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Guidance when the result was cut to fit the inline response size (rows shown, the LIMIT/OFFSET that continues, and when to stop), when a single row was too large to show, or when row_count stopped at the canvas row cap.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / row_count / description
      Previous value: -"Number of rows in the full result before any row cap."New value: +"Rows the query produced, counted up to the canvas row cap — exact unless truncated is true, when it equals the cap and the result is larger."
    • changedOutput schema / properties / rows / description
      Previous value: -"Result rows (capped at the canvas row limit). Keys are the selected column names."New value: +"Result rows in query order, ending at a whole row where more would exceed the inline response size. Keys are the selected column names. When rows were left out, the notice says how many are shown and the LIMIT/OFFSET that reads the rest."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the result exceeded the canvas row cap and rows were trimmed."New value: +"True when the query produced more rows than the canvas row cap, so row_count stopped counting at the cap."
  3. Changed1 schema field changed
    • addedInput schema / properties / canvas_id / pattern
      Added value: +"^[A-Za-z0-9_-]{10}$"
  4. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Goes far beyond the readOnlyHint annotation by detailing operational constraints: explicitly rejecting writes and file-reading functions, and describing the notification mechanism for results exceeding the canvas row cap.

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?

While slightly lengthy, the description is highly efficient; every sentence serves a distinct informational or structural purpose, providing maximum value without unnecessary filler.

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?

The definition is exceptionally complete, covering the workflow prerequisite, syntax hints (JSON), constraints (no writes), and output management (pagination notices) for this complex query tool.

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

Parameters5/5

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

Offers crucial semantic information on the input parameters, specifically explaining the format of the `classification` column and providing syntax for extraction using `json_extract_string`, which is not defined in the schema.

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?

Clearly identifies the tool as running a read-only SQL SELECT, the specific resource (occurrence result sets staged on a DataCanvas), and its function in the workflow (analyzing large fossil sets).

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

Usage Guidelines5/5

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

Provides explicit usage guidance by stating when this tool is used (without re-fetching data) and which sibling tool to call first (paleobiology_dataframe_describe) when table or column names are unknown.

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.