ILO Labour Statistics (ILOSTAT)

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

The description adds meaningful behavior beyond the annotations: it is read-only and idempotent, performs a live GET against the public source when needed, and returns an error for unknown ids. It also discloses the return shape. This complements, rather than contradicts, the annotations.

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 well-structured: the core function and return shape come first, followed by context and behavior. It is concise enough that every sentence adds useful information, and it avoids repeating the schema or annotations.

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

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

For a simple one-parameter tool with an output schema and safety annotations, the description covers everything needed: source of ids, return format, error behavior, read-only nature, and relationship to sibling tools. Nothing critical is missing for correct 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 coverage is 100%, so the baseline is 3. The description adds extra semantic value by specifying that the id must come from `search`, that only such ids are valid, and that unknown ids produce errors—details not present in the schema's parameter description.

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 a specific action ('Returns the full document') and names the resource (document identified by an id from `search`). It also distinguishes itself from siblings by explicitly separating the `ilo_*` data-query tools from this document-fetch contract.

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 states when to use the tool: after obtaining an id from `search`, and only ids from `search` are valid. It also provides an exclusion by reserving `ilo_*` tools for data queries, so an agent knows this is not for statistical data retrieval.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It adds valuable behavioral detail: no aggregation, no transformation, raw values only, unfiltered dimensions return all categories, and a 30-area cap with batching/pagination guidance. No contradictions with annotations.

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 sentences deliver purpose, filter examples, constraints, batching strategy, raw-data semantics, and sibling routing with no filler. The core scope is front-loaded, and 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?

Combined with a fully documented input schema and an output schema, the description covers intended use, required parameters, operational limits, batching strategy, raw-data behavior, and sibling differentiation. There is no critical missing information for an agent to select and call this 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by giving concrete filter/period examples, enforcing REF_AREA as required, explaining the 30-area limit, and clarifying what happens when dimensions are unfiltered. It leaves last_n_observations and provenance_mode to the schema, but those are already well documented there.

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

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

The description opens with a specific action and object: retrieving statistical observations from one ILOSTAT dataflow, filtered by dimension codes and period. It explicitly scopes behavior as raw ILOSTAT data and distinguishes itself from ilo_search_indicators, making its purpose 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?

The description gives clear operational guidance: REF_AREA is required, max 30 areas per call, batch for broad panels, paginate by period, and unfiltered dimensions return all categories. It names ilo_search_indicators as the alternative for indicator search, though it does not explicitly route to ilo_get_indicator_metadata or ilo_list_dimension_values.

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

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

Annotations already cover the safe, read-only, idempotent nature of the tool. The description adds meaningful behavioral context by disclosing exactly what is returned (structure, not values or codes) and what the vintage represents. This goes beyond the annotations without contradicting them.

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 three sentences with no filler. The core definition is front-loaded, followed by usage timing and explicit exclusions. 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?

For a metadata-retrieval tool with two well-documented parameters, a rich output schema, and safety annotations, the description fully covers what the agent needs: what is returned, what is intentionally excluded, and how it relates to sibling tools. No critical guidance 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 schema already explains both parameters. The description reinforces that 'dataflow' identifies a specific ILOSTAT dataflow and that the tool is a prerequisite for knowing filters, but it does not add new parameter-level details beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource: it returns the structure of one ILOSTAT dataflow, including dimensions, codelists, time dimension, default selection, and vintage. It also explicitly differentiates itself from siblings by stating it does not return statistical values and does not list codes, which are handled by other tools.

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

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

The description gives clear usage direction: 'Use before ilo_get_data to know which filters exist.' It also names the alternative for code listing: 'use ilo_list_dimension_values,' and states what the tool does not do, preventing misuse. This is explicit when-and-when-not guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond those: codelists are shared across dataflows, the tool does not indicate data availability, and it excludes the time dimension. These are non-obvious behaviors an agent needs to know before calling the 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?

