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.

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.

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.

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.

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.

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.

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's additional content is almost entirely about what data comes back, which overlaps with the existing output schema. It adds no operational context such as cost, size limits, or failure modes for unknown ids.

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 return contract, which is good. However, the second sentence is dense and partly opaque ('the slice /query serves (prescribed)', 'an xarray line for any other slice') and spends its weight on zarr-specific return mechanics rather than on how to call the tool.

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 one-parameter read tool with full schema coverage, an output schema and complete annotations, most required information already exists in structured fields. The description nonetheless leans on return-value detail that the output schema already supplies, while leaving agent-facing decisions such as when to prefer get_data unaddressed.

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 100% and the single parameter is documented in the schema as 'a variable id from search_variables'. The description adds no format or validity detail beyond that. Baseline 3 applies when the schema carries the parameter semantics.

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 opens with a clear scoping statement ('One variable in full') and enumerates what is resolved: names, unit, dataset, coverage, quality flag, licence, DOI. That is a specific verb-plus-resource picture an agent can match against search_variables (which only finds ids). It never names a sibling explicitly, so differentiation is inferred 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?

Usage context is implied only: the schema says the id comes from search_variables, and the second sentence hints this tool is the follow-up for zarr-backed multi-dimensional variables. There is no explicit when-to-use versus get_data or aggregate, and no statement of when this tool is unnecessary.

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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral fact -- the call does not fetch the data, so it is a cheap pre-flight check. It says nothing about cost, latency, or how the estimate is computed/sampled, which would matter for a planning tool.

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, zero filler, with the substantive explanation front-loaded and the usage directive second. Nothing could be removed without losing information.

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 and 100% parameter coverage, the description needn't explain return values or arguments, and it correctly focuses on purpose plus sequencing. For a 12-parameter tool the description is thin on how the estimate interacts with the filters, but the structured fields carry that load.

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 100%, so all 12 parameters are documented in the schema itself and the baseline is 3. The description's mention of "rows, stations, time span" loosely maps to the row/station/time filtering dimensions, but it adds no syntax, defaults, or interaction detail beyond what the schema already provides.

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?

"How big a selection is -- rows, stations, time span -- without fetching it" states the specific operation (size estimation) and enumerates what is measured, which is far more informative than the bare name "estimate." It is clearly distinguishable from get_data, though it doesn't name the other sizing-adjacent siblings (aggregate, find_stations) that an agent might confuse it with.

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?

"Call this before get_data" gives an explicit ordering rule that routes the agent correctly between the two tools. There is no explicit when-not guidance (e.g., when skipping the estimate is fine, or how it relates to aggregate/find_stations), so it stops short of full alternative 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 safety is covered; the description still adds real value by disclosing the sort order for proximity search (by distance) and the identity of the returned fields. It stops short of behavioral edge cases such as what happens with zero matches, how conflicting filters interact, or how the default limit truncates 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?

Two dense sentences with no filler, and the most actionable fact (ids feed estimate and get_data) is placed last but is short enough to read. Minor ambiguity: the field list reads like return values while 'a variable' is an input id, which takes a moment to disentangle.

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 search tool with a full output schema and rich annotations, the description covers the essentials: what is searched, the mode options, sort order, and the id handoff. The remaining gap is filter-combination semantics, which matters given four mutually overlapping selection mechanisms but is not addressed anywhere.

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 100% and all 11 parameters are individually documented (id source, text matching examples, two-letter country, bounding-box edges, near_lat/near_lon/radius_km trio, limit bounds), so the schema does the heavy lifting. The description adds only the conceptual grouping of those parameters into four search modes plus the reminder that the resulting ids are the station= input for other tools; 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?

Names the resource (stations carrying a given variable), enumerates the metadata returned (id, name, position, sampling height, country, ecosystem), lists the four selection modes (near a point, in a box, by name, by country), and closes with the downstream contract that the ids are what estimate and get_data accept as station=. An agent can tell exactly what this yields and how to chain it, which no sibling does.

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 four filter modes imply when each is appropriate (proximity vs bounding box vs text vs country), and pointing at estimate/get_data establishes the follow-on step, so usage is inferable. But there is no explicit routing guidance against search_variables, describe_variable, or list_datasets, and no statement about whether the modes can be combined or which wins when several are supplied.

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 read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds that the source list is returned 'in full' while other tools return only a count, which is useful context, but it says nothing about what happens when a selection matches no sources or a variable lacks a passport entry.

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 return content, then a clarifying contrast in the second sentence. The em-dash parenthetical is a bit convoluted but every clause carries meaning and there is no 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?

