ICOS carbon and greenhouse-gas observations

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

With readOnly/idempotent annotations already covering safety, the description adds real semantics: server-side chunking and exact merge for selections over 500,000 rows, population std (ddof 0), and the crucial caveat that summing a rate or concentration yields no physical quantity. This is context an agent cannot get from annotations or schema.

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 capability and the 'instead of reading rows' guidance, followed by scale guarantees and statistical caveats. The rate-summation passage is long but each sentence carries non-obvious information; little waste.

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?

Output schema exists, so return values need not be explained, and the statistical semantics and exactness guarantees are covered. The remaining gap is the spatial and height filter parameters, which are neither described here nor in the schema.

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 only 54% across 13 parameters, so the description should compensate more. It echoes the grouping enum values (station, year, month, day) and implies the variable id, but says nothing about lat/lon, height, or cruise filters, which are undocumented in the schema as well.

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+resource: server-side statistics (count, mean, min, max, sum, std) over a whole selection of one variable, with grouping options named explicitly. It is clearly separable from siblings like get_data (row reading) and estimate.

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?

Explicitly instructs 'Use this for any average, total, range or trend instead of reading rows', naming the alternative behavior to avoid. It lacks a named sibling or an explicit when-not condition, but the steering is strong and includes the flux-total workaround.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety bar is low. The description goes further by disclosing the shape of the response and, importantly, the conditional behaviour for multi-dimensional zarr variables (axes/labels, prescribed slice, xarray expression for other slices) – useful context beyond the annotations.

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?

It is compact and front-loads the returned-fields summary, but the second sentence is telegraphic to the point of ambiguity – 'the slice /query serves (prescribed)' and 'an xarray line for any other slice' require guesswork about what 'access zarr' refers to.

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?

An output schema exists, so return values need not be re-explained, and annotations cover the safety profile. The description adds the conditional zarr branch, leaving only minor gaps such as behaviour on an unknown id and explicit routing from search_variables.

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?

There is a single required parameter and the schema already documents it at 100% coverage ('a variable id from search_variables'). The description adds no further constraint, format or example for the id, so the baseline 3 applies.

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 states a concrete verb+resource: it returns the full description of one variable, and enumerates what that description contains (names, unit, dataset, coverage, quality flag, licence, DOI). It is clearly the detail-fetch counterpart to search_variables, though it never names that sibling explicitly.

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?

Usage is only implied: the id parameter (documented in the schema, not the description) says 'a variable id from search_variables', which suggests the search-then-describe flow. The description itself gives no when-to-use guidance and does not distinguish this from get_data, list_datasets or aggregate.

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

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

Adds real context beyond the annotations: the call is a cheap pre-flight that does not transfer the data itself, and it reports rows, stations and time span. Annotations already cover read-only/idempotent/non-destructive, so the description's job is this cost/return framing, which it delivers. It doesn't mention latency or cost limits, keeping it from a 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?

Two short sentences, front-loaded with the outcome and trailing with the sequencing rule. Every word earns its place with no restatement of the name or schema.

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?

An output schema and full annotations reduce what the description must carry, and the purpose plus sequencing rule are sufficient to invoke it correctly. The gap is filter semantics for the geo/height/QC parameters, which an agent must infer from bare schema names.

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 only 50% — lat/lon bounds and height bounds carry no descriptions anywhere, and the description never mentions them or the semantics of cruise, apply_qc or start/end exclusivity. The phrase 'rows, stations, time span' hints at output dimensions rather than explaining any of the 12 parameters, so it does not compensate for the coverage gap.

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 the concrete outcome (size of a selection: rows, stations, time span) and the key property that it happens 'without fetching it'. It also names the sibling it precedes, so an agent can tell it apart from get_data 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.

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

Gives explicit workflow guidance: 'Call this before get_data,' which tells the agent when this tool belongs in a sequence. It does not state when to skip it or what the alternative is if an estimate is unnecessary, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the useful detail that proximity results are distance-sorted and that ids feed estimate/get_data. It says nothing about default limit (50), the 300 km default radius, or whether filters are ANDed, which are the remaining behavioral unknowns.

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?

Two dense sentences that front-load the resource and its fields before listing selection modes. No filler, though the em-dash clause packing four modes into one line is slightly harder to parse than a short list would be.

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?

An output schema exists, so return values need no explanation, and annotations cover safety. However, for an 11-parameter tool with 36% schema coverage, the description should address the limit/radius defaults and whether the filter families are mutually exclusive or combined, which it does not.

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 only 36%, so the description carries extra burden. It does map the search modes to the near_*/lat-lon/text/country parameter families, but leaves limit, radius_km defaults and filter-combination semantics unexplained, so it only partially compensates for the low coverage.

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 the resource concretely ('the stations that carry a variable') and enumerates the returned fields (id, name, position, sampling height, country, ecosystem), so an agent knows exactly what comes back. It also clarifies the downstream role of the returned ids. No sibling does the same thing, so differentiation is implicit rather than stated.

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?

