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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states that the tool retrieves series side by side and does not merge them, which is important non-destructive context. However, it leaves 'obvious metadata differences' undefined and says nothing about permissions, rate limits, or error 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?

A single, front-loaded sentence conveys the core behavior with no filler. Every phrase ('side by side', 'without merging') adds 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?

The output schema covers return values, and the description communicates the main behavior, but the lack of usage guidance and parameter semantics leaves gaps for a six-parameter tool. Required fields like country_codes are not motivated, and no alternative routing is given. Still, the core operation is understandable, so it is minimally viable.

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

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

Schema description coverage is 0% and the description adds no parameter-level meaning beyond what the property names already convey. It does not explain required country_codes or the optional start_year, end_year, latest_only, and include_original parameters, so the agent has to guess their semantics from names and 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 names a concrete verb ('Retrieve'), a specific resource ('series'), and the differentiating outcome ('flag obvious metadata differences without merging them'). This makes it easy to distinguish from sibling get_observations, which would just fetch 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 implies the tool is for side-by-side comparison, but it never states when to choose compare_observations over get_observations or find_microdata, nor does it list exclusions. There is no explicit 'use this when...' guidance, leaving the agent to infer the intended scenario.

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?

With no annotations provided, the description must disclose behavioral traits. It mentions 'live' indicating current data, but does not explain pagination (though cursor/limit are in schema), filtering, or what the response contains beyond listing. There is minimal disclosure of operational 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?

The description is a single, concise sentence that is front-loaded with the action. It is efficient, but it may be too brief for a tool with multiple parameters. Structure is clean, though it lacks elaboration.

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 tool with 5 optional parameters and no annotations, the description is noticeably incomplete. It does not explain any parameter semantics, the output structure, or provide examples. While an output schema exists, its content is unknown, so the description carries the burden of detail and falls short.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters like limit, cursor, status, group_code, and include_archived. The description does not mention any of them, adding no value for parameter understanding.

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 it lists FAOSTAT groups and domains, with a specific purpose: to build source-qualified series. The verb 'List' and resource 'FAOSTAT groups and domains' are specific. It does not explicitly distinguish from sibling tools like list_sources, but the FAOSTAT context and specific object make its purpose clear enough.

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?

No guidance is given on when to use this tool versus alternatives. It does not mention any sibling tools or conditions that would select this tool over others. The description simply states what it does without any contextual advice.

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?

With no annotations, the description carries the full burden of behavioral disclosure, but it only says 'Search' and gives no details about pagination, cursor behavior, match semantics, or data-source quirks. It is not misleading, but it adds minimal behavioral context.

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, readable sentence with no wasted words. It is concise and front-loads the core action and resource, though it sacrifices substance for brevity.

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 has 5 parameters (3 required), no annotations, and no parameter descriptions, but the description only gives a high-level purpose. It lacks instructions on how to specify dataset and dimension, how query is matched, and how pagination works. An output schema exists, so return values need not be described, but the calling context is still under-specified.

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

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

Schema description coverage is 0%, and the description does not explain dataset, dimension, query, limit, or cursor. It only hints that dimension refers to definition tables like area/item/element/unit, which is not enough to compensate for the complete lack of schema-level parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Search') and resource ('FAOSTAT domain's area, item, element, unit, or other definition table'). It conveys the tool's scope clearly, though it does not explicitly differentiate itself from sibling search tools like search_indicators.

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?

No guidance on when to use this tool versus alternatives such as search_indicators or faostat_list_domains. Usage context is only implied by the name and one-line description; there are no exclusions or selection criteria.

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?

