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

No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait — that the output is an input to two other tools — which is genuinely useful, but says nothing about read-only safety, the lang parameter's effect on results, or the shape/scope of the returned list.

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 with the action first and the usage linkage parenthetically after. 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?

An output schema exists, so return-value explanation is not required, and the description covers what the tool yields and how it is consumed. The only meaningful omission is the undocumented lang parameter, which leaves a small gap for a discovery 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?

There is one parameter (lang) with 0% schema description coverage, and the description never mentions it. The agent gets no indication that the listed definition types are language-dependent, so the description fails to compensate for the coverage gap.

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

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

States a specific verb+resource: 'List all available definition types.' It also distinguishes itself from the two siblings it feeds into (faostat_get_definition_type, faostat_get_definitions_by_type), so an agent can place it correctly without opening any 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?

Explicitly routes the agent: use the result with faostat_get_definition_type for FAO-wide definitions or faostat_get_definitions_by_type within one domain. That is clear downstream guidance, though it doesn't state that this tool should be called first to discover valid type values or note any prerequisite ordering.

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 supplied, so the description carries the full burden. It discloses two genuinely useful behaviors: filter codes differ from display codes (with a concrete example) and limit=0 returns all codes. However it says nothing about auth/permission requirements, whether the operation is read-only, or rate/latency characteristics.

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?

Four tight sentences: purpose first, then the alternative routing, then the critical filter-vs-display caveat, then the limit special case. Every sentence carries information and the most important routing guidance is front-loaded. Not maximal only because the code-distinction note is dense enough to warrant light framing.

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 description covers purpose, alternative tool, and the key code-type quirk. For a 4-param tool with 0% schema coverage and no annotations, though, it omits what dimension_id values are valid and any auth/prerequisite context, leaving real gaps.

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 all four parameters rely on the description and their names. The description clarifies the non-obvious limit parameter (limit=0 returns all codes) and frames domain_code within "domain FILTER codes," but dimension_id (the key selector for which code dimension to browse) is left without semantics; lang is only inferable 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?

States a specific verb and resource ("Browse domain FILTER codes") and explicitly distinguishes itself from the sibling faostat_search_codes for named lookups. The added distinction between filter codes and display codes sharpens the purpose further. Not a 5 only because "browse" is slightly loose, but the intent is unmistakable.

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 an explicit routing rule: "Prefer faostat_search_codes for named lookups," which tells the agent when to pick the alternative over this tool. It lacks an explicit "use this when..." positive condition and no exclusions beyond the one sibling, so it stops 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?

With no annotations, the description carries the burden and does disclose real behavioral traits: limit defaults to 50 and limit=0 returns all rows, filter codes differ from display codes, units are preserved, and multiple response formats (compact/objects/csv) are supported. It omits auth/permission needs and pagination beyond limit, but the disclosure is substantial.

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 purpose is front-loaded in the first sentence, and the following clauses are dense with actionable instruction and little waste. Some abbreviations ('QCL Production') and packed directives are slightly cryptic, but the structure is efficient for a 17-parameter 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?

An output schema exists, so return values need not be explained, and the description supplies solid operational guidance for a complex tool. However, for 17 parameters with zero schema descriptions and no annotations, the many unexplained flags and _cs variants leave it short of complete.

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 0% across 17 parameters, so the description must compensate, but it only meaningfully covers a handful (element, limit, response_format, fields, area/item/year filtering). The four _cs variants (area_cs, item_cs, year_cs, element_cs), lang, show_unit, show_codes, show_flags, null_values, and domain_code are entirely undocumented. The element filter-code detail is genuinely valuable but does not offset the large uncovered majority.

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 ('Fetch domain data') and distinguishes itself from siblings by naming faostat_search_codes as the prerequisite and faostat_get_datasize as a scoping helper. The resource 'domain data' is somewhat generic, but the operational framing makes it clear this is the primary data-retrieval tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly routes the agent: resolve filter codes with faostat_search_codes first, check datasize when unsure, and prefer response_format='compact'. It names the alternative tools and the conditions that select them, leaving little 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?

With no annotations, the description carries the full burden, and it does disclose the key traits: the result is an estimate (approximate), it happens 'BEFORE fetching' (cheap, non-retrieving), and it mirrors the filters of the data tool. It stops short of stating accuracy, cost, or any caveats about the estimate, so it is not fully transparent, but the essential behavioral profile is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the outcome, then the usage trigger, then the parameter relationship. No filler or repetition; every clause carries 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?

