us-drought-monitor-mcp-server

Query staged drought data

drought_dataframe_query

Read-only

Run one DuckDB read expression against staged drought tables, optionally ending with one semicolon. Get canvas_id from drought_get_timeseries or drought_compare_areas and inspect columns with drought_dataframe_describe. For every original row, SELECT * FROM the table ORDER BY row_id and follow next_offset until null. Arbitrary SQL pagination requires your own stable ORDER BY. Exact totals require SELECT COUNT(*).

Input Schema

Name	Required	Description
`sql`	Yes	One DuckDB read expression with an optional terminal semicolon; staged tables only.
`limit`	No	Default 25 rows per page; values above 500 are clamped with disclosure.
`offset`	No	Rows to skip in the stable ordered query.
`canvas_id`	Yes	Token returned by a drought producer.

Output Schema

Name	Required	Description
`cap`	No	Requested maximum page rows.
`rows`	No	Complete projected values on this page.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Complete rows shown on the truncated page.
`notice`	No	Empty-result or continuation guidance.
`offset`	No	Rows skipped by this query.
`columns`	No	Projected column names in order.
`has_more`	No	Whether another page remains.
`canvas_id`	No	Supplied canvas token.
`truncated`	No	More query rows remain beyond this page.
`limitNotice`	No	Disclosure when the requested limit was clamped.
`next_offset`	No	Continue with this offset and identical SQL, or null.
`countIsExact`	No	True only when the page exhausts the query at offset zero.
`returnedCount`	No	Number of rows returned.
`tableMetadata`	No	Bounded table identity and source provenance.
`effectiveLimit`	No	Effective page ceiling after clamping to 500.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 26, 2026

changedInput schema / properties / limit / default
```
Previous value: -100New value: +25
```

changedInput schema / properties / limit / description

Previous value: -"Maximum returned rows, clamped to 500 with disclosure and further bounded by complete response size."New value: +"Default 25 rows per page; values above 500 are clamped with disclosure."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: Analytical provider is disabled or unavailable. `canvas_not_found`: Token is absent, expired or belongs to another tenant. `missing_table`: A named staged table is absent. `invalid_sql`: SQL cannot parse or bind. `sql_execution_error`: A data conversion or range expression fails. `sql_read_only`: SQL gate rejects a write, external read or system catalog. `dataset_too_large`: Combined source metadata exceeds the query response budget. `query_row_too_large`: One projected row cannot fit a complete response. `staging_busy`: Two queries are already active in this process. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: Analytical provider is disabled or unavailable. `canvas_not_found`: Token is absent, expired or belongs to another tenant. `missing_table`: A named staged table is absent. `invalid_sql`: SQL cannot parse or bind. `sql_execution_error`: A data conversion or range expression fails. `sql_read_only`: SQL gate rejects a write, external read or system catalog. `staging_busy`: Two queries are already active in this process. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "canvas_unavailable",
-  "canvas_not_found",
-  "missing_table",
-  "invalid_sql",
-  "sql_execution_error",
-  "sql_read_only",
-  "dataset_too_large",
-  "query_row_too_large",
-  "staging_busy"
-]New value: +[
+  "canvas_unavailable",
+  "canvas_not_found",
+  "missing_table",
+  "invalid_sql",
+  "sql_execution_error",
+  "sql_read_only",
+  "staging_busy"
+]

First observedOct 24, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well past the readOnlyHint/openWorldHint annotations: it discloses the single-statement constraint with one optional semicolon, the staged-tables-only restriction, the limit clamping above 500 with disclosure, the next_offset-until-null pagination contract, and the requirement for a caller-supplied stable ORDER BY when paginating arbitrary SQL. These are exactly the behaviors that cause silent wrong results if unknown.

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-loaded with the core action, then workflow routing, then pagination rules; every sentence carries operational content. The telegraphic phrasing and the semicolon detail (already in the sql schema description) are minor redundancy, not waste.

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

Completeness4/5

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

An output schema exists, so return shape needn't be described, and the description covers the query contract, pagination, and row-count caveats well. The remaining gap is the canvas_id lifecycle — nothing says whether a staged canvas expires or how long it stays queryable, which matters for a staged-data 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%, so the schema already documents limit, offset, canvas_id, and sql. The description still adds meaning beyond it by defining what the schema's vague 'stable ordered query' means (ORDER BY row_id) and by explaining how offset/limit interact with the next_offset chain.

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 and resource: run one DuckDB read expression against staged drought tables. It also distinguishes itself from siblings by naming drought_get_timeseries and drought_compare_areas as the canvas_id producers and drought_dataframe_describe as the column inspector, so the agent can place it in the workflow without inspecting schemas.

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?

Gives explicit prerequisites (canvas_id from a drought producer, columns via drought_dataframe_describe) and prescribes distinct query patterns for distinct goals: SELECT * ... ORDER BY row_id with next_offset for full row enumeration, versus SELECT COUNT(*) for exact totals. It lacks an explicit 'do not use this when...' exclusion, which keeps it below 5.

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

All us-drought-monitor-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.