ilostat-mcp-server

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

Annotations already cover read-only, idempotent, open-world behavior, yet the description goes well beyond them: areas lacking values are listed separately with a reason, mixed periods and mixed bases are flagged rather than hidden, and each value carries period, source, status, and basis (reported/modelled_estimate/projection). That is exactly the kind of output-shape and edge-case disclosure annotations cannot provide.

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?

Content is front-loaded and every clause carries information, but the opening sentence is a long run-on enumerating period, change, rank, and basis in one breath. Given the tool's 11-parameter complexity the length is defensible, though it could be split for scanability.

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 an 11-parameter, single-required-param tool with an output schema, the description covers selection modes, defaults, aggregate restrictions, null handling, and mixed-period/base flagging. Nothing an agent needs to invoke 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 the schema already documents all 11 parameters in detail (defaults, enums, patterns, limits). The description adds framing about the slice concept (sex plus breakdown codes defaulting to totals) but little parameter syntax beyond what the schema carries, so the baseline 3 applies.

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 (compare) and resource (reference areas on one ILOSTAT dataset and one slice), and spells out the scope: values at a common or latest non-projected period, optional change over N years, and a rank. An agent can distinguish this from ilostat_query_indicator (single indicator extraction) or ilostat_get_country_profile without opening the 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 clearly establishes the operating context: select areas by code list, by group, or both, and X-coded aggregates require a dataset with aggregates. That is strong contextual guidance, but it never explicitly names a sibling tool as the alternative or states when NOT to use this in favor of ilostat_query_indicator or ilostat_list_reference.

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 and idempotentHint, so safety is covered; the description goes further by disclosing what the payload contains (attribution, creation and expiry times, coverage, basis counts) and a deployment-dependent quirk: on a shared-canvas deployment, omission-based listing is off and only an exact name works. That is real behavioral context annotations could not convey.

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 usage constraint (read the schema before writing SQL) is front-loaded in the final sentence and the operational rule about name versus listing is clear. The first sentence is a long enumerated field list that is dense but largely informative rather than filler.

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 one-optional-parameter read tool with annotations and an output schema, the description is complete: it covers scope, argument behavior, deployment caveat, and the handoff to ilostat_dataframe_query. It spends words enumerating return fields that the output schema already defines, which is redundant rather than 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% for the single name parameter, so the pattern, case-insensitivity, and omission semantics are already documented in the schema. The description restates them ('Pass name for one dataframe. Without it, every staged dataframe is listed') without adding format or syntax beyond the schema, so the baseline of 3 applies.

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 (Describe) and a precisely scoped resource (df_<id> dataframes staged by ilostat_query_indicator / ilostat_compare_geographies or registered via ilostat_dataframe_query), and enumerates what is returned. It names the producing siblings explicitly, so an agent can distinguish it from ilostat_dataframe_query or ilostat_describe_indicator 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?

Gives explicit when-to-use routing: 'Read the schema here before writing SQL for ilostat_dataframe_query.' It also states the condition that selects the name argument (one dataframe) versus omitting it (list everything), and flags the shared-canvas exception where listing is refused.

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 readOnlyHint/openWorldHint/idempotentHint, but the description adds real operational detail beyond them: the exact rejected statement classes (writes, DDL, DROP, COPY, PRAGMA, ATTACH, file-reading table functions), the denied system catalogs, the overlapping breakdown-version trap (AGE_YTHADULT_*/AGE_AGGREGATE_*/AGE_10YRBANDS_*), and that register_as creates a fresh TTL. This is exactly the behavioral context an agent needs to write a valid query.

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?

