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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds real operational context beyond them: a 30-area cap per call, batching/pagination strategies, and the guarantee that values are never aggregated or transformed. It stops short of describing rate limits or failure modes beyond the schema's timeout note.

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 front-loaded with the core purpose, then filters, then constraints, then exclusions — a logical progression with no filler. The sentences are long and dense, but each carries distinct 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?

With an output schema present, return values need not be explained, and the description covers everything else an agent needs: required filtering, size limits, period vs. last-N options, and scope exclusions. Nothing material 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, but the description goes further by showing a worked filter example that illustrates the string-vs-array value shapes and by clarifying the period parameters' format. This adds genuine meaning beyond the schema field 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 and resource — returning statistical observations from one ILOSTAT dataflow — and scopes it by dimension codes and period. It also explicitly distinguishes itself from the sibling ilo_search_indicators, so an agent can route between them without opening either 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?

It gives concrete usage conditions (filter by dimension codes and period, unfiltered dimensions return everything) and names an alternative for a different job (ilo_search_indicators for indicator lookup). It also advises batching/pagination for broad panels, though it does not discuss the other siblings (fetch, ilo_get_indicator_metadata).

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds substantive context beyond them: it defines the shape of the response and explicitly states two negative behaviors (no statistical values, no code enumeration), which prevents misuse. It does not mention pagination or response size, but for a metadata lookup that is minor.

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, each load-bearing: the return structure first, the usage ordering second, the exclusions and alternative third. No filler and the most important content (what it returns and when to call it) is front-loaded.

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 detail is not the description's burden, and it still summarizes the payload structure. Combined with the explicit sibling routing, an agent has everything needed to select and invoke 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 description coverage is 100% and both parameters are documented there, including the dataflow id source and the provenance_mode enum values. The description adds no parameter-level detail, so the baseline 3 applies — the schema does the heavy lifting.

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 ('Structure of one ILOSTAT dataflow') and enumerates exactly what is returned: dimensions in SDMX key order, codelists, time dimension, default selection, and data vintage. It explicitly distinguishes itself from ilo_get_data (values) and ilo_list_dimension_values (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?

Gives explicit sequencing guidance ('Use before ilo_get_data to know which filters exist') and two clear exclusions with the correct alternative named for each ('does not return statistical values', 'does not list the codes themselves (use ilo_list_dimension_values)'). Nothing is left 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral scope beyond them: codelists are shared across dataflows, results exclude statistical values, and codes do not indicate which have data. It stops short of describing pagination defaults or the raw return shape, so a 4 rather than 5.

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

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

Front-loaded with purpose, then usage, then exclusions, in a compact block with no filler sentences. It is dense and runs long in a single paragraph, which slightly reduces scanability, but each 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?

With an output schema present and annotations covering safety, the description only needed to supply scope and exclusions — which it does: shared codelists, absence of data-availability info, and the time-dimension carve-out. Nothing an agent needs to call it correctly 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 limit/offset/search/dataflow/dimension/provenance_mode are already documented in the schema; baseline 3 applies. The description adds the intent of `search` (name-to-code resolution) and implies paging, but no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Valid codes (id + label) of one dimension of an ILOSTAT dataflow') and grounds it with concrete examples (REF_AREA ISO 3166-1 alpha-3, X-codes, SEX_T/SEX_M/SEX_F, AGE). An agent can distinguish this from ilo_get_data and search without opening a 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 `search` to resolve a name to a code instead of paging, and use this to build ilo_get_data filters. It also names an exclusion ('not applicable to the time dimension — filter it via start_period/end_period in ilo_get_data'), which is exactly the when-not guidance the dimension calls for.

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?

While annotations already establish readOnly/idempotent/non-destructive behavior, the description goes well beyond them by disclosing AND semantics, case-insensitivity, synonym resolution, relevance ranking, id-shape conventions (_RT, _NB, 2-token modelled estimates), and vocabulary_notes behavior. No contradiction with annotations exists.

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 long but every sentence earns its place: purpose, query strategy, vocabulary behavior, ranking, id interpretation, and exclusions are all covered without redundancy. The core purpose is front-loaded before the detailed guidance.

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 output schema exists and the tool is a read-only search, the description covers everything an agent needs: what it searches, how to construct queries, how results are ordered, how to interpret ids, and which sibling tools to use for adjacent tasks. Nothing important 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, but the description adds meaning beyond the schema: it explains query semantics with examples, vocabulary mapping, ranking behavior, and how to interpret result ids. It doesn't add much about limit/offset/provenance_mode, but those are already fully described in the schema.

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

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

The description opens with a specific verb and resource: 'Search the ILOSTAT catalogue of ~1,200 indicator dataflows by keywords in the name or id.' It also differentiates itself from siblings by explicitly stating what it does not do: no statistical values, no dimension-code search, no 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?

Usage guidance is explicit and actionable: start with 2–3 English words, drop terms on zero results, and use alternatives for other needs (ilo_get_data for values, ilo_list_dimension_values for countries). It also names sibling tools directly, so an agent knows exactly when to choose 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?

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.