AQUAVIEW MCP is a hosted Model Context Protocol server that gives any LLM agent direct access to 700,000+ oceanographic, atmospheric, and marine datasets from 68 authoritative sources — NOAA, IOOS, World Ocean Database, Argo, GOES-R, NEXRAD, ESA Sentinel, and more. Ask in plain English; the server returns structured results with direct download links for NetCDF, GRIB2, GeoTIFF, and CSV files.
Scored across 6 tools
The tools are largely distinct: get_data (observation rows) vs get_item (catalog metadata item) is clearly separated, and search_datasets vs aggregate are differentiated by metadata vs summary queries. However, list_collections and list_data_sources both present lists of 'sources/collections' and could be confused, and search_datasets vs aggregate overlap in catalog-querying purpose, though descriptions do help.
Most tools follow a clear verb_noun pattern (get_data, get_item, list_collections, list_data_sources, search_datasets). The lone 'aggregate' is a bare verb with no noun object, a minor deviation from the otherwise consistent scheme.
Six tools is well-scoped for a read-only catalog and data-retrieval server. Each tool earns its place: catalog listing/search/aggregation plus item fetch and observation pull, with no redundancy.
The surface covers catalog discovery (list_collections, search_datasets, aggregate), item detail (get_item), and raw data retrieval (list_data_sources, get_data), with pagination and download handled inline. Minor gap: no dedicated download/staging tool and no cross-source comparison, but core read workflows are covered.
Run aggregation queries on the AQUAVIEW catalog — get counts, spatial distributions, temporal distributions, and per-collection breakdowns without fetching individual items.
Args:
aggregations: Comma-separated aggregation types (required). Valid types: total_count, datetime_max, datetime_min, datetime_frequency, collection_frequency, geometry_geohash_grid_frequency, geometry_geotile_grid_frequency.
collections: Comma-separated collection IDs to scope the aggregation (e.g., "NOAA,NDBC").
exclude_collections: Comma-separated collection IDs to omit from the aggregation (e.g., "INCIDENT_NEWS"). Applied as a CQL2 NOT filter, so it composes with filter.
bbox: Bounding box as "west,south,east,north".
datetime: Temporal filter (same format as search_datasets).
q: Free-text search to scope the aggregation. Multi-word queries are tokenised on whitespace and OR-combined to mirror search_datasets semantics (aggregate compiles q to CQL2 LIKE clauses on title/description; a raw %multi word% substring match would return 0 for most queries).
filter: CQL2-JSON filter as an object or JSON-encoded string. Flat example: {"op": "=", "args": [{"property": "aquaview:institution"}, "NOAA"]}. Nested example: {"op": "<=", "args": [{"property": "aquaview:column_stats_summary.variables.Pressure.min"}, 10]}.
license: Comma-separated SPDX license id(s) to scope the aggregation (e.g., "CC-BY-4.0,CC0-1.0"), or one of "public-domain", "proprietary", "various", "unknown". Matched against aquaview:license.
precision: Grid precision for geo aggregations (1-12, higher = finer grid). Applied to whichever geo aggregation type is requested.
datetime_frequency_interval: Interval for datetime_frequency (e.g., "month", "year", "day").
output_format: "csv" (default, sectioned CSV — ~50% fewer tokens than TOON for bucket responses), "json" (structured STAC API response), or "toon". Use "json" for deterministic/structured consumers.
Returns:
Aggregation results. In CSV mode: one ## <name> section per aggregation;
scalars render on a single line; bucket aggregations render as CSV with a
# rows: N header, a # key=value line for columns that are constant
across all rows, and a conventional CSV table of the varying columns.
In JSON/TOON mode: the raw SFEOS response with name, data_type, and
value/buckets for each requested aggregation.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| bbox | No | ||
| filter | No | ||
| license | No | ||
| datetime | No | ||
| precision | No | ||
| collections | No | ||
| aggregations | Yes | ||
| output_format | No | csv | |
| exclude_collections | No | ||
| datetime_frequency_interval | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the tool's behavior: it runs aggregations, composes q as CQL2 LIKE clauses, and returns various output formats. No destructive behavior is implied, so transparency is good but could mention read-only nature explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, parameter list, and return format explanation. It is front-loaded with purpose. However, it is somewhat lengthy due to detailed parameter explanations; could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, multiple aggregation types, output formats), the description covers all necessary aspects: what each parameter does, valid values, return format details, and behavioral notes. It is complete for an aggregation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates thoroughly by explaining all 11 parameters with valid values, examples, and behavioral notes (e.g., q tokenization, output_format default). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs aggregation queries on the AQUAVIEW catalog, providing counts, spatial/temporal distributions, and per-collection breakdowns without fetching individual items. This distinguishes it from siblings like search_datasets (item retrieval) and list_collections (collection listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool for aggregations instead of fetching items. It provides parameter details and notes on composition with filters. However, it does not explicitly state when not to use it or directly compare with siblings for exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull actual observation rows from an AQUAVIEW data source — not catalog metadata.
Use this whenever the question needs the measurements themselves (temperature
profiles, float positions, buoy readings), rather than which datasets exist.
Call list_data_sources first for a source's canonical variable names, its
qc_modes, and its engine (gridded "xarray" sources have no rows to pull).
READ 'returned' FIRST. It is one of three values:
'complete': 'rows' holds EVERY matching row (or your whole 'limit'). Safe to compute anything from.
'head': 'rows' holds the FIRST rows in the source's natural order (see 'head.order'), out of 'head.of' total. These are not a random sample — later rows differ systematically — so never average or take a maximum from them. To get more, set 'limit' up to 'head.max_inline'; beyond that, narrow the request or fetch 'download_url'.
'none': no rows. 'refusal.reason' says why. 'unscoped_query' means add a bbox/datetime/depth/filter. 'no_natural_order' means the source has no column to order a partial read by, so no partial set can be given honestly — narrow until it fits, or use 'stats'. The rest are transient; retry.
OTHER FIELDS:
'stats': exact minimum, maximum, mean and spread computed over EVERY matching row. Use these for any numeric claim — exact at any data size.
'stats_basis': what shaped those numbers. If 'qc' is null the values are UNSCREENED and may include implausible outliers from bad sensor readings; say so, or re-run with a quality filter. When a mode was applied, 'qc_screened' lists the variables it actually checked — a variable not in it was NOT flag-checked, and an empty list means nothing was screened despite 'qc' naming a mode. 'qc_note', when present, explains that the screen drops whole rows, so it shapes every variable's figures.
'structure': how many distinct floats/stations/profiles matched — often the real answer ("16 profiles from 5 floats"), which no row count gives.
'sample': a genuinely random sample, included only when rows were withheld. For seeing what the data looks like — do NOT compute from it.
'download_url': the full result as a file, in 'download_format'. Fetch it if you can run code; otherwise give it to the user. Absent for restricted sources and for matches too large to stage synchronously.
'schema': each column's real type. Needed when reading the CSV download, which stores no types — without it a reader infers them and can get them wrong (an id column read as a number loses leading zeros).
'omitted': names any part that could not be computed. An absent field is unknown, NOT zero.
Args:
source: Source id from list_data_sources (e.g. "gadr", "wod", "ndbc").
variables: Comma-separated canonical variable names (e.g. "temperature,salinity,depth").
bbox: Bounding box "west,south,east,north" (e.g. "-161,18,-154,23").
datetime: ISO-8601 instant or range ("2022-06-01/2022-06-30"; ".." for an open end).
depth: Depth range in metres below surface, "min,max" (e.g. "0,200").
filters: JSON object of extra column filters on ordinary columns, e.g.
{"data_mode": "D"}. For QUALITY screening prefer qc below — a source
that defines modes applies them to each measurement correctly, where
filtering a raw flag column yourself is easy to get wrong.
qc: Named quality mode, and the right way to screen. Unfiltered ocean data
contains sentinel values that make maxima and means physically
implausible, so screen before any scientific claim. list_data_sources
reports each source's qc_modes; pass one of those here. Passing a mode
to a source with none is an error. A source with no modes may still
expose per-measurement quality columns you can filter directly via
filters — list_data_sources shows its variables.
limit: Maximum rows to return, honored up to what fits inline. Omit for a
default-sized head. When a response comes back as a head, head.max_inline
tells you the largest limit worth asking for on that request.
format: Encoding of download_url. Default "parquet" — it keeps every column's
type, is ~5x smaller and ~2x faster, and pd.read_parquet(url) reads it.
Choose "csv" when the link is going to a person who will open it by hand
rather than into code, or when you can fetch a URL but cannot run code;
then use schema to set the column types yourself.
include_sample: Set False to skip the random sample and return slightly faster.
output_format: 'csv' (compact, default), 'json', or 'toon'.
| Name | Required | Description | Default |
|---|---|---|---|
| qc | No | ||
| bbox | No | ||
| depth | No | ||
| limit | No | ||
| format | No | parquet | |
| source | Yes | ||
| filters | No | ||
| datetime | No | ||
| variables | Yes | ||
| output_format | No | csv | |
| include_sample | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it explains the three-valued 'returned' contract, warns that 'head' rows are order-biased and must never be averaged or maximized, lists refusal reasons with remedies, and flags that unscreened qc values may be implausible and that absent fields mean unknown rather than zero. This is exactly the behavioral context a caller needs before trusting results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Heavily front-loaded with 'READ 'returned' FIRST' and organized under labeled sections, so it scans well. It is nonetheless long, and the 'OTHER FIELDS' block re-describes return fields that an output schema already covers, which is more verbosity than strictly required.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, no-annotation tool with a rich result contract, the description covers invocation, filtering, screening, truncation behavior, and download paths. Nothing an agent needs to call it correctly or interpret the response appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 11 parameters, so the description must compensate and it does for every arg: formats for bbox, datetime (including '..' open ends), depth, filters JSON, and the qc/limit/format semantics. It adds meaning beyond the schema's bare types, e.g. why to prefer 'qc' over filtering a raw flag column, and when to pick csv vs parquet.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line states a specific verb+resource ('Pull actual observation rows from an AQUAVIEW data source') and explicitly negates the sibling category ('not catalog metadata'), which cleanly separates it from list_data_sources/search_datasets. An agent can route to it 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('whenever the question needs the measurements themselves'), a prerequisite ('Call list_data_sources first for canonical variable names, qc_modes, engine'), and routes the agent away from unusable sources ('gridded "xarray" sources have no rows to pull'). Alternatives are named for edge cases ('narrow until it fits, or use stats').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single AQUAVIEW dataset item with full details, properties, and download links (assets).
STAC items embed assets inline — each asset includes an href (download URL) and media type, so there is no need for a separate "files" call.
Args: collection: The collection ID the item belongs to (e.g., "NOAA", "NDBC", "WOD"). Available from search results or list_collections. item_id: The unique item identifier (e.g., "wod_xbt_ZZ144579"). Available from search results. output_format: "toon" (default) or "json".
Returns: Full STAC item with geometry, properties (title, description, datetime, institution, variables, per-variable descriptions under aquaview:variable_descriptions when available, etc.), and assets (download links with media types).
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | ||
| collection | Yes | ||
| output_format | No | toon |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose a genuinely useful behavioral trait: STAC assets are embedded inline with href and media type, so no follow-up 'files' call is needed. It omits auth/permission requirements, rate limits, and any error behavior for a bad collection/item_id, keeping it out of the top band.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then cleanly sectioned into Args and Returns. Every sentence is functional, though the Returns block partially restates what the output schema already carries, which trims a point off maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter read tool with an output schema, the description supplies everything an agent needs: purpose, argument sources, format options, and the inline-assets behavior. Since a machine-readable output schema exists, the return-value detail is bonus rather than a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and it does: every one of the three parameters is explained with a concrete example value ('NOAA', 'wod_xbt_ZZ144579') and a source for the value. It also flags output_format's default and its two allowed values, matching the enum in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Fetch a single AQUAVIEW dataset item') and scopes the payload ('full details, properties, and download links (assets)'). It contrasts with a hypothetical 'files' call, but never differentiates itself from the actual siblings (search_datasets, list_collections, aggregate), so it lands at clear-but-no-sibling-differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states where the required arguments come from ('Available from search results or list_collections'), which implies this is a fetch-after-search tool, and warns that a separate assets/files lookup is unnecessary. It gives no explicit when-not-to-use or preferred-alternative condition, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available AQUAVIEW data collections (sources).
Returns a summary of each collection with ID, title, description, spatial/temporal extent, and keywords. Use collection IDs to filter searches.
These are CATALOG collections. Several are also queryable row by row — see list_data_sources for the sources get_data can pull observations from.
A collection's bbox and temporal range are OUTER BOUNDS, not a promise of coverage. They are the envelope around everything in the collection, so most of the box usually holds no data at all — an Argo collection spans the global ocean, a partner collection with one point either side of the date line spans the whole planet. An empty result for a point or window inside the extent is the normal answer, not a failure: report "no data there", not "the query did not work", and do not widen a search on the strength of a bbox alone.
Args:
tag: Only collections with this tag, e.g. "uxs" for uncrewed systems. Pass the returned IDs as collections to search_datasets to search only those.
output_format: "csv" (default, sectioned CSV — ~20% fewer tokens than TOON for this tabular response), "json", or "toon". Use "json" for deterministic/structured consumers.
Returns:
List of collections with count. CSV mode emits a single ## collections
section with columns id,title,bbox,temporal,keywords,description;
bbox is rendered as "west,south,east,north"; temporal as "min|max";
keywords ";"-joined.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| output_format | No | csv |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so with non-obvious, high-value detail: bbox/temporal are OUTER BOUNDS, not coverage promises, and an empty result inside the extent is the normal answer rather than a failure. It also warns not to widen a search on bbox alone, which directly prevents a common agent error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and scope, and every section earns its place. There is mild redundancy between the summary sentence listing fields (ID, title, description, extent, keywords) and the Returns section repeating the CSV column list, which slightly inflates length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the detailed Returns block partially duplicates structured data, but the description still covers everything an agent needs: purpose, sibling routing, parameter semantics, and the critical extent-is-envelope behavior. Only minor gaps remain (no pagination or auth notes, though neither appears relevant here).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: `tag` is documented with an example ('uxs') and its downstream use as `collections` in search_datasets, and `output_format` explains the csv default, token tradeoff, and when to choose json. Both parameters gain meaning beyond the bare enum/string schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List all available AQUAVIEW data collections') and explicitly distinguishes the resource from siblings by noting these are CATALOG collections and pointing to list_data_sources for queryable sources. An agent can tell it apart from search_datasets, get_data, and list_data_sources 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear routing: pass returned IDs as `collections` to search_datasets to filter, and see list_data_sources for sources get_data can pull from. It explains the downstream use well but states no explicit exclusions or when-not-to-use conditions beyond the sibling pointer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the AQUAVIEW data sources you can pull actual rows from, or describe one in detail.
Call this BEFORE get_data on a source you have not used. Variable names are canonical per source and cannot be guessed — this is where they come from.
With an API key, sources your account is entitled to appear here too.
Args: source_id: Omit to list every visible source. Give one (e.g. "gadr") to get its full detail: canonical variable names, units, row limits, and filterable columns. output_format: 'csv' (compact, default), 'json', or 'toon'.
| Name | Required | Description | Default |
|---|---|---|---|
| source_id | No | ||
| output_format | No | csv |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the burden, and it does disclose meaningful behavior: entitlement-gated visibility when an API key is present, the fact that canonical variable names originate here, and the list-vs-detail mode switch. It stops short of describing pagination, response size, or rate limits, but the presence of an output schema covers the return-shape gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and the ordering rule before the Args block, and every sentence adds information. Slightly long for a two-parameter tool, but the extra lines on canonical names and entitlement gating are load-bearing rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with an output schema already defining the return shape, the description covers everything needed to invoke correctly: the ordering constraint relative to get_data, entitlement behavior, and both parameter modes. Nothing an agent must know before calling is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: source_id is explained in both modes ('omit to list every visible source', 'give one e.g. "gadr"') along with what detail is returned (canonical variable names, units, row limits, filterable columns). output_format is given defaults and relative sizing ('csv', compact, default) beyond the raw enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the AQUAVIEW data sources') plus the dual mode (list vs. describe one in detail). It also implicitly separates itself from get_data and search_datasets by scoping to 'sources you can pull actual rows from' and positioning itself as the source of canonical variable names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit sequencing rule: 'Call this BEFORE get_data on a source you have not used,' which names the alternative tool and the exact condition that selects this one. It further justifies the call by noting variable names are canonical and cannot be guessed, so the agent knows why the prerequisite exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the AQUAVIEW catalog — a comprehensive collection of 268K+ global oceanographic, atmospheric, and marine datasets from 15 sources (NOAA, NDBC, IOOS, WOD, CoastWatch, etc.), intended for scientific research, data analysis, and environmental monitoring.
This searches METADATA — which datasets exist. To pull the actual observations (temperature profiles, buoy readings, float positions), use get_data instead; list_data_sources shows which sources support it.
You must provide at least one of: q, bbox, datetime, collections, filter, or token. Hint: When the user asks for a region, prefer the 'bbox' parameter over including region name in 'q'. Use the geo_hints resource for common bounding boxes.
Args:
q: Free-text search across title, description, and keywords (e.g., "sea surface temperature"). Case-insensitive, OR logic across terms.
bbox: Bounding box as "west,south,east,north" (e.g., "-98,24,-80,31" for Gulf of Mexico).
datetime: Temporal filter. Single datetime, range ("2020-01-01T00:00:00Z/2024-12-31T23:59:59Z"), or open-ended ("../2024-01-01T00:00:00Z" or "2020-01-01T00:00:00Z/..").
collections: Comma-separated collection IDs to search within (e.g., "NOAA,NDBC,WOD"). Use list_collections to see available IDs.
exclude_collections: Comma-separated collection IDs to omit from results (e.g., "INCIDENT_NEWS" to drop oil-spill reports from free-text searches). Applied as a CQL2 NOT filter, so it composes with filter.
filter: CQL2-JSON filter as an object or JSON-encoded string. Supports flat and nested property paths. Flat example: {"op": "=", "args": [{"property": "aquaview:institution"}, "NOAA/NCEI"]}. Nested example (filter by per-variable stats summary): {"op": "<=", "args": [{"property": "aquaview:column_stats_summary.variables.Pressure.min"}, 10]}. Supported operators: =, <>, <, >, <=, >=, like, between, in, and, or, not.
license: Comma-separated SPDX license id(s) to match exactly (e.g., "CC-BY-4.0,CC0-1.0"). Also accepts the controlled extra values "public-domain", "proprietary", "various", "unknown". Matched against aquaview:license, which is normalized on every item regardless of source.
sortby: Sort specification as "+field,-field" (e.g., "+properties.datetime,-id"). + = ascending, - = descending.
limit: Number of results to return, 1-100. Defaults to 10.
token: Pagination token from a previous response's 'next_token' field. Pass this to get the next page of results.
fields: Comma-separated list of fields to include in results (e.g., "id,geometry,properties.title"). Reduces response size. When set in CSV mode, emits projected columns (no canonical columns, no asset_keys, no ## assets section).
include_assets: If False (default), asset download records are omitted to save ~60-70% of response tokens; CSV mode still emits a capped asset_keys hint column (e.g. column_stats;overview;gdac_prof;+[N]) so an agent can see what kinds of assets exist. To get full URLs, call get_item(collection, item_id) for the specific id. If True, assets are included inline (full dict for JSON/TOON; ## assets section with item_id,key,href,type,title rows for CSV).
output_format: "csv" (default, sectioned CSV — canonical columns including asset_keys hint), "json", or "toon".
Returns:
Search results with metadata (total matched, returned, next_token) and items.
CSV mode emits ## metadata + ## items sections and a ## assets section
when include_assets=True; columns are id,collection,bbox,datetime,title,institution,
platform_type,cdm_data_type,variables,keywords,source_url,description,
column_stats_summary,geometry,asset_keys. JSON/TOON return the STAC feature shape,
with the assets dict present only when include_assets=True.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| bbox | No | ||
| limit | No | ||
| token | No | ||
| fields | No | ||
| filter | No | ||
| sortby | No | ||
| license | No | ||
| datetime | No | ||
| collections | No | ||
| output_format | No | csv | |
| include_assets | No | ||
| exclude_collections | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and largely meets it: it discloses the metadata-only scope, the required-parameter constraint, pagination via next_token, and concrete cost/token behavior (include_assets False omits assets to save ~60-70% of response tokens; fields reduces response size). It stops short of stating read-only/permission semantics or rate limits, so a 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Long, but the length is justified by 13 undocumented parameters and is well-structured with Args and Returns sections. The purpose and the get_data disambiguation are front-loaded. A few parenthetical asides (e.g. the CQL2 NOT explanation for exclude_collections) add detail that could be trimmed, but nothing is egregiously wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter metadata search, the description covers scope, required inputs, every parameter, pagination, output formats, and even a Returns section despite an output schema being present. An agent has everything needed to invoke it correctly, including the sibling routing to get the actual data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does: every one of the 13 parameters is documented with meaning, format, defaults, and worked examples (bbox as 'west,south,east,north', datetime range syntax, CQL2 filter with flat and nested examples and the operator list, license controlled values, sortby +/- convention, limit 1-100). This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) and resource (the AQUAVIEW catalog of metadata), and explicitly distinguishes the scope: 'This searches METADATA — which datasets exist.' It names the sibling it is not (get_data pulls actual observations) and the sibling that helps (list_data_sources), so an agent can differentiate without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use vs alternatives ('to pull the actual observations... use get_data instead'), a constraint ('must provide at least one of: q, bbox, datetime, collections, filter, or token'), and a routing hint ('prefer bbox over region name in q'; use geo_hints for bounding boxes). This is about as prescriptive as usage guidance gets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_datalist_collections1 field changedInput schema / properties / tagAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}list_data_sourcesaggregate12 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / aggregations / descriptionRemoved value: -"Comma-separated aggregation types (required). Valid types: total_count, datetime_max, datetime_min, datetime_frequency, collection_frequency, geometry_geohash_grid_frequency, geometry_geotile_grid_frequency."Input schema / properties / bbox / descriptionRemoved value: -"Bounding box as \"west,south,east,north\"."Input schema / properties / collections / descriptionRemoved value: -"Comma-separated collection IDs to scope the aggregation (e.g., \"NOAA,NDBC\")."Input schema / properties / datetime / descriptionRemoved value: -"Temporal filter (same format as search_datasets)."Input schema / properties / datetime_frequency_interval / descriptionRemoved value: -"Interval for datetime_frequency (e.g., \"month\", \"year\", \"day\")."Input schema / properties / exclude_collections / descriptionRemoved value: -"Comma-separated collection IDs to omit from the aggregation (e.g., \"INCIDENT_NEWS\"). Applied as a CQL2 NOT filter, so it composes with `filter`."Input schema / properties / filter / descriptionRemoved value: -"CQL2-JSON filter as an object or JSON-encoded string. Flat example: {\"op\": \"=\", \"args\": [{\"property\": \"aquaview:institution\"}, \"NOAA\"]}. Nested example: {\"op\": \"<=\", \"args\": [{\"property\": \"aquaview:column_stats_summary.variables.Pressure.min\"}, 10]}."Input schema / properties / license / descriptionRemoved value: -"Comma-separated SPDX license id(s) to scope the aggregation (e.g., \"CC-BY-4.0,CC0-1.0\"), or one of \"public-domain\", \"proprietary\", \"various\", \"unknown\". Matched against `aquaview:license`."Input schema / properties / output_format / descriptionRemoved value: -"\"csv\" (default, sectioned CSV — ~50% fewer tokens than TOON for bucket responses), \"json\" (structured STAC API response), or \"toon\". Use \"json\" for deterministic/structured consumers."Input schema / properties / precision / descriptionRemoved value: -"Grid precision for geo aggregations (1-12, higher = finer grid). Applied to whichever geo aggregation type is requested."Input schema / properties / q / descriptionRemoved value: -"Free-text search to scope the aggregation. Multi-word queries are tokenised on whitespace and OR-combined to mirror search_datasets semantics (aggregate compiles q to CQL2 LIKE clauses on title/description; a raw %multi word% substring match would return 0 for most queries)."get_item4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / collection / descriptionRemoved value: -"The collection ID the item belongs to (e.g., \"NOAA\", \"NDBC\", \"WOD\"). Available from search results or list_collections."Input schema / properties / item_id / descriptionRemoved value: -"The unique item identifier (e.g., \"wod_xbt_ZZ144579\"). Available from search results."Input schema / properties / output_format / descriptionRemoved value: -"\"toon\" (default) or \"json\"."list_collections2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / output_format / descriptionRemoved value: -"\"csv\" (default, sectioned CSV — ~20% fewer tokens than TOON for this tabular response), \"json\", or \"toon\". Use \"json\" for deterministic/structured consumers."search_datasets14 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / bbox / descriptionRemoved value: -"Bounding box as \"west,south,east,north\" (e.g., \"-98,24,-80,31\" for Gulf of Mexico)."Input schema / properties / collections / descriptionRemoved value: -"Comma-separated collection IDs to search within (e.g., \"NOAA,NDBC,WOD\"). Use list_collections to see available IDs."Input schema / properties / datetime / descriptionRemoved value: -"Temporal filter. Single datetime, range (\"2020-01-01T00:00:00Z/2024-12-31T23:59:59Z\"), or open-ended (\"../2024-01-01T00:00:00Z\" or \"2020-01-01T00:00:00Z/..\")."Input schema / properties / exclude_collections / descriptionRemoved value: -"Comma-separated collection IDs to omit from results (e.g., \"INCIDENT_NEWS\" to drop oil-spill reports from free-text searches). Applied as a CQL2 NOT filter, so it composes with `filter`."Input schema / properties / fields / descriptionRemoved value: -"Comma-separated list of fields to include in results (e.g., \"id,geometry,properties.title\"). Reduces response size. When set in CSV mode, emits projected columns (no canonical columns, no asset_keys, no `## assets` section)."Input schema / properties / filter / descriptionRemoved value: -"CQL2-JSON filter as an object or JSON-encoded string. Supports flat and nested property paths. Flat example: {\"op\": \"=\", \"args\": [{\"property\": \"aquaview:institution\"}, \"NOAA/NCEI\"]}. Nested example (filter by per-variable stats summary): {\"op\": \"<=\", \"args\": [{\"property\": \"aquaview:column_stats_summary.variables.Pressure.min\"}, 10]}. Supported operators: =, <>, <, >, <=, >=, like, between, in, and, or, not."Input schema / properties / include_assets / descriptionRemoved value: -"If False (default), asset download records are omitted to save ~60-70% of response tokens; CSV mode still emits a capped `asset_keys` hint column (e.g. `column_stats;overview;gdac_prof;+[N]`) so an agent can see what kinds of assets exist. To get full URLs, call `get_item(collection, item_id)` for the specific id. If True, assets are included inline (full dict for JSON/TOON; `## assets` section with item_id,key,href,type,title rows for CSV)."Input schema / properties / license / descriptionRemoved value: -"Comma-separated SPDX license id(s) to match exactly (e.g., \"CC-BY-4.0,CC0-1.0\"). Also accepts the controlled extra values \"public-domain\", \"proprietary\", \"various\", \"unknown\". Matched against `aquaview:license`, which is normalized on every item regardless of source."Input schema / properties / limit / descriptionRemoved value: -"Number of results to return, 1-100. Defaults to 10."Input schema / properties / output_format / descriptionRemoved value: -"\"csv\" (default, sectioned CSV — canonical columns including asset_keys hint), \"json\", or \"toon\"."Input schema / properties / q / descriptionRemoved value: -"Free-text search across title, description, and keywords (e.g., \"sea surface temperature\"). Case-insensitive, OR logic across terms."Input schema / properties / sortby / descriptionRemoved value: -"Sort specification as \"+field,-field\" (e.g., \"+properties.datetime,-id\"). + = ascending, - = descending."Input schema / properties / token / descriptionRemoved value: -"Pagination token from a previous response's 'next_token' field. Pass this to get the next page of results."aggregate1 field changedInput schema / properties / licenseAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Comma-separated SPDX license id(s) to scope the aggregation (e.g., \"CC-BY-4.0,CC0-1.0\"), or one of \"public-domain\", \"proprietary\", \"various\", \"unknown\". Matched against `aquaview:license`."
+}search_datasets1 field changedInput schema / properties / licenseAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Comma-separated SPDX license id(s) to match exactly (e.g., \"CC-BY-4.0,CC0-1.0\"). Also accepts the controlled extra values \"public-domain\", \"proprietary\", \"various\", \"unknown\". Matched against `aquaview:license`, which is normalized on every item regardless of source."
+}aggregateget_itemlist_collectionssearch_datasets
Add one secure layer between your agents and this server.