With an output schema present, the description does not need to explain return values, and it correctly focuses on scope and the distinction from count-only sources. For an 8-parameter, read-only lookup this is close to complete, with only edge-case behavior left unstated.

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 100%, so the baseline would be 3; the description goes slightly beyond by framing the optional parameters as a 'selection (stations, a time window, a box)' and explaining that they determine which data objects are listed in full. That gives semantic intent to the optional filters rather than just restating field types.

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 concretely what the tool returns: citation text, licence and DOI from a variable's data passport, plus the full list of underlying data objects. It implicitly distinguishes itself from data-answer tools that carry only a short citation and a source count, giving an agent a clear sense of the resource 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?

Usage is implied by the contrast 'Data answers carry a short citation and only the COUNT of their sources; this lists them', which suggests calling this when full provenance is needed. However, no sibling tool is named (e.g. get_data, describe_variable) and there is no explicit when-to-use/when-not-to-use statement.

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 new behavior: results are capped at max_rows rows as a table, the response also carries the total count and a download URL covering the whole selection, and the returned citation must be surfaced to the user with any use of the data — a licensing obligation not present in any structured field. That is meaningful context beyond the annotations, though it does not discuss truncation semantics or rate limits.

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 compact sentences with the filter scope front-loaded, followed by the return contract and the citation requirement. No filler, no restatement of the tool name, and each sentence carries distinct information.

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 14-parameter query tool with full schema coverage and an output schema, the description covers scope, the row-cap-plus-download-URL pattern that resolves the truncation concern, and the citation duty. What is missing is minor: it does not note that certain filters (e.g. cruise, height) apply only to particular dataset types, though the schema covers this per-parameter.

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 100%, so every one of the 14 parameters is already documented, including exclusive end dates, case-sensitive station ids, and the apply_qc default. The description only restates the filter categories (box, time, station, cruise, height, quality control) without adding syntax, interaction, or precedence detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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?

"Observations for one variable, filtered by box, time, station, cruise, height and quality control" gives a specific verb (retrieve observations), a specific resource (a single variable's data), and enumerates the filter axes. This clearly separates it from sibling tools like aggregate, estimate, and describe_variable, which operate on variables rather than returning raw observations. It stops short of naming those siblings explicitly, so it lands at 4 rather than 5.

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?

There is no explicit when-to-use / when-not-to-use statement and no pointer to alternatives such as aggregate for summarised results or search_variables for obtaining the required id. Usage is only implied by the phrase "Observations for one variable" and by the citation obligation at the end. An agent can infer the purpose but must reason about sibling selection on its own.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds useful context about the shape of the result set (one entry per data store, with coverage, licence and DOI), but says nothing about result size, pagination or freshness.

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?

A single sentence, front-loaded with the action and resource, with the returned attributes packed into a parenthetical. No filler and nothing repeated from the schema or annotations.

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 does not need to enumerate return fields in detail, and it already summarizes them. For a zero-parameter read-only listing, this is nearly complete; only the absence of any statement about the catalogue's scope or ordering leaves a small 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The description correctly implies no filtering is possible — callers get the whole catalogue.

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 ICOS datasets") and adds the granularity (one per data store) plus the fields returned. An agent can tell this is the catalogue-level discovery tool rather than a data retrieval tool, though it never names a 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: a catalogue listing is naturally the first step before get_data or find_stations, but the description never says so, nor does it state any precondition or exclusion. No explicit when-to-use versus alternatives guidance is present.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The one genuine addition is the result-ordering trait: "Primary measurements come before their companions (standard deviation, value counts, flags)," which the agent cannot infer from the schema. Nothing is said about ranking, matching behaviour on partial terms, or empty results, and the return shape is covered by the output 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?

Three short sentences, purpose front-loaded, followed by the downstream use and then the ordering caveat. No filler or restatement of the tool name, and every sentence contributes information the agent would otherwise lack.

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?

The tool is a simple, well-annotated search with full schema coverage and an output schema, so return values need no explanation. Purpose, downstream use, and result ordering are all present; the only thin spot is interaction with the optional `store`/`domain` filters, which are already documented 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 description coverage is 100%, including concrete examples for `text` and defaults/bounds for `limit`, so the schema carries the parameter burden. The description only restates the searchable facets (name, quantity, unit) without adding syntax, matching, or filter-combination semantics. 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 gives a specific verb and resource ("Find variable ids in the ICOS catalogue") plus the searchable dimensions (name, quantity, unit), so the agent knows exactly what the tool returns. It does not, however, contrast itself with the closely related sibling describe_variable, so the boundary between "search for an id" and "describe a variable" is left implicit.

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 the downstream contract clearly — "The ids are what estimate and get_data take" — which tells the agent this is the lookup step before those tools. It stops short of explicit when-not guidance or naming alternatives such as describe_variable or find_stations.

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