Oceanum MCP

Official

by oceanum-io

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Datamesh Stage Query

datamesh_stage_query

Read-only

Dry-run a Datamesh query to report result size without downloading data, so you can check if it fits inline retrieval.

Instructions

Dry-run a query: report the result size WITHOUT downloading any data.

Always stage before retrieving data you have not sized. The response says whether the result is small enough for query_data to return inline, and echoes the canonical query. With limit plus time_resolution or aggregate_operations the reported size is that of the unlimited result (limit is applied after resampling), so it is an upper bound.

A variable given as the exact CF standard_name of exactly one of the datasource's variables (e.g. "sea_surface_wave_significant_height" for "hs") is resolved to that variable; the response then includes resolved_variables ({requested: used}) and echoes the resolved names.

Input Schema

Name	Required	Description
`crs`	No	CRS for filter coordinates and returned data (EPSG code or CRS string).
`bbox`	No	Bounding box [xmin, ymin, xmax, ymax] in WGS84 (or crs units if crs is set).
`limit`	No	Keep only the last N records (Datamesh semantics: the last N steps along time/ensemble). Combined with time_resolution or aggregate_operations it is applied AFTER resampling/aggregation (by this server, not sent to Datamesh), so stage_query sizes the unlimited result as an upper bound; hosted export_query refuses that combination.
`times`	No	Discrete times to select (series selection). Mutually exclusive with time_start/time_end.
`levels`	No	Discrete vertical levels to select (series selection). Mutually exclusive with level_min/level_max.
`time_end`	No	ISO 8601 end of a time range. Open-ended if omitted.
`level_max`	No	Maximum vertical level of a range.
`level_min`	No	Minimum vertical level of a range.
`variables`	No	List of variable names to select (e.g. ["temperature", "salinity"]).
`time_start`	No	ISO 8601 start of a time range (e.g. "2023-01-01T00:00:00Z"). Open-ended if omitted.
`level_interp`	No	Interpolation for level series selection: nearest or linear.
`coord_filters`	No	Additional coordinate selections, e.g. [{"coord": "station", "values": ["A1", "B2"]}].
`datasource_id`	Yes	The datasource to query.
`time_resample`	No	Resampling method when time_resolution is set: mean, nearest, or linear.
`time_resolution`	No	Downsample a time range server-side to this resolution (pandas frequency string, e.g. "1h", "6h", "1D", "7D", or "30D" for roughly monthly). Drastically shrinks long time series. Monthly/quarterly/yearly calendar aliases (MS, ME, QS, YS) are not supported until a Datamesh engine fix ships: use "30D", "90D" or "365D". Finer than 1 minute is refused.
`geofilter_interp`	No	Interpolation for feature selection: nearest or linear (default linear).
`aggregate_spatial`	No	Aggregate over spatial dimensions (default true).
`geofilter_feature`	No	GeoJSON Feature object (Point, MultiPoint, or Polygon geometry) for spatial selection/interpolation. Mutually exclusive with bbox.
`aggregate_temporal`	No	Aggregate over the temporal dimension (default true).
`aggregate_operations`	No	Aggregations to apply after filtering: mean, min, max, std, sum.
`geofilter_resolution`	No	Maximum spatial resolution for downsampling, in CRS units.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.5.2Oct 16, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations declare readOnlyHint/openWorldHint, so the safety bar is already met; the description still earns credit by disclosing non-obvious behavior: no data is downloaded, limit+resampling makes the size an upper bound, and CF standard_name variables get resolved with resolved_variables echoed back. It omits cost/latency or rate-limit context for what is effectively a repeated exploratory call.

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 dry-run semantics, then caveats in descending priority; every sentence carries information. It is a bit long and partially restates the limit/time_resolution interaction already present in the limit parameter description, which is mild redundancy.

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?

Given 21 parameters, an output schema, and annotations, the description covers what structured fields cannot: that nothing is downloaded, how the size verdict relates to query_data, and the upper-bound caveat. Nothing essential for correct invocation is missing, though staging cost and whether the echoed canonical query is reusable could be stated.

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 baseline is 3 and the schema already documents all 21 parameters. The description adds genuine meaning beyond it by specifying the CF standard_name resolution rule for variables and how the response echoes resolved names, a behavior not stated in the variables schema field.

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?

The description opens with a specific verb+resource pairing ("Dry-run a query: report the result size WITHOUT downloading any data") that immediately distinguishes it from siblings like datamesh_query_data and datamesh_export_query. An agent can tell exactly what this tool does without opening any 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?

It gives an explicit usage rule ("Always stage before retrieving data you have not sized") and routes the agent by naming query_data as the consumer of the size verdict. It does not explicitly cover the export path or state the inverse exclusion ("do not use this to fetch data"), so routing is clear but not exhaustive.

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

Deploy Server