Oceanum MCP

Official

by oceanum-io

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Datamesh Export Query

datamesh_export_query

Idempotent

Export the FULL result of a query — the data never enters the conversation.

Instructions

Export the FULL result of a query — the data never enters the conversation.

Behavior depends on how the server is running:

Hosted (http/sse): returns a time-limited, self-authenticating gateway download_url (choose format via format); path is ignored. Fetch the URL out-of-band — it needs no credential, so treat it as a secret. When the response includes expires_at or max_uses, fetch it before expires_at and at most max_uses times. Refused above the hosted export cap, and for limit combined with time_resolution/aggregate_operations.
Local (stdio): writes the result to the local file path (required) and returns that path. Gridded datasets stream to NetCDF; tabular results write Parquet or CSV, as do datasets small enough to flatten into a table (e.g. point time series). Refused up front if the result exceeds the local export cap or the destination's free disk space. With limit plus time_resolution/aggregate_operations, the last N resampled steps are written.

The size is checked before anything is exported, whether or not stage_query was called. An export writing more than 1 GB in the chosen format (CSV text is about 3x; locally, a dataset written as CSV/Parquet is sized as the flattened table, and a limited one on its limited slice) is refused unless confirm_size_bytes equals that size (on hosted, within 5%, since the download stage is sized separately): ask the user first. The refusal states the exact value. The server cannot see whether the user was asked, so this is advisory: it forces an explicit, size-aware step. The export caps limit the transfer, not the size of each file: never split a refused request into parts to get under them.

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).
`path`	No	Local (stdio) destination file path (required on stdio; parent directories are created; confined to OCEANUM_MCP_EXPORT_DIR when set). Ignored on hosted servers, which return a download URL.
`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.
`format`	No	Output format: netcdf (datasets), parquet or csv (tabular, or datasets small enough to flatten into a table such as point time series). Defaults by container: dataset -> netcdf, tabular -> parquet.
`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.
`overwrite`	No	Overwrite an existing local file (default false). Local export only.
`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).
`confirm_size_bytes`	No	Required for results above 1 GB: the size in bytes, in the chosen format, the user has agreed to export (stage_query's size_bytes for the default format, or export_size_bytes from a refusal). Must match exactly (within 5% on hosted servers). Ignored for exports of 1 GB or less.
`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.

Changed1 schema field changedv0.6.0Oct 22, 2026

addedInput schema / properties / confirm_size_bytes

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Required for results above 1 GB: the size in bytes, in the chosen format, the user has agreed to export (stage_query's size_bytes for the default format, or export_size_bytes from a refusal). Must match exactly (within 5% on hosted servers). Ignored for exports of 1 GB or less."
+}

First observedv0.5.2Oct 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Given annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: hosted download URL secrecy, expiry/max_uses semantics, local file writing with overwrite behavior, size-check-before-export, and the advisory nature of confirm_size_bytes. It also warns against splitting refused requests. No contradiction with annotations.

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?

The description is front-loaded with the core purpose and mode-dependent behavior, and every paragraph carries operational weight (size caps, secret handling, refusal conditions). It is however quite long and dense for a tool description; a bullet or table structure for hosted vs local differences could improve scanability without losing content.

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?

Given 25 parameters, an output schema (so return values need not be described), and the complexity of dual hosted/local behavior, the description covers all critical decision points: environment-dependent behavior, size confirmation, variable resolution, and refusal conditions. Nothing an agent needs in order to call it correctly or handle its response appears missing.

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?

With schema description coverage at 100%, the baseline would be 3, but the description adds cross-parameter semantics not captured per-parameter in the schema: hosted vs local effects on `path` and `format`, the interaction of `limit` with `time_resolution`/`aggregate_operations`, and CF standard_name resolution for `variables`. These are meaningful additions beyond the schema, though many individual parameters (bbox, times, levels) are still only explained 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?

The description opens with a specific verb+resource: 'Export the FULL result of a query' and immediately differentiates itself by stating 'the data never enters the conversation'. This clearly distinguishes it from sibling tools like datamesh_query_data that presumably return data in-conversation. An agent can tell what this tool does without opening the 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?

The description gives rich context on when behavior changes (hosted vs local), when `path` is required or ignored, and when `confirm_size_bytes` is needed, including 'ask the user first'. It provides explicit refusal conditions (hosted cap, limit combined with resampling) but does not explicitly name an alternative sibling (e.g., datamesh_query_data or stage_query) for routine retrieval, leaving the when-to-use-this-vs-that inference to the reader.

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

Deploy Server