Information is front-loaded: purpose first, then prerequisite, then the rejection list, then the semantic pitfall, then the optional output mode. Every sentence carries distinct operational value with no filler.

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, the description need not explain return values, and it covers what it must: prerequisites, allowed statement surface, and the analysis trap that would silently corrupt sums. Nothing needed to invoke the tool 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 each of the four parameters (sql, preview, row_limit, register_as) is already documented in detail, including the BIGINT-as-string caveat and the 1,000,000-row register limit. The description's mention of register_as storing with a fresh TTL largely repeats the schema, so it adds little beyond the baseline.

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: 'Run a single-statement SELECT against the df_<id> dataframes.' It goes further by naming which sibling tools produce those dataframes (ilostat_query_indicator, ilostat_compare_geographies, register_as) and which sibling inspects them (ilostat_dataframe_describe), so the agent can separate this from ilostat_query_indicator without opening any 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 clearly states the precondition — data must already be staged by ilostat_query_indicator or ilostat_compare_geographies — and directs the agent to run ilostat_dataframe_describe first because 'its column schema is what the SQL has to match.' That is strong contextual routing, though it never explicitly says when to prefer querying an indicator directly via ilostat_query_indicator instead.

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 by structured data. The description adds real behavioral context beyond that: an unknown code returns found: false with guidance, and a bare indicator code describes every frequency variant. It does not discuss rate limits or the output shape in depth, hence 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?

The content is dense but front-loaded: the purpose verb and the list of what is explained lead, and the accepted-input and error behavior follow. Every clause maps to a real aspect of the response, though the long enumerations make it heavier than a minimal definition.

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 values need not be explained, yet the description still summarizes what the agent will get (definitions, units, codes, aggregates, classification), plus the input forms and the not-found behavior. For a single-parameter, well-schema'd read tool this is complete.

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, but the description adds meaning beyond the schema by clarifying that a bare indicator code expands to every frequency (schema only calls it 'a bare indicator code'). It also reinforces the accepted forms and lists a concrete example, though it largely parallels the schema's own guidance.

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 precise verb+resource (explain/describe one ILOSTAT dataset) and enumerates exactly what the explanation contains: definition, unit/multiplier, frequency variants, breakdown codes, coverage, aggregates, and observation classification. It explicitly positions itself against the comparison/query siblings with 'before comparing numbers', so an agent can place it without opening the 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?

'Explain one ILOSTAT dataset before comparing numbers' gives a clear when-to-use signal that routes the agent away from ilostat_compare_geographies and ilostat_query_indicator. It does not explicitly name those alternatives or state exclusions, so it stops short of the top band.

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 open-world behaviour, so the bar is lower. The description nonetheless adds real behavioural context beyond them: each indicator shows latest reported value plus separately the latest non-projection ILO modelled estimate, without imputing missing reported values, and aggregates carry only modelled values. That is substantive disclosure of data-provenance semantics.

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 long sentences carry dense but relevant content, and the indicator inventory plus scope are front-loaded. The first sentence's indicator list is heavy but every element is load-bearing for a profile tool, so there is little waste.

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 full schema coverage, the description needn't explain return values, and it covers the non-obvious behavioural points an agent needs: reported vs modelled values, missing-value handling, and aggregate-only modelling. It stops short of routing guidance among the seven sibling tools, which is the only material gap.

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 both parameters are already documented, and the baseline of 3 applies. The description reinforces ref_area semantics by naming ISO3 and X-coded aggregate forms with examples and noting that aggregates only have modelled values, but says nothing about the sex parameter beyond what the schema provides.

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 gives a specific verb ('Build a headline labour-market profile') and resource (one reference area), and enumerates the nine indicators returned, so the agent knows exactly what the tool produces. It is clearly a bundled multi-indicator snapshot, which implicitly separates it from single-indicator query tools, but it never names a sibling to make the contrast explicit.

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 is implied by scope: 'one reference area' with country or X-coded aggregate accepted, which tells the agent the input shape but not when to prefer this over ilostat_query_indicator or ilostat_compare_geographies. There are no explicit when-to-use or when-not conditions and no named alternatives.

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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuine behavior beyond that: pagination via cursor, that missing codes surface in not_found, that area_group exact lookups expand to member countries, and that matching is case/accents/punctuation-insensitive. It omits nothing critical and adds real context on a lower bar.

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?