With no annotations provided, the description carries the burden of behavioral disclosure. It does say the tool will 'state their access conditions', which hints at the output, but it does not explain search relevance, filtering, limitations, or how results are ordered. This is acceptable but not rich.

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 dense sentence with no wasted words. It front-loads the core action and then specifies what the tool returns, making it easy to scan and interpret.

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 relatively simple with only two parameters and an output schema present. The description covers the basic purpose and result, but the unexplained 'country' parameter and the lack of any guidance on how relevance is determined leave meaningful gaps for an agent trying to invoke 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 description coverage is 0%, so the description must compensate for parameter meaning. The required 'query' parameter is self-evident, but the optional 'country' parameter is entirely unexplained: does it filter by the country of the data, the source, or the catalogue? The description adds no parameter-level value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Find') and a specific resource ('public microdata catalogues'), and adds what the tool produces ('state their access conditions'). This clearly differentiates it from siblings like list_sources or search_indicators, which target different resources or purposes.

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 implies the tool is for locating public microdata catalogues and access conditions, so an agent can infer when to use it. However, it gives no explicit guidance about when not to use it or which sibling alternative to prefer, leaving the decision to inference.

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?

No annotations are provided, so the description carries the burden. 'Retrieve' clearly indicates a read-only operation, and 'authoritative' adds a data-quality expectation. But it does not disclose error behavior, access requirements, or any limitations, leaving the behavioral profile minimally but not fully transparent.

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 with no filler. It states the action and object efficiently, though the brevity leaves some details to inference.

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 one parameter and an output schema present, the description doesn't need to explain return values. Still, it omits a concrete series_ref format and any guidance on choosing this tool over siblings, making it adequate but not complete for a one-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?

The schema describes series_ref only as a required string with zero coverage. The description adds the meaningful qualifier 'source-qualified', indicating the reference must carry source qualification, but it stops short of specifying the format or providing an example.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Retrieve') and identifies the resource ('authoritative metadata') and target ('source-qualified series reference'). This distinguishes it from search-oriented siblings like search_indicators, though it doesn't explicitly contrast with get_source_setup or list_sources.

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 phrase 'for a source-qualified series reference' implies the tool is used when a caller already has such a reference and needs its metadata. However, there is no explicit when-to-use guidance, exclusions, or reference to sibling tools, so the usage context is only 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?

With no annotations, the description must carry the behavioral disclosure burden. It communicates that this is a read-only retrieval operation and that metadata, citations, and warnings are preserved in the output. However, it does not address permissions, errors, pagination, or how the various options affect 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?

The description is a single concise sentence that front-loads the core action and adds a useful qualifier. Every word contributes meaning, and there is no redundant or filler content.

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?

Although an output schema exists, the tool has six parameters, two required, and no annotations. The description does not explain how to construct a valid request or which parameters matter for which use cases, so it is not complete enough for reliable tool invocation.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It provides no explanation of series_ref, country_codes, start_year, end_year, latest_only, or include_original, leaving the agent to infer their meaning entirely from names and 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 clearly identifies a specific action ('Retrieve official observations') and a distinguishing feature ('retaining metadata, citations and warnings'). It is not a tautology and conveys what the tool returns, though it does not explicitly contrast with sibling tools like compare_observations.

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 guidance on when to use this tool versus alternatives such as compare_observations or search_indicators. The phrase 'official observations' implies a use case, but the description provides no when-to-use or when-not-to-use 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It only adds the constraint that server secrets will not be exposed, which is useful, but it does not say whether the operation is read-only, requires authentication, has side effects, or what the response contains. The output schema covers return values, but invocation behavior remains unclear.

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, front-loaded sentence that communicates the core purpose and a key behavioral constraint without wasted words. 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?

The tool is simple (one required parameter, output schema present), but the description does not provide enough context for a correct invocation: no indication of where source_id comes from, no usage conditions, and no behavioral details such as auth or caching. The secret-exposure constraint is the only extra context 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?

The schema has 0% description coverage for the single source_id parameter. The description does not explain what source_id refers to or how to obtain valid values (e.g., from list_sources). Because the schema is bare and the description does not compensate, an agent is left to infer source_id semantics from its name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Explain') with a clear resource ('source access requirements'), so an agent can tell that the tool describes how to access a source. It does not explicitly distinguish itself from list_sources, but the focus on access requirements separates it from listing sources.

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 phrase 'Explain source access requirements' implies the tool is for users who need setup or access details for a specific source. However, it gives no explicit when-to-use or when-not-to-use guidance and does not mention any sibling alternatives, so an agent must infer the context from the name and description.

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?

