icos-mcp

Official

Overview Schema Source Related Servers Discussions Admin

aggregate

Read-onlyIdempotent

Compute count, mean, min, max, sum, and population standard deviation for a variable over any selection, overall or grouped by station, year, month, or day, without reading rows.

Instructions

Statistics over a WHOLE selection, computed on the server: count, mean, min, max, sum and standard deviation of one variable, overall or per station, year, month or day. Use this for any average, total, range or trend instead of reading rows. Any size: a selection over 500,000 rows is split by time on the server and merged exactly. std is the POPULATION standard deviation (ddof 0). sum adds the values as stored, which is a total only for values that are themselves totals per row: summing a RATE (umol m-2 s-1 per half-hour, gC m-2 d-1 per day) or a concentration gives no physical quantity -- for a flux total multiply the mean by the period.

Input Schema

Name	Required	Description	Default
`by`	No	the groups: none (one result), station, a period, or both	none
`id`	Yes	a variable id from search_variables
`end`	No	ISO date or datetime, EXCLUSIVE
`start`	No	ISO date or datetime, inclusive (2025-01-01)
`cruise`	No	cruise expocodes, a list or a string; ocean observation tables only
`lat_max`	No	northern edge of a bounding box, degrees north
`lat_min`	No	southern edge of a bounding box, degrees north
`lon_max`	No	eastern edge of a bounding box, degrees east
`lon_min`	No	western edge of a bounding box, degrees east
`station`	No	station ids -- a list, or one id (or several, comma-separated) as a string; CASE-SENSITIVE: HTM150 (trigram + sampling height) for atmosphere, SE-Htm for FLUXNET sites
`apply_qc`	No	DEFAULT TRUE: drop the observations the store's recommended quality control rejects; false keeps every observation, flagged ones included
`question`	No	the user's request as they wrote it; kept only if the user agreed in the licence form to share their questions anonymously, otherwise dropped
`height_max`	No	highest sampling height above ground, metres (station series)
`height_min`	No	lowest sampling height above ground, metres (station series)

Output Schema

Name	Required	Description
`by`	Yes
`id`	Yes
`note`	No
`unit`	No
`groups`	Yes	one entry per group: its keys (station, period), n (finite values), and mean, min, max, sum, std over them (null when n is 0)
`citation`	Yes
`n_groups`	Yes
`variable`	Yes
`rows_used`	Yes
`download_url`	Yes
`download_urls`	No
`download_complete`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.0Nov 7, 2026

TDQS

A4.1/5.0

Behavior3/5

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

Adds real behavior beyond the read-only/idempotent annotations: exact server-side splitting and merging for selections over 500,000 rows, and that `std` is population (ddof 0). It adds little else the agent needs in order to call it safely; it extends useful behavioral detail but stops short of discussing failures or empty results.

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 what is computed and the routing advice, then adds two justified caveats about `std` and `sum` (the caveat saves the agent from producing physical nonsense). The `sum` caveat runs long with its parenthetical unit examples but each sentence earns its place.

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?

Output schema exists, so return values need no explanation, and the description covers the aggregation semantics and large-selection behavior for a 14-parameter tool. It is slightly incomplete for parameters in the schema (apply_qc default true, station/height filters) that materially change what gets aggregated and are documented only in the schema.

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

Parameters3/5

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

Schema coverage is 100%, so every parameter already carries its own description and the baseline applies. The description adds only the notion of a single variable and the grouping axis ('overall or per station, year, month or day'), which largely restates the `by` enum, and says nothing about the spatial/temporal/QC filters.

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 concrete verb and resource: server-computed statistics (count, mean, min, max, sum, std) over a whole selection of one variable, grouped by station/period. It explicitly distinguishes itself from row-fetching siblings with 'instead of reading rows', so an agent can route correctly 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance ('Use this for any average, total, range or trend instead of reading rows') that names the alternative behavior (reading rows via get_data). It also warns when not to trust `sum` (rates/concentrations) and tells the agent what to do instead (multiply the mean by the period).

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

Deploy Server