UNESCO UIS — Education, Science & Culture Statistics (provenance-first)

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

Discloses that the tool returns raw records only with no aggregation/transformation, that broad queries are rejected, and that ILO data is not included. These behaviors go beyond the read-only/idempotent annotations and help an agent set 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?

Four short sentences, each with distinct value: purpose/filter, footnote toggle, raw-only transformation stance, and rejection/narrowing advice. No filler or repetition of schema.

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 and annotations provide safety profile, the description covers what the tool returns, limits, error behavior (broad query rejection), and relationship to ILOSTAT. This is sufficient for an agent to invoke 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 covers all six params at 100%, and the description adds useful cross-references (indicator codes from uis_search_indicators, geo codes from uis_list_geo_units, max 25 indicators) and explains include_footnotes purpose. Not as deep as a full param walkthrough, but schema already 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?

The description states a specific action: retrieve statistical records from the UNESCO Institute for Statistics Data API, filtered by indicator codes, geo unit codes, and year range. It clearly differentiates from sibling tools by referencing them as code sources rather than data retrieval alternatives.

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 instructs how to use: source codes from uis_search_indicators and uis_list_geo_units; use include_footnotes for source notes; if query too broad, narrow by geo unit or years; ILO stats should go to ILOSTAT sibling. This gives clear when-to-use and exclusion 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 and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it says the tool does not return statistical values, codes apply only to uis_get_data, and lists the dataset size (462 units) and categories. It does not discuss pagination or edge cases, but the schema covers those.

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 two sentences, front-loaded with the core purpose, and every clause adds distinct information. It avoids redundancy and is highly scannable.

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, read-only, and has an output schema, so the description need not cover return structure. It explains the tool's role in the larger workflow (providing codes for uis_get_data), its filtering options, and its narrow applicability. Given the annotations and schema, this is fully complete for reliable agent use.

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 baseline is 3. The description adds meaning beyond schema by explaining that search can be a name containing string or an exact code (with example 'BRA'), and clarifies NATIONAL vs REGIONAL types. It frames the parameters as 'filter by name/code and type', giving a cohesive mental model.

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's function: 'Valid geographic codes for uis_get_data' and explicitly enumerates what it returns (462 geo units, countries and regional aggregates). It also distinguishes itself from siblings by noting it 'Does not return statistical values' and applies only to uis_get_data, not other statistical servers.

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 strongly implies usage: it is a prerequisite for uis_get_data, providing valid codes. It clarifies that it does not return statistical values, which excludes a class of alternatives. However, it stops short of explicitly stating 'use this before uis_get_data' or naming when not to use it, leaving the workflow slightly implicit.

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 establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context by stating it searches the catalogue only, does not return statistical values, and returns availability metadata such as years and record counts. 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 main purpose is front-loaded, the return value and downstream consumer (uis_get_data) are made explicit, and the key exclusions (no statistical values, ILO data elsewhere) are stated efficiently. 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 5-parameter search tool with a rich output schema and read-only annotations, this description is complete: it covers scope, themes, match behavior, output nature, and routing to related tools. The output schema supplies return-value details, so the description does not need to enumerate fields.

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 all parameters. The description adds only modest semantic context by mentioning keyword matching against name/code and optional theme filtering, which aligns with the query and theme parameters but does not substantially extend the schema's own 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 names a specific verb ('Search'), a concrete resource ('UNESCO Institute for Statistics catalogue of ~5,000 indicators'), and the supported domains and match behavior (keywords in name or code, optional theme filter). It also distinguishes itself from siblings by clarifying that it returns catalogue metadata and indicator codes, not statistical 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?

The description explicitly routes the agent: use this tool for catalogue searches and indicator-code lookup, use uis_get_data for statistical values, and use the ILOSTAT MCP server for ILO labour statistics. The when-not-to-use guidance is unambiguous, and the intended downstream use with uis_get_data is stated directly.

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