ILO Labour Statistics (ILOSTAT)

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

Annotations already mark the tool as read-only, but the description adds substantial behavioral detail beyond that: it returns raw data only and 'does not aggregate, convert or otherwise transform values', unfiltered dimensions return all categories, and calls are scoped to one dataflow with a hard area limit. These are meaningful constraints not visible from annotations or schema alone.

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 dense sentences with no filler. The core action is front-loaded, followed by constraints, return behavior, and the exclusion of sibling functionality. Every sentence contributes actionable 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?

Given the 6-parameter schema, nested filter object, output schema, and rich annotations, the description covers the remaining necessary context: required fields, area limits, batching, period semantics, raw-data behavior, and the sibling tool for indicator search. Nothing needed for correct invocation is 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 100%, so the baseline is 3. The description adds value beyond the schema with a concrete filter example, the REF_AREA requirement, the 30-area limit, and period format examples ('2015'/'2024'), which clarify how parameters should be used together.

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

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

The description opens with 'Statistical observations from one ILOSTAT dataflow', giving a specific verb, resource, and scope. It also defines what the tool is not by explicitly stating it 'does not search indicators' and offers the sibling tool for that purpose, making differentiation clear.

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 explicit operational guidance: REF_AREA is required, maximum 30 areas per call, and for broad panels it instructs to 'split areas into batches and/or paginate by period'. It also names the correct alternative for indicator search ('use ilo_search_indicators'), so an agent knows when not to use this tool.

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

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

Annotations already cover read-only, open-world, and idempotent behavior. The description adds useful negative scope beyond the annotations: it does not return statistical values and does not enumerate codes. It also discloses the data vintage as part of the return, which sets expectations for what the output contains.

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

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

Three sentences, no filler. The core output scope is front-loaded, followed by when to use it and what it does not do. Every sentence earns its place and directly aids tool selection.

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, has only one required parameter, full schema coverage, rich annotations, and an output schema. The description covers the output's composition, its relationship to sibling tools, and its limitations, so an agent has everything needed 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 100%, so the schema already documents both parameters well. The description adds context for dataflow ('use before ilo_get_data') but does not deepen the meaning of provenance_mode beyond what the enum and schema text already provide. This is an adequate baseline rather than a standout contribution.

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 resource (one ILOSTAT dataflow) and enumerates exactly what is returned: dimensions, codelists, time dimension, default selection, and vintage. It also explicitly contrasts itself with related tools by stating it does not return statistical values or code lists, making its purpose unambiguous.

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

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

The description gives explicit usage context: 'Use before ilo_get_data to know which filters exist.' It also provides a clear exclusion and alternative: do not use this to list codes; use ilo_list_dimension_values instead. This fully routes an agent to the right tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: codes are shared across dataflows, the tool does not say which codes actually have data, and it does not apply to the time dimension. This fully discloses behavioral boundaries.

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 dense but well organized: the primary purpose is front-loaded, examples clarify the semantics, and exclusions are stated at the end. Every sentence adds distinct value and there is no filler or repetition of schema details.

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 complex domain, the presence of a full input schema and output schema, and rich annotations, the description covers all essential operational aspects: what is returned, how to page, when to use search, what the codes mean across dataflows, and what the tool cannot do. An agent has enough context to call this tool correctly without additional investigation.

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

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

Schema description coverage is 100%, which meets the baseline of 3, but the description adds useful parameter context: the `search` parameter is described as the way to resolve a name to a code rather than paging, and the `dimension` parameter is illustrated with concrete valid dimension ids such as REF_AREA and SEX. This enriches the schema-level descriptions without redundancy.

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

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

The description states a specific verb and resource: 'List valid codes (id + label) of one dimension of an ILOSTAT dataflow' and gives concrete examples (REF_AREA, SEX, AGE). It clearly separates this tool from siblings by explaining what it does not do, such as returning statistical values or indicating data availability.

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

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

It explicitly says to use `search` to resolve a name to a code instead of paging through codes, to use this tool to build correct ilo_get_data filters, and to filter time via start_period/end_period instead. It also states codelists are shared across dataflows, which tells the agent when a code found here is reusable. Clear when-to-use and when-not-to-use guidance is present.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. Description adds ranking behavior (ILO relevance weight) and id interpretation (suffix _RT/_NB, modelled vs reported), which is valuable. However, it does not disclose potential rate limits or pagination behavior beyond offset, but with strong annotations the bar is lowered; score 3 is appropriate.

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 paragraph, moderately concise but packed with useful operational details. It front-loads the primary purpose and provides actionable tidbits (id interpretations, modelled vs reported). Slightly long but every clause adds value, so 4 is justified.

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 that an output schema exists and annotations are thorough, the description covers edge cases: no-data-result handling, id naming conventions, and returns IDs for chaining. It also clarifies limitations (does not return values, not for dimension codes). This is complete for the tool's complexity and integrations.

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 has 100% coverage for all 4 parameters, providing detailed descriptions for query (AND matching), limit, offset, and provenance_mode enum values. The description adds insight into how the query terms are interpreted (case-insensitive, AND) and provenance_mode meaning, but mostly reinforces schema. With full schema coverage, baseline 3 is fair.

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

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

The description clearly states the tool searches the ILOSTAT catalogue by keywords, with a specific resource ('indicator dataflows') and scope (~1,200). It distinguishes from siblings by explicitly noting what it does not do: return statistical values, search dimension codes, or cover non-ILO sources, which differentiates it from ilo_get_data and ilo_list_dimension_values.

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 concrete usage guidance: start with 2-3 English words, drop terms if 0 results (AND logic), and identifies related tools (ilo_get_data, ilo_get_indicator_metadata, ilo_list_dimension_values) for specific use cases. It even explains when not to use this tool (for dimension codes or non-ILO sources).

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