Purpose and the enumeration of topics are front-loaded, and the second sentence's routing to ilostat_describe_indicator is high-value. The long comma-separated topic list overlaps with the schema enum, which is mild redundancy, but every clause is informative and no sentence is filler.

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 7-parameter schema, full coverage descriptions, and an output schema, the description need not explain return values. It covers topics, filtering, exact-code lookup, pagination, and sibling routing, leaving only minor gaps such as how next_cursor is returned.

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 nonetheless adds meaning beyond the schema: the X01 aggregate convention for area_group, the ILO_GEO_ form tolerance, and which topics accept which lookup codes — useful disambiguation that the enum alone does not convey.

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 ('Decode ILOSTAT's code vocabulary') and enumerates exactly what gets listed (ref areas, groups, databases, subjects, sexes, breakdown codes, sources, flags, notes, frequencies). It explicitly distinguishes itself from the sibling ilostat_describe_indicator by contrasting ILOSTAT-wide vocabularies with the codes one dataset uses.

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?

Names the two operating modes ('Filter by text or look up exact codes') and flags that long topics paginate with a cursor, plus the alternative tool for dataset-specific codes. It stops short of explicit when-not-to-use conditions (e.g., when a numeric query is the right call instead), so it falls just short of a 5.

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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses row content (source, observation status, decoded notes, reported/modelled_estimate/projection basis), filter echo semantics, code pre-validation against ILOSTAT dictionaries, dataframe staging for oversized results, and two distinct refusal conditions (unfiltered over ceiling, filtered still over ceiling). That is unusually rich behavioral context.

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 the core action and scope, and each subsequent sentence carries distinct information (row shape, validation, staging, refusals). It is dense as a single paragraph, but virtually no sentence is filler.

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 values need not be spelled out, yet the description still explains the meaningful row attributes and filter echo. Combined with refusal behavior and dataframe hand-off, an agent has everything needed to call this correctly in a complex, 12-parameter, multi-dataset query tool.

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 itself documents all 12 parameters in detail, including the sources/source_selection interaction and normalization rules. The description's summary of filter dimensions and the 'best-source default' echo adds reinforcement but no new parameter syntax beyond what the schema provides, so baseline 3 applies.

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 ('Fetch observations for up to 3 ILOSTAT datasets') with explicit scope limits and the filter dimensions it accepts. It also distinguishes itself from siblings by naming ilostat_list_reference and ilostat_describe_indicator as code-resolution tools and the dataframe tools as the path for large results.

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?

Clearly routes the agent: consult ilostat_list_reference / ilostat_describe_indicator for valid codes before calling, and use ilostat_dataframe_describe / ilostat_dataframe_query when a result is staged. It does not explicitly contrast this tool with ilostat_compare_geographies or ilostat_get_country_profile, so it stops short of full 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 readOnly/idempotent/closed-world, and the description adds substantive behavioral detail beyond them: matching is word/prefix based across label, subject, database, breakdown names, code, and definition; British and American spellings match alike; facet counts reflect all applied filters. These are non-obvious search semantics the agent could not infer from annotations or schema.

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 the purpose and return shape, then the workflow, then matching semantics. The first sentence is long and packs several clauses, but every sentence carries information with no filler or repetition.

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 an 8-parameter, zero-required search tool with an output schema, the description covers the non-obvious behavior: return shape, matching rules, spelling tolerance, filter-as-query fallback, and downstream tool routing. Nothing an agent needs to invoke 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it clarifies the AND semantics of multiple terms, prefix matching, the frequency-to-datasets relationship ('an indicator with none left drops out'), and that filters can substitute for a query. This is value beyond the parameter 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?

States a specific verb+resource ('Search ILOSTAT's catalog of labour-statistics indicators') and immediately describes what a hit contains. It distinguishes itself from siblings by naming ilostat_describe_indicator, ilostat_query_indicator, and ilostat_compare_geographies as the downstream steps, so an agent knows this is the entry-point search, not a query tool.

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 workflow guidance: pass a dataset ID to describe_indicator, then to query_indicator or compare_geographies for values, and 'Omit to browse by filters'. It does not name exclusions (e.g. use ilostat_list_reference for code discovery) beyond the schema hints, so it stops short of full when/when-not coverage.

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