An output schema exists, so return values need not be explained, and the pre-fetch purpose is clear. But with 10 undocumented parameters at 0% schema coverage, an agent still lacks the field-level detail needed to construct a valid query beyond the pointer to faostat_get_data.

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% across 10 parameters, so the description must compensate; it partially does by asserting 'Accepts the same filter parameters as faostat_get_data', which lets an agent borrow that tool's semantics. However, it adds no per-parameter meaning (e.g., the area vs area_cs distinction, domain_code requirement) on its own.

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 ('Estimate the number of rows a data query will return') and explicitly distinguishes itself from the sibling faostat_get_data by framing itself as a pre-fetch check. An agent can tell exactly what this tool produces 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 an explicit trigger ('Use this to check if a query is too large before calling faostat_get_data') and names the alternative it precedes. The when-to-use condition and the routing decision are both spelled out rather than inferred.

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 behavioral burden. It discloses the scope of the result set (all definitions for a given domain), which is useful, but says nothing about whether this is a safe read-only call, whether results are cached or paginated, or whether a valid domain_code must first be obtained from a listing 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?

A single compact sentence with the resource and scope front-loaded and no filler. It is efficient, though arguably too terse given the ambiguity with sibling tools.

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 the description need not explain return values, and its brevity is partly justified. However, given a sibling set containing four other definition-related tools with overlapping names, the description is not complete enough to guarantee correct tool selection.

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 both parameters and does so only partially: "for a domain" implies domain_code but gives no format or example, and the lang parameter (default "en") is never mentioned at all.

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 clear verb+resource ("Get all definitions") and scopes it to a domain, with a parenthetical clarifying that definitions cover items, elements and flags. It does not, however, distinguish itself from near-identical siblings such as faostat_get_definitions_by_type, faostat_get_definition_type, or faostat_definition_types, which an agent could easily confuse with 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?

There is no guidance on when to use this tool versus the many sibling definition tools. The agent is left to infer that "all definitions" means the unfiltered superset and that faostat_get_definitions_by_type is the filtered alternative, but the description never says so.

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 full behavioral burden. It reveals that the result is filtered by a 'type' such as items, elements, or flags, but says nothing about permissions, rate limits, pagination, localization via the lang parameter, or return behavior, leaving key operational traits undisclosed.

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 a single, front-loaded sentence that directly states the tool's function and includes an example of the filter values. It is short and wastes no words, though it is arguably too terse for a tool with undocumented parameters.

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 input parameters have zero schema description coverage, no annotations are present, and the description does not cover parameter semantics beyond definition_type or clarify when to use this tool versus its many siblings. The definition is incomplete for correct invocation in a multi-tool environment.

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 there are three parameters. The description clarifies that definition_type accepts values like items, elements, or flags, which is useful, but it says nothing about domain_code or lang, and no parameter descriptions exist in the schema to compensate.

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 (get) and resource (definitions) with a filtering scope ('by type'). It distinguishes itself from siblings like faostat_get_definitions and faostat_definition_types by combining the definition retrieval with a type filter, but it does not explicitly differentiate from those close siblings in the description text.

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 faostat_get_definitions, faostat_definition_types, or faostat_get_definition_type. The only implied use is retrieving definitions filtered by a type, which is a restatement of the name rather than decision support.

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. It does disclose useful behavior: search operates on text columns, limit=100 with 0 returning all, response_format choices, and the caveat that definition codes are not necessarily query filter codes. It omits auth/permission requirements and pagination behavior, so the disclosure is partial.

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: scope first, then sibling routing, then per-parameter notes. Slightly telegraphic, but each sentence carries operational information and nothing is redundant.

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 needed, and the description covers most invocation details. Still, with 0% schema coverage and no annotations, the undocumented lang parameter and absent auth/behavior notes leave it not fully complete.

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. It usefully explains search (filters text columns), limit semantics (100 default, 0 = all), and response_format values, plus the accepted definition_type values. However, the 'lang' parameter is never addressed, leaving a gap at low coverage.

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

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

States a specific verb+resource with scope ('Get FAOSTAT-wide definitions without a domain') and enumerates the definition types covered. It distinguishes itself from the domain-scoped siblings, though it doesn't clearly separate itself from faostat_get_definitions_by_type, which sounds nearly identical.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly routes the agent: 'use faostat_definition_types for all types' names the alternative and the condition for choosing it, and the 'without a domain' qualifier scopes when this tool applies. No explicit when-not guidance against the other definition tools.

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 behavioral burden. It discloses that the output is a structural listing of filterable dimensions, which is genuinely informative, but says nothing about read-only nature, permissions, or pagination/latency. For a simple read-only getter this partial disclosure is adequate 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?