The description is dense but every sentence earns its place: definition and examples, routing to `search`, intended use, and explicit limitations. The core purpose is front-loaded, and the caveats are grouped clearly at the end. 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 six parameters, a rich input schema, and an output schema, the description covers the necessary operational context: what the codes represent, how to use search vs. paging, cross-dataflow validity, limitations regarding data availability, and time-dimension handling. Nothing essential 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 coverage is 100%, so the baseline is 3. The description adds meaningful extra context for the `search` parameter ('resolve a name to a code' with a 'Brazil' example) and clarifies the relationship between `dataflow` and `dimension` by noting codelists are shared across dataflows. This goes beyond the schema's per-parameter descriptions without duplicating them.

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

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

The description opens with a specific verb+resource: 'Valid codes (id + label) of one dimension of an ILOSTAT dataflow,' and reinforces it with concrete examples (REF_AREA, SEX, AGE). It also distinguishes itself from siblings by stating what it does not do ('does not return statistical values') and by pointing to the `search` tool for name-to-code 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 description explicitly says when to use this tool ('Use to build correct ilo_get_data filters') and when not to use it ('does not say which codes actually have data for a given dataflow', 'not applicable to the time dimension'). It names the alternative (`search`) and explains the condition that selects it, so an agent gets clear 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?

The description reveals important behavioral details beyond the readOnly/idempotent annotations: AND matching, case-insensitivity, ranking by ILO relevance weight rather than match count, id suffix conventions (_RT, _NB), and the distinction between ILO modelled estimates and reported national data.

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 every sentence contributes: core purpose, query tips, result interpretation, usage with siblings, and exclusions. It front-loads the main action and appends only relevant operational detail.

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 a rich output schema present, the description does what is needed: it explains what the search returns, how results are ordered, how to decode ids, and how to route follow-up calls to sibling tools. Nothing essential is missing for correct 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 coverage is 100%, so the baseline applies. The description adds interpretive guidance about how the query behaves (AND, case-insensitive, relevance ranking) and how to read result ids, but it does not significantly extend the meaning of the individual parameters beyond the schema descriptions.

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, 'Search', and a concrete resource, 'the ILOSTAT catalogue of ~1,200 indicator dataflows by keywords in the name or id'. It also explicitly distinguishes itself from its siblings by saying it does not return statistical values, does not search dimension codes, and does not cover non-ILO 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?

It gives actionable guidance: start with 2–3 English words, drop terms if 0 results, and use the returned dataflow ids with ilo_get_data / ilo_get_indicator_metadata. It also names alternatives for what this tool does not do, such as ilo_list_dimension_values for dimension codes.

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

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

The description adds meaningful behavioral context beyond annotations: read-only and idempotent, backed by an in-memory cache of the public catalog, empty list means no match, and results are relevance-ordered. It also clarifies that this is a catalog index rather than a data-returning endpoint, which is essential for correct agent expectations.

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?

Every sentence carries useful information: purpose, output format, ordering, match behavior, tool routing, language/query semantics, and behavioral guarantees. It is detailed yet tightly organized, front-loading the core capability and then providing the operational context an agent needs.

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 description fully covers what an agent needs to correctly select and invoke this tool: what it searches, what it returns, how results are ordered, how to consume results via fetch, when to prefer sibling tools, and how the query parameter behaves. Nothing essential 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 coverage is already 100%, and the description goes further by explaining query semantics: 'natural language or keywords, Portuguese or English; accents and case are ignored.' This adds practical information that the schema alone does not fully convey about acceptable input formats.

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

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

The description opens with a precise verb and resource: 'Searches the ILOSTAT labour statistics catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance.' It clearly distinguishes its role from the sibling fetch tool (which reads documents by id) and the ilo_* data tools, so an agent can tell them apart immediately.

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 guidance is explicit: 'For direct questions and for data (values, series, rankings) prefer the ilo_* tools... this is a catalog index, not a data query.' It also states when to use fetch by passing the returned id, and mentions the Deep Research contract context. This is strong routing guidance with no ambiguity.

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