Names the four selection modes (near a point sorted by distance, in a box, by name, by country) and explains that the returned ids are the `station=` input for estimate/get_data, which gives a clear workflow context. It stops short of stating when to prefer one mode over another or how modes combine.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the bar is lower; the description adds real content beyond them, namely that the response includes licence, DOI and the full list of source data objects. It omits any note on cost, rate limits, or what happens when the optional selection filters match nothing.

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?

Three short sentences, purpose front-loaded, zero filler. The final clause exists specifically to differentiate from data answers, so it earns its place.

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?

With an output schema present, the description needn't detail return values, and it still conveys the substantive return contract (citation, licence, DOI, full sources). What's missing is default behavior when no selection filters are supplied, which matters given 7 optional parameters.

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 only 50%, so the description must compensate, and it does: the phrase "for a selection (stations, a time window, a box)" maps the otherwise-undescribed lat/lon min-max parameters into a coherent bounding-box concept and ties start/end to a time window. It also implicitly frames the optional parameters as an all-or-nothing selection rather than independent filters.

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?

Opens with a specific framing verb+resource ("How to cite a variable's data") and enumerates exactly what is returned: citation text, licence, DOI, plus full provenance objects for a selection. It explicitly distinguishes itself from the data-returning siblings by contrasting "short citation and only the COUNT of their sources" with "this lists them."

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 contrast with "data answers" gives a clear condition for choosing this tool (you need the full citation/provenance rather than the data itself). It does not name the sibling tool (get_data) directly or state exclusions such as "do not use when you just need values," so it falls short of explicit routing.

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

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

Goes beyond the readOnly/idempotent annotations by disclosing truncation semantics (at most max_rows rows, full selection at the download URL), the total count, and the legal obligation to convey the citation. It does not mention rate limits or performance cost of large selections, but the important behavioral traits are covered.

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?

Three tight sentences, front-loaded with what the tool returns first and the citation obligation second. No filler, though the parenthetical filter list is a light restatement of the schema fields.

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?

Return values need not be explained because an output schema exists, and the description still covers the truncation/download contract and the citation mandate. The remaining gap is routing guidance among the many sibling tools and coordinate-bounds semantics for a 13-parameter 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 coverage is 54%, and the description does not add much: it names the filter groups (box, time, station, cruise, height, QC) but gives no semantics for the four coordinate bounds, which are undocumented in the schema, nor clarification of exclusivity/format. Baseline 3 given partial coverage and only a high-level restatement of the filters.

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+resource: observations for a single variable with named filter dimensions, plus the fact that it returns a truncated table, a total, and a download URL. It is clearly distinguishable from aggregate/estimate by returning raw observations, though it never says so explicitly.

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?

Usage is implied by the mention of max_rows/truncation and by the required id coming from search_variables (in schema), but the description never says when to choose this over aggregate (summaries), estimate (gridded products) or find_stations. No exclusions or prerequisites are stated.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, open-world operation. The description adds some behavioral context by saying the result is one record per data store and listing included metadata fields, but it does not discuss pagination, completeness, or other operational traits beyond the annotations.

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 a single front-loaded sentence that states the main action and then compactly lists the returned metadata. Every phrase adds useful information without repetition.

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 simple zero-parameter read tool with an output schema and rich annotations, the description gives enough context to call it correctly and understand the returned dataset metadata. It is slightly incomplete on how this catalog listing relates to sibling discovery tools.

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?

The tool takes zero parameters, so the baseline is 4. The description appropriately does not waste space explaining parameters that do not exist, though it also does not need to compensate for any schema gaps.

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 states a specific verb and resource ('List the ICOS datasets') and adds useful scope: one entry per data store with domain, coverage, licence and DOI. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as search_variables or get_data.

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 what the tool lists but gives no guidance on when to use it rather than alternatives like search_variables, find_stations, or get_data. There are no exclusions, prerequisites, or routing hints.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely non-obvious result-ordering behavior: primary measurements are returned ahead of their companions (standard deviation, value counts, flags), which affects how an agent should interpret the first hits. It does not mention empty-result behavior or that results may be truncated by limit.

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?

Three short sentences, front-loaded with the core action, then the downstream purpose, then the ordering caveat. No filler and nothing redundant with the schema.

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?

With an output schema present, return values need not be explained, and the ordering note plus the estimate/get_data linkage covers the main agent needs for a 4-parameter search. Minor gap: no guidance on narrowing a too-broad query or on what an empty result implies.

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 75%, and the schema already documents the free-text query, store filter and domain values, so baseline is 3. The description restates the searchable axes (name, quantity, unit) but adds nothing about limit semantics or how store/domain constrain ranking – no compensation beyond 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 ('Find variable ids in the ICOS catalogue') plus the three search axes (name, quantity, unit). It further distinguishes itself from siblings by naming the consumers of its output ('The ids are what estimate and get_data take'), so an agent knows this is the discovery step, not a data-fetch step.

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 mention that ids are consumed by estimate and get_data clearly implies this is a prerequisite/discovery call before those tools. However, it never explicitly says when not to use it, e.g. that describe_variable should be used to inspect metadata for an id already known, or that list_datasets is better for browsing stores.

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