A single front-loaded sentence with the core action first and illustrative examples second. No filler; every clause adds meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be described, and the description conceptually explains what the call yields. The main remaining gap is usage/parameter detail, but for a two-parameter read tool the description is largely complete.

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 both parameters. It only loosely implies a 'domain' argument (matching domain_code) and never mentions the optional lang parameter or its role in returned labels. The critical parameter naming/semantics gap is left unfilled.

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 ('Get the structure of a domain') and clarifies what 'dimensions' means with concrete examples (area/country, item/commodity, element/measure, year). This makes the purpose unambiguous, though it never distinguishes itself from siblings like faostat_get_codes or faostat_get_metadata.

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 guidance, no prerequisites, and no mention of alternatives among the many sibling tools. The agent must infer that this is a discovery step from the phrase 'structure of a domain' alone.

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. It usefully discloses the scope of returned content (data sources, collection methods, coverage, limitations), but says nothing about whether this is a read-only/cacheable call, how the 'lang' parameter changes behavior, or any rate or auth constraints.

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 with no filler; the verb and scope come first and the enumeration of content types earns its place by telling the agent what it will receive.

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 details are not required here, and the content enumeration covers the 'what'. However, with no annotations and no parameter documentation, the description leaves the lang parameter and the domain_code format entirely unexplained.

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% across two parameters. The phrase 'for a domain' loosely implies domain_code, but no code format or example is given, and the lang parameter (with its 'en' default) is never mentioned in the description, leaving half the parameters undocumented anywhere.

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 (get) and resource (methodology and metadata) scoped to a domain, and enumerates the content types returned. It is clear what the tool does, though it does not explicitly distinguish itself from near-siblings such as faostat_get_definitions or faostat_get_definitions_by_type.

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 when-to-use guidance, no prerequisites, and no named alternative. An agent cannot tell from this text whether metadata should be fetched before or after faostat_get_definitions or faostat_get_codes, both of which sound adjacent.

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 behavioral burden. It does disclose one trait beyond the schema (output is printable/simplified), but says nothing about what is simplified or dropped, whether domain_code must be valid, or any access constraints. Given an output schema exists, return-value detail is not required, but the transformation semantics are unexplained.

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 short sentence with no padding, and the core action is front-loaded. Efficient, though the terseness contributes to the gaps elsewhere.

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 no annotations, 0% schema coverage, and a near-identical sibling (faostat_get_metadata), the description should at minimum differentiate the two and document 'lang'. An output schema exists, so return values need not be explained, but the variant's purpose and parameters remain 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% across two parameters. The description covers 'domain' loosely (mapping to domain_code) but says nothing about the 'lang' parameter, its default, or accepted values, so it only partially compensates for the documentation gap.

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

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

States a clear verb+resource ('Get metadata for a domain') and adds a format qualifier ('printable/simplified'). However, it never distinguishes itself from the sibling faostat_get_metadata, which appears to retrieve the same resource; the 'printable' modifier is the only hint of difference and is left unexplained.

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 statement of when to choose this over faostat_get_metadata or faostat_get_definitions. The phrase 'printable/simplified format' implies a human-readable use case but gives no condition or exclusion to act on.

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 present, so the description carries the full disclosure burden. It adds useful operational detail (default limit=10, response_format default and supported values), but omits ranking direction, whether it is read-only, and error behavior on invalid codes. Moderate but incomplete disclosure.

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?

Four short sentences with no filler, front-loaded with the core purpose and followed by the caveats that matter. Efficient, though the value/format notes could be grouped more tightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need no explanation, and the trickiest parameter (element_code) is well covered. Still, for a 7-parameter tool with no annotations, several parameters and the ranking direction are 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 coverage is 0%, so the description must compensate and it does so selectively: element_code's display-vs-filter distinction is genuinely valuable, and limit/response_format defaults are clarified. However domain_code, item_code, year, and lang receive no explanation, leaving a large share of the 7 parameters undocumented.

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 (rank) and resource (countries) with the scoping keys (domain/item/element/year), so the operation is unambiguous. It partially distinguishes itself from get_data by contrasting element_code semantics, though it does not explicitly name the sibling it competes with. Clear but sibling differentiation is only 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?