There are no annotations, so the description carries the behavioral disclosure burden. It adds meaningful scope detail ('supported and planned') and content detail ('access characteristics'), and 'List' implies a read-only operation. However, it does not disclose auth requirements, pagination, or any side-effect status beyond that implication.

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 with no filler or redundant phrasing. Every word contributes to the tool's purpose and scope.

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 definition is simple and an output schema exists, but it omits any explanation of the optional topic parameter and provides no usage guidance relative to sibling tools. These are real gaps for an agent deciding whether and how to invoke this 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?

The schema has one optional 'topic' parameter with 0% description coverage, and the description never mentions topic or its effect. The agent can guess from the parameter name that it might filter by subject, but the definition provides no explicit semantic help.

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 ('List'), a specific resource ('supported and planned official data sources'), and the type of information returned ('their access characteristics'). It does not explicitly contrast with sibling tools like get_source_setup or find_microdata, but the resource scope is clear enough to distinguish it.

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?

No guidance is given about when to use this tool versus alternatives such as get_source_setup or find_microdata, and no exclusions or prerequisites are mentioned. The intended use case is only implied by the verb and resource.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently states the core transformation behavior, but it does not disclose handling of unrecognized inputs, normalization behavior, accepted code variants, or error behavior. The description is not misleading, but it leaves meaningful behavioral gaps.

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 with no filler. It states the action, input, output standard, and provides useful examples in about fifteen words. Every element contributes to understanding.

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 simple with one parameter and an output schema, which covers return shape. Still, the description lacks important context about accepted input code formats, behavior on invalid or mixed inputs, and whether names must be exact. These are clear gaps for an agent invoking the tool 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?

The schema provides only an array of strings with 0% description coverage. The description adds meaning by indicating the strings are 'country names or codes' and that the output is ISO alpha-3. However, it does not specify which code types are accepted (e.g., alpha-2, alpha-3, numeric) or case sensitivity, so the parameter semantics remain only partially clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Resolve') and names the exact resource and output format: country names or codes to ISO 3166-1 alpha-3 codes, with concrete examples (GHA, KEN). This clearly distinguishes it from the sibling data-retrieval tools, none of which perform geographic resolution.

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 intended use case is implied: use when you need to convert country names or codes to ISO alpha-3 codes. However, there is no explicit when-to-use guidance, no mention of exclusions, and no alternatives are named. The description does not clarify which input code formats are accepted or what to do with ambiguous or invalid inputs.

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?

With no annotations, the description carries the burden of behavioral disclosure. It helpfully reveals that results include ranking, match evidence, retrieval health, and source failures—non-obvious diagnostics. However, it does not explain how ranking works, whether query matching is fuzzy or exact, or any pagination/limit 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?

The description is a single, front-loaded sentence with no wasted words. It puts the ranking behavior first and immediately summarizes the return payload. It could be slightly more informative, but it is efficiently structured.

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?

Despite the existence of an output schema and only three parameters, the description leaves important context undefined: what constitutes an official indicator, which sources are searched, how ranking is determined, and when source failures occur. With no annotations and 0% parameter coverage, this is too sparse for reliable invocation in an unfamiliar context.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain query syntax, the meaning of limit, or how source_ids filters results. Only the tool name and the phrase 'source failures' faintly hint at query and source-related parameters; this is minimal compensation.

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 action—ranking/searching official indicators—and states that it returns match evidence, retrieval health, and source failures. This distinguishes it from metadata or observation retrieval tools, though it does not explicitly contrast with a sibling search tool like find_microdata.

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?

No guidance is provided about when to use this tool instead of alternatives such as find_microdata, get_indicator_metadata, or list_sources. The implied use case is 'search for indicators,' but exclusions, prerequisites, and routing conditions are absent.

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