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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered; the description adds the 20-name practical cap and the exact facets returned per name (QA/QC range, QC meaning per resolution, sign conventions, site instrument/height/coverage). It says nothing about behavior on unrecognized or malformed names, which is the notable remaining 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 verb and the 20-name scope, then the decoding facets, then the site behavior and the next-step pointer. Information-dense and largely tele grams-style, with the only cost being the compressed comma-spliced listing that takes a second pass to parse.

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 annotations covering the safety/idempotency profile, the description need not restate return structure, and it covers all three parameters plus the workflow handoff. The one omission is failure/partial-match behavior for unknown names, which matters when passing arbitrary file headers.

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 baseline is 3, but the description goes beyond it by explaining the name grammar itself with concrete token families (_PI, _QC, _F, _IU, _H_V_R, MDS, VUT/CUT, NT/DT, REF, percentiles) and by clarifying what 'site' unlocks. That materially helps an agent build valid 'names' values rather than just reading 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?

Specific verb 'Decode' plus a precisely scoped resource: up to 20 variable names from BASE or FLUXNET files, with an enumerated list of what gets decoded (base name, FP Standard definition, qualifiers, position tokens, units, QC, sign conventions). This clearly separates it from the sibling amf_search_variables, which finds names rather than explaining 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 framing 'Decode ... from BASE or FLUXNET files' plus 'With site: whether the site measures it...' makes the use context clear, and 'Next: call amf_get_availability for the site's years' gives an explicit follow-up step. It stops short of naming when to use amf_search_variables instead, so no true alternative 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?

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds real behavior beyond them: pre-request validation of product/policy pairs, enumeration of sites lacking data with reasons, and the policy obligations the selection must follow. It does not discuss pagination or result volume behavior.

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 dense sentences, front-loaded with what is returned, then edge cases, then the next step; little waste. The product/policy enumeration in the first sentence is compressed but readable.

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-value explanation is not required; the description still covers the important non-obvious behaviors (invalid pairs, missing-site reporting, policy obligations) and the workflow handoff. Only pagination/large-result behavior is left 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?