The comparison to get_data ('DISPLAY code ... unlike get_data filter code') hints at which tool to pick for display-ranked output, but there is no explicit when-to-use/when-not guidance or named alternative. Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: only "Get" implies a read operation. There is no mention of authentication, pagination, rate limits, response size, or what the opaque required payload does.

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 a single sentence, but the brevity reflects under-specification rather than efficient front-loading. Nothing is wasted, yet nothing useful is delivered.

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 (so return values need not be described), the combination of zero annotations, an opaque required nested payload, and no usage guidance makes this definition inadequate for correct invocation. An agent has no basis for constructing the payload.

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 required "payload" parameter is an unconstrained object with additionalProperties=true. The description adds no meaning whatsoever about what belongs in payload or how "lang" affects results, leaving the primary input completely undocumented.

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 verb ("Get") and a resource ("structured report data from FAOSTAT"), but "structured report data" is vague and overlaps heavily with siblings like faostat_get_data, faostat_get_report_headers, and faostat_get_metadata. An agent cannot tell from this text which of those it should call.

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 guidance on when to use this tool versus the many sibling retrieval tools, and no prerequisites or context are given. The agent is left to infer usage entirely from the name.

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 behavioral burden. It conveys only that this is a read-style metadata lookup; it says nothing about whether the payload requires a report identifier, auth requirements, rate limits, or failure modes. That is thin for a tool with a required opaque object parameter.

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?

One front-loaded sentence with zero filler, and the purpose is stated immediately. It is perhaps terse given the unexplained required object parameter, but nothing in it is wasted.

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. But for a tool whose only required input is an undescribed nested object and which has no annotations, the description omits the request-shape information an agent needs to actually 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% and the required 'payload' is an opaque object with additionalProperties=true, so the schema provides no semantic help. The description mentions 'a report' but never explains what belongs in payload or what 'lang' does, leaving the caller to guess the request shape.

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: 'Get the column headers/schema for a report.' It also distinguishes itself from the data-fetching sibling by noting this happens 'before fetching its data,' though it never names faostat_get_report_data 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?

The phrase 'before fetching its data' implies a workflow position (call this first, then fetch), which is useful implied guidance. However, it names no alternative tool and gives no when-not-to-use condition, so an agent must infer the pairing with faostat_get_report_data.

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 behavioral burden. It implies a safe read via 'Get' and signals potentially large output ('full hierarchical tree of all'), but says nothing about permissions, rate limits, or response size. Adequate but thin for an unannotated 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, purpose front-loaded, no filler. The second sentence is somewhat redundant with the first but does add usage value, so it earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the tool is simple with one optional param. Still, the description omits any guidance on 'lang' and any explicit tie-break against the list_groups/list_domains siblings, leaving small but real gaps.

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 single 'lang' parameter has 0% schema description coverage and the description never mentions it. Its purpose (label language) and valid values are left entirely to guesswork, so the description fails to compensate for the schema gap.

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

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

States a specific verb and resource: 'Get the full hierarchical tree of all FAOSTAT groups and their domains.' The word 'hierarchical' plus 'all' distinguishes it in spirit from the flat sibling tools faostat_list_groups and faostat_list_domains, but those siblings are never named, so the differentiation must 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?

'Use this for a complete overview of all available datasets' gives a use case, which is more than nothing. However, it never contrasts with the obvious alternatives (faostat_list_groups, faostat_list_domains) or states when a flat list would be preferable, leaving selection 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 full burden. It usefully warns that archives 'can be very large,' which is real operational context, but says nothing about auth requirements, whether access is read-only, or any rate/size limits on the listing call itself.

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 compact sentences, front-loaded with the core action; the second sentence adds genuinely useful size context rather than 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?

An output schema exists, so return values need not be explained, and the size warning is helpful. However, with zero schema coverage on parameters and no annotations, the definition leaves the lang parameter and access behavior undocumented.

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. It implicitly ties the listing to a domain_code, but the lang parameter is never mentioned and no format/expected values are given for domain_code.

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 (List) and resource (bulk download files, ZIP/CSV archives) scoped to a domain. The purpose is unambiguous, though it does not explicitly differentiate from data-fetching siblings like faostat_get_data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The clause 'contain the full domain dataset' implies why one might want this, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., faostat_get_data or faostat_get_datasize). The agent must infer the selection criterion.

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 behavioral burden. It doesn't say whether the result is paginated, what the 'related' relationship is, or whether documents are filtered by language. For a list endpoint with zero annotation coverage, this is a significant 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?

