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 indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable boundary information: it searches the catalogue only, does not return statistical values, and returns indicator codes plus data availability (years, record count). These are behavioral traits not present in the annotations, giving the agent an accurate model of what happens.

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, each earning its place: the first explains what is searched and how, the second describes the return value, and the third clarifies boundaries and points to alternatives. It is front-loaded with the core purpose and avoids redundancy or fluff.

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 provide the safety profile, the description is highly complete. It covers the tool's scope, its relationship to uis_get_data, and the nature of its return data. No important aspect such as pagination or default limit needs to be in the description because the schema already covers it.

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 all five parameters already have detailed descriptions in the schema. The tool description restates that keywords match against name or code and that results can be filtered by theme, but it does not add new semantic information beyond the schema. This meets the baseline for high schema 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?

The description clearly states the tool searches the UNESCO UIS catalogue of ~5,000 indicators, specifying the subject areas (education, science/R&D, culture and communication) and the matching criteria (keywords in name or code). It explicitly distinguishes itself from siblings by noting it returns indicator codes for use with uis_get_data and that it does not return statistical values, so there is no ambiguity about its 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?

The description gives explicit usage guidance: 'Returns indicator codes to use with uis_get_data' and 'it does not return statistical values (use uis_get_data)' clearly state when to use this tool vs the sibling. It also notes that ILO labour statistics are in the sibling ILOSTAT MCP server, providing an alternative for a specific subset of queries.

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