paleobiology-mcp-server

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. A result too large to return inline comes back as its first rows, with a notice naming the ORDER BY … LIMIT/OFFSET that reads the rest. SELECT only; writes and file-reading functions are rejected.

Input Schema

Name	Required	Description	Default
`sql`	Yes	A read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / paleobiology_dataframe_describe returned.
`canvas_id`	Yes	Canvas id returned by paleobiology_search_occurrences when its result spilled.

Output Schema

Name	Required	Description
`rows`	No	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.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	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.
`row_count`	No	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.
`truncated`	No	True 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.

Changed5 schema fields changedOct 15, 2026

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."

Changed1 schema field changedSep 19, 2026
- addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```
First observedSep 1, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations cover readOnly/idempotent, and the description adds substantial extra behavior: SELECT-only enforcement (writes and file-reading functions rejected), JSON classification column handling with json_extract_string, absence of collection-only fields like lithology, and the oversized-result truncation behavior with an ORDER BY … LIMIT/OFFSET notice. This is rich, non-redundant behavioral disclosure.

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?

Front-loads the core action and use case, then unpacks column conventions and safety constraints. Dense but every sentence carries information; slightly longer than minimal but justified by the complexity of SQL-over-JSON behavior.

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 an output schema present, the description needn't explain returns; it instead covers the tricky parts an agent must know — table naming, JSON column extraction, missing fields, result truncation, and write rejection. Complete for a 2-param SQL tool.

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

Parameters4/5

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

Schema coverage is 100% and the schema documents both params, so baseline is 3. The description adds meaning beyond the schema by explaining what the canvas_id represents (staged result from a spill) and giving concrete SQL patterns/columns. Good added value.

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?

States a specific verb (run SELECT) against a specific resource (occurrence result sets staged on a DataCanvas), and names the producing sibling tool paleobiology_search_occurrences. Clearly distinguishable from siblings like dataframe_describe or get_diversity.

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?

Explicitly directs the agent to call paleobiology_dataframe_describe first if unknown table/column names, and explains the analysis-without-refetch use case. Full when-to-use guidance with sibling routing.

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

All paleobiology-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.