With 67% schema coverage, the description still adds meaning: it explains that policy filters to data usable under that policy versus the default of labelling each row with its own policy, and it frames products as tied to site collections. It leaves limit/offset and the year-window syntax to 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 names the exact resource and scope: published years per site for BASE-BADM, FLUXNET, FLUXNET2015, FLUXNET-CH4 and BIF membership, each row labelled with its data policy. It also states secondary outputs (sites without data and why, the governing policy), which cleanly separates it from siblings like amf_search_sites or amf_list_files.

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 a concrete follow-on step ("call amf_get_citation for these sites") and a precondition (invalid product/policy pairs fail before any request), which steers usage. It stops short of naming an alternative tool and when to prefer it, so no explicit when-not guidance.

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/openWorld, so the safety profile is covered; the description adds real behavioral detail beyond that: emails are suppressed unless the server's privacy.allow_contact_emails permits them, and instruments include measurement heights. It stops short of describing pagination behavior for the reference-paper list, which the limit/offset params imply.

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 sentences, front-loaded with the resource definition, then the BIF alternative, then the next-step routing. The long enumeration is dense but every item maps to a real returned section; nothing is padded.

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 explain return values, and the annotations cover the safety profile. It is nearly complete for a read tool, with only the paginated nature of the reference-paper section left implicit.

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 83%, so the schema already carries most parameter meaning. The description reinforces the section grouping used by `include` and the default email suppression for `include_contacts`, but adds nothing about `variables` filtering syntax or about how `references_limit`/`references_offset` paginate, leaving those to 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 names a specific verb-and-resource pair (get a site's BADM metadata) and then enumerates the exact sections returned (location, IGBP/climate, tower dates, team, disturbance, funding, references, instruments), which lets an agent distinguish it from siblings like amf_read_bif or amf_get_site. It also flags what is not included by default ('team (no emails by default)').

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 full BADM ships as the BIF file in BASE-BADM downloads' implicitly routes the agent to amf_read_bif for the complete record, and 'Next: call amf_get_citation to cite the site' gives an explicit follow-up step. There is no explicit 'do not use this when...' exclusion, so it falls 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.

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

Beyond the annotations, the description discloses substantial behavioral detail: versioned DOI text, licensing obligations and mixing rules, verbatim acknowledgments, funding statements, data-availability language, processing papers, and optional BibTeX. The read-only, idempotent, open-world annotations are consistent with a citation-retrieval operation.

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 front-loaded with the core resource and remains information-dense without obvious filler. The long parenthetical list of return contents is useful but slightly dense; it could be structured more readably, though it does not waste words.

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 annotations covering safety behavior, the description supplies enough context about returned citation components, licensing obligations, and follow-up actions. An agent has what it needs to invoke the tool correctly and understand the output's purpose.

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 the parameter meanings are already fully documented. The description reinforces the site limit and product options but adds little semantic detail about parameters beyond what the schema provides, making the baseline 3 appropriate.

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 resource is citations/acknowledgments for up to 50 sites and one product, with concrete returned items. This is a distinct purpose from sibling data-access tools such as amf_get_site or amf_get_badm, so an agent can identify the correct tool without ambiguity.

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 gives clear usage context through 'Next: cite every site in the reference list and follow the obligations,' which explains what to do with the result. It does not explicitly name when to choose this over alternatives or state exclusions, but the purpose is specific enough that usage is well implied.

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, but the description adds real behavioral context they don't: emails are suppressed by default, include_contacts is server-gated by a privacy setting, and the data policy is returned 'with what it means.' It stops short of disclosure on response size or truncation for large sites.

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?

Dense but front-loaded: identifier forms first, payload contents next, routing advice last. The telegraphic comma-separated style is efficient; a slightly clearer sentence boundary between payload and next-step guidance would help readability.

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, enumerating return fields isn't strictly required, yet the description gives the agent enough to know this payload satisfies site-detail questions. Privacy defaults and next-step tools are covered; only the search-vs-get decision is 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%, so site, include, and include_contacts are already fully documented, including the enum values and the default-all behavior. The description echoes the identifier forms without adding syntax or edge-case detail beyond the schema, so 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 names the resource ('one site'), the accepted identifier forms, and enumerates the returned content (location, IGBP/Köppen, DOIs, years per product, team, variables). This is far more specific than a restated title and makes it trivially distinguishable from amf_search_sites and amf_get_availability.

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 explicit next-step routing: 'call amf_get_availability for exact years or amf_get_citation to cite it.' What's missing is the inverse guidance against the closest competitor, amf_search_sites (i.e., 'use this when you already have an ID; otherwise search first').

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, so safety is covered; the description adds real behavior: each archive's members are classified by kind, site, resolution, years and version, and unsafe members are flagged. The phrase 'stdio only' is unexplained and is the one piece of context an agent cannot act on.

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 purpose, then scope, then classification behavior, then the next action. The middle sentence is a dense enumeration of file kinds and member fields that borders on over-packed, but no sentence is 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 needn't explain return values, and annotations cover mutability, so the remaining burden is scope and post-call routing — both supplied. The gaps are pagination behavior for limit/offset and the opaque 'stdio only' clause.

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 67%, and the description covers the spirit of path (download directory / configured local roots), site, and include_members ('members classified by kind'). It says nothing about limit/offset paging despite those being 2 of the 6 parameters, so the schema still carries the paging 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?

States a specific verb and resource ('Find the AmeriFlux and FLUXNET files already on this computer') and enumerates the artifact families it covers (BASE/BASE-BADM zips, BIF, ONEFlux, FLUXNET2015). The 'already on this computer' scoping immediately distinguishes it from siblings like amf_search_sites and amf_get_availability, which operate on remote catalogs.

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?

Provides a clear next-step handoff ('call amf_preview_data(file=...) on one'), which is genuinely useful routing. However, it never states when NOT to use it — e.g., that a site not present locally should be fetched first or looked up via amf_search_sites — so the alternative path is left implicit.

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?

Beyond the annotations (readOnly/idempotent/openWorld/no-destructive), the description adds real value: identity output is 'booleans and profile names only, never the values' (a privacy guarantee), and it clarifies that network contact only happens when check_api=true, refining the broad openWorldHint. It doesn't quantify cost or latency of the API probe, keeping it short of 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?

Front-loaded with the core purpose, then grouped details, then a next-step pointer; every clause carries distinct information. The semicolon-dense enumeration is efficient but slightly packed, so it is not maximally crisp.

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-value documentation is not required, yet the description still summarizes the report contents. Combined with annotations covering safety/idempotency and the conditional network note, an agent has everything needed to call this correctly.

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?

With one parameter and 100% schema description coverage, the schema already explains check_api. The description restates the same condition and only marginally adds the notion that it is 'one small request' to a specific endpoint. Baseline 3 for full schema coverage is appropriate.

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 names a specific diagnostic operation ('Liveness and capability report') and enumerates exactly what it reports: server version, protocol/transport, download-identity configuration status, download enablement and file destination. No sibling tool in the list performs status/diagnostics, so the role is unambiguous and distinct from the data-retrieval siblings.

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 condition for the optional behavior ('With check_api=true it also makes one small request... to confirm connectivity') and gives an explicit next step ('read ameriflux://guide/identity to set up downloads'). It does not state when *not* to call this or contrast it against any sibling, but no sibling overlaps, so the practical guidance is clear.

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, destructiveHint=false, and openWorldHint=false. The description adds useful operational context: output 'stops within a byte and time budget' and the tool is 'stdio only', which matters for an agent's expectations around scope and environment.

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 front-loads the core purpose and uses dense but informative phrasing. The first sentence is a long feature list that could be more structured, but every item maps to a real capability 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?

For a complex 14-parameter local preview tool with an output schema, the description covers data sources, high-level output content, resource budget limits, stdio-only operation, and the recommended next step. It leaves details like file-vs-site/product mutual exclusivity to the schema, which is reasonable.

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 schema has 100% description coverage across 14 parameters, so the baseline is 3. The description adds high-level feature mapping (time step/range, QC filter, BIF-based UTC timestamps, SUBSET view, aux tables) but does not add parameter-specific syntax or defaults 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?

States specific verbs ('summarize or page through') and a precise resource ('local BASE, AmeriFlux FLUXNET or FLUXNET2015 CSV, in place or inside its zip'). It is clearly scoped to local files and previewing, though sibling differentiation appears mainly as a next-step reference to amf_describe_variables rather than an explicit comparison.

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?

Implies the tool is used to preview before decoding, via 'Next: call amf_describe_variables on columns to decode', and notes 'stdio only'. However, it does not say when to choose this over amf_list_files, amf_get_badm, or other siblings, nor when not to use it.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the description's real contributions are the privacy behavior ('Emails and addresses are withheld by default'), the archive-unwrapping capability ('also from inside the zip'), and the transport constraint ('stdio only'). Those are genuinely additive traits not derivable from the structured fields.

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 verb and resource, and every clause adds information about contents or behavior with no filler. The middle is a single dense run-on enumeration with awkward fragments ('also from inside the zip'), which slightly hurts scannability but costs no wasted text.

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 described, and the safety profile is carried by annotations. The remaining gap is input disambiguation: with 7 optional parameters and neither `file` nor `site` required, the description never says which selector wins or what the default behavior is when none is supplied.

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 71%, so the schema already documents most parameters; the description adds only loose mapping (groups -> 'entries by group (location, IGBP, team, instruments, disturbance …)', include_contacts -> withheld emails/addresses). It says nothing about pagination via `limit`/`offset` or about the bulk-file `site_id` filter, both of which carry no description 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?

Names a specific verb ('Read') and a specific resource (a local BADM Interchange Format file), then enumerates the payload (groups, UTC offsets, DOI/citation, funding) so the agent knows what comes back. It does not explicitly contrast with the sibling amf_get_badm, which likely serves the same content from a remote source, leaving the local-vs-remote distinction to be inferred.

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 a routing pointer ('Next: call amf_get_citation for the current citation') and clarifies the input shapes (BASE-BADM xlsx, FLUXNET CSV, or inside the zip), which implies when to reach for it. However, there is no explicit statement of when NOT to use it versus amf_get_badm or amf_list_files, and no guidance on what happens when both `file` and `site` are omitted.

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 that results include years per product, facets over all matches, and paging — useful behavioral context, though an output schema exists and covers the return shape in more detail.

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: the search capabilities are front-loaded after the verb, and the routing advice comes last. The long filter list is information-packed but borders on a run-on; still, every clause corresponds to an actual query dimension.

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 19-parameter search tool with full annotations and an output schema, the description covers what can be searched (place, ecosystem, climate, networks, products, variables), what comes back, and where to go next. No major gap an agent needs to call it correctly.

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 89%, so the schema documents nearly all 19 parameters including defaults and formats. The description's enumeration of filter categories largely restates what the schema already provides, adding little syntactic or semantic detail beyond it. 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?

Opens with a specific verb and resource ('Find flux tower sites') and names the three catalogs with site counts. The enumerated filter dimensions make its scope clearly distinct from siblings like amf_get_site or amf_search_variables.

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 closing sentence routes the agent explicitly: use amf_get_site for a single site, amf_get_availability for exact years. That is a clear next-step rule, but it does not state when to prefer this search over the sibling amf_search_variables, nor any exclusions.

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, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: units vary by resolution (NEE in umol m-2 s-1 at HH vs gC m-2 d-1 at DD) and each result carries per-resolution units plus SUBSET membership — non-obvious output traits an agent needs to interpret 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 sentences plus a one-line next step; the searchable corpora are front-loaded and the units caveat follows immediately. No filler, no restatement of the title.

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, yet it still summarizes what each result row carries. It omits pagination/default-limit expectations for a 6-param search tool, a minor gap given all params are optional and defaults are 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 67%, so the schema carries most parameter definitions. The description adds rationale the schema lacks — why `resolution` matters (units are resolution-dependent) and how the dictionary variants differ (BASE vs ONEFlux v1.3 vs FULLSET/SUBSET) — though `limit`/`offset` paging is left entirely to 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?

Names a specific verb (find) and resource (variable names), and enumerates the exact corpora searched: FP Standard (AmeriFlux BASE) and three FLUXNET dictionaries including ONEFlux v1.3 and FLUXNET2015 FULLSET/SUBSET. The closing pointer to amf_describe_variables makes the boundary with that sibling unambiguous.

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?

States the three search axes (words, category, resolution) and gives an explicit next step: 'call amf_describe_variables on the names', which routes the agent in a two-step workflow. It stops short of naming when NOT to use this tool (e.g., vs amf_search_sites for site lookup), so no exclusion guidance.

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