A single efficient sentence with no waste, front-loading the verb and resource. However, it is arguably too terse for a tool whose parameters are undocumented.

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 no annotations, 0% parameter coverage, and an output schema that doesn't substitute for input clarity, the description should describe the domain_code/language semantics and any filtering behavior. It leaves the agent under-informed about both inputs.

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 both parameters are undocumented. The description mentions 'domain' but doesn't name the domain_code parameter or explain its format, and it ignores the lang parameter entirely, leaving the agent to guess.

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 (List) and resource (related documents) and clarifies what those documents are with examples (methodology papers, questionnaires). It doesn't differentiate from siblings like faostat_get_definitions or faostat_get_metadata, which also return descriptive content.

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 explicit when-to-use guidance or exclusions. The agent must infer this is for fetching documentation linked to a domain, without knowing how it differs from metadata/definition tools.

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 behavioral burden. 'List all' weakly implies a read-only operation, but it discloses nothing about authentication, rate limits, or whether setup/refresh is required first — significant gaps for a tool with zero annotation coverage.

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 short sentence with no filler; the core purpose is front-loaded. It is appropriately sized, though the brevity reflects under-specification as much as economy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter list tool with an output schema, the description still leaves the agent without sibling differentiation or group_code semantics. The output schema covers return values, but usage and parameter context are missing.

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%, yet the description adds almost no parameter detail. It hints that 'group' corresponds to group_code but never states the expected format, valid values, or what the lang parameter controls.

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 all datasets (domains)') and names the scoping container ('within a FAOSTAT group'). However, it offers no differentiation from closely related siblings like faostat_list_groups or faostat_groups_and_domains, leaving the agent to infer the boundary.

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 a listing use case but gives no explicit when-to-use guidance, no prerequisites, and no alternatives or exclusions. Nothing tells the agent when this tool is preferable to faostat_list_groups or faostat_groups_and_domains.

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. It implies a safe, read-only enumeration by calling itself a discovery tool, but it says nothing about whether the list is static, whether lang affects results, or the practical return shape beyond the examples. For a zero-parameter read tool the risk is low, so this is a moderate gap rather than a severe one.

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, no filler, with the action, the concrete contents, and the purpose each stated once and front-loaded. Every 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?

An output schema exists, so return values need not be explained, and the description is adequate for a simple listing call. What is missing is the differentiation from the several sibling list/lookup tools and any mention of the lang parameter, which leaves the definition a bit thin in a crowded namespace.

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

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

There is one parameter (lang, default 'en') with 0% schema description coverage, and the description never mentions it. The agent cannot learn from either source that output language is selectable, let alone what values are accepted.

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 top-level FAOSTAT data groups) with concrete examples (Production, Trade, Food Security), so the agent knows exactly what comes back. It does not differentiate itself from the closely related siblings faostat_list_domains or faostat_groups_and_domains, though 'top-level' hints at the hierarchy level.

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?

'Use this to discover what categories of data are available' gives a clear discovery-oriented context for calling the tool. However, it names no alternatives or conditions, which matters here because faostat_list_domains and faostat_groups_and_domains appear to cover overlapping territory and the agent gets no routing 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the return semantics ('a status message indicating if the API is online'), which is genuine behavioral context, but says nothing about authentication requirements (notable given the sibling faostat_refresh_token), rate limits, or what is returned when the API is down.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the purpose, zero filler. Every clause 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?

For a zero-parameter health-check tool with an output schema that already documents the response shape, the description is nearly sufficient. It omits only operational context such as auth needs or failure behavior, which is a minor gap rather than a blocking one.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to add beyond what the empty schema already conveys.

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

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

States a specific verb+resource: 'Check the FAOSTAT API health status.' No sibling tool in the list performs a health check, so the agent can tell it apart without opening the schema. It stops short of explicitly contrasting with siblings, but none are close enough to require 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?

Usage is only implied — an agent can infer this is a preflight/connectivity check before calling data tools, but the description never says when to call it (e.g., before other calls, on errors) or whether any alternative exists. No exclusions or prerequisites are stated.

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

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

No annotations are provided, so the description carries the full burden. 'Force-refresh' hints that it bypasses a validity check and mutates stored credential state, but the description omits whether existing credentials are required, whether the old token is invalidated for other callers, and whether repeated calls are safe or rate-limited.

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 with zero filler, front-loading the action and its object. Nothing is repeated from the schema or 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?

An output schema exists, so return values need not be described, and a no-argument auth tool needs little explanation. The only shortfall is the absent guidance on when a refresh is warranted, which for an auth utility is genuinely useful 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and the schema is trivially complete.

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 ('force-refresh') and resource ('FAOSTAT API authentication token'). No sibling tool touches authentication, so the agent can immediately distinguish it from the data-retrieval tools in the list.

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 word 'force' implies it is invoked when the cached/current token must be replaced regardless of its apparent validity, which gives implied usage. However, it never states the trigger conditions (e.g., after an auth failure or expiry) or any prerequisites, so the agent must infer when to call 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?

No annotations are present, so the description carries the load, and it discloses real behavioral traits: exact matches are treated as defined while partial matches require confirmation, why 'no_matching_definition' should not be read as proof of non-existence, and that custom constructions need explicit user request plus a non-FAO label. These are non-obvious semantics beyond a bare lookup; only auth/permission behavior is absent.

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 information-dense with essentially no filler, and the core purpose leads. The fragment 'Narrow truncated matches.' is cryptic enough to cost readability and briefly obscures intent, but the overall size is appropriate for what it conveys.

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-shape documentation is not required, and the description still explains how to interpret a notable result state. With three parameters at 0% schema coverage, the only real remaining gap is the undocumented `name`/`lang` inputs; behaviorally the tool is well covered.

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. It does enumerate the meaningful values for `kind` (region, country, indicator, including elements/items), which is genuinely additive since the schema has no enum, but it says nothing about `name` or `lang`, leaving part of the parameter surface undocumented.

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 (resolve/find), resource (FAOSTAT definitions by name), and the distinguishing scope condition (when the domain is unknown). It also names the sibling it is not (faostat_search_codes for query codes), so an agent can route between them without opening the schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Clearly specifies the selecting condition ('when the domain is unknown') and names an alternative tool with the case that selects it (query codes belong to faostat_search_codes). It stops short of an explicit 'when the domain IS known, use X instead' exclusion, so it is strong context rather than complete when/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?

With no annotations, the description carries the full burden and does reasonably well: it discloses substring/case-insensitive matching, the two result-cardinality outcomes (unique = usable, multiple = user must select), the default limit of 25, and truncation-narrowing behavior. It omits what happens on an invalid domain_code/dimension_id or any error/empty-result 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?

Four short sentences, front-loaded with the core purpose and matching rule, then the result-handling contract, then the limit constraint. Every sentence carries actionable information with 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?

An output schema exists, so return format need not be explained, and the search/match behavior is covered. However, for a tool requiring domain_code and dimension_id, the description never explains their relationship or valid values, leaving a real gap in how 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 coverage is 0% and five parameters exist, yet the description only explains 'query' (must be nonblank, which is not in the schema) and repeats the limit default already present in the schema. The two other required parameters, domain_code and dimension_id, are never defined, leaving the agent without the scoping semantics that matter most.

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 (Find) plus resource (domain FILTER codes) and the matching method (case-insensitive substring), so the operation is unambiguous. It does not name the closest sibling (faostat_get_codes) or faostat_resolve_name, so the distinction is only implied by 'before querying unknown codes'.

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?

'Use before querying unknown codes' gives a clear triggering condition, and the unique-vs-multiple match rule tells the agent what to do with the result. It stops short of explicitly naming the alternative tool to use when codes are already known.

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 behavioral burden and discloses important details: credentials are validated and persisted, saved to the system keychain when available, and fall back to a config file with mode 600. It does not specify failure behavior, overwrite semantics, or whether the password is stored in plaintext.

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, front-loaded with the core action and followed by storage details. Every clause earns its place with no redundancy.

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?

Given the output schema exists, return values need not be explained. The description covers purpose, storage locations, and username semantics, but omits when to use this versus refresh_token and what happens on validation failure.

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. It clarifies that 'username is the account email', adding useful meaning for one parameter, but provides no added semantics for 'password' beyond the obvious.

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 specific verbs 'Validate and persist' and names the resource 'FAOSTAT credentials', clearly distinguishing this setup tool from all data-retrieval siblings. The scope 'for automatic authentication across sessions' further clarifies its unique role.

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 phrase 'for automatic authentication across sessions', suggesting it is a one-time setup for subsequent calls. However, it does not explicitly state when to run it versus alternatives like faostat_refresh_token, nor does it mention prerequisites or conditions.

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