ilostat-mcp-server

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

Annotations only declare readOnly/openWorld/idempotent, but the description adds real behavioral context: refusal conditions (sex on a dataset without a breakdown, classif1 where the breakdown lacks a total), how areas without a value are reported, and that mixed periods and mixed bases are flagged rather than hidden. It stops short of covering auth, rate limits, or pagination behavior.

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 purpose is front-loaded and nearly every clause carries information (modes, change semantics, missing-area handling, selection methods). However, the first sentence runs to roughly seventy words as a single breath, making it dense to parse; splitting the response-behavior detail into its own sentence would improve structure.

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 tool with one required field, an output schema, and safety annotations, the description covers the mode selection, area-selection paths, refusal cases, and edge-case reporting. Nothing an agent needs to call it correctly is missing, and return-value detail is already handled by the output schema.

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 already 100%, so the schema carries most parameter meaning (defaults, patterns, enums). The description nonetheless adds a governing constraint not present in the schema — that X-coded aggregates require a dataset with aggregates — plus the totals-defaulting rule, which is genuine added semantics beyond the field docs.

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+resource+scope: 'Compare reference areas on one ILOSTAT dataset and one slice.' It specifies the outputs (per-area value at a common or latest period, optional change over N years, and a rank), which makes it unmistakably distinct from single-series siblings like ilostat_query_indicator without needing to name them.

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 explains the two operating modes (a common period vs. each area's latest non-projected period) and the three ways to select areas (code list, group, or both), and it routes the agent to ilostat_describe_indicator and ilostat_list_reference for code discovery. It never states when not to use this tool or how it compares to ilostat_query_indicator, so it stops short of full alternative routing.

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, so the safety profile is covered; the description goes further by disclosing that values stay in the published scale the multiplier names, that entries carry creation and expiry times, and that shared-canvas deployments refuse listing. That is genuine behavioral context beyond the structured hints, though it stops short of saying what happens to expired dataframes.

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 verb and resource, and every clause after it carries information. It is dense, and the long enumeration of returned fields partly duplicates the output schema, which is the only mild redundancy.

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 no explanation, yet the description still covers storage provenance, deployment caveat, and the SQL prerequisite. Nothing an agent needs to call this 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% and the schema description already explains the df_XXXXX_XXXXX pattern, case-insensitivity, and the omit-to-list behavior. The description restates the same semantics rather than adding new meaning, 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?

Names a specific verb and resource (describe the df_<id> dataframes) and pins down exactly which objects it covers by naming the two producing tools plus the register_as storage path. An agent can distinguish it from ilostat_dataframe_query and the query siblings 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?

States the two invocation modes (pass name for one, omit to list all), names the deployment condition where listing is refused and only the exact name works, and gives an explicit prerequisite: read the schema here before writing SQL for ilostat_dataframe_query. Alternatives and exclusions are both present.

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 substantial behavioral context beyond the annotations: it lists rejected SQL operations, denied system catalogs, the read-only enforcement scope, and the overlap warning for breakdown versions. It also notes that register_as creates a new dataframe with a fresh TTL and that registration can evict older dataframes.

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 front-loaded with the core operation, then layers in the inspection prerequisite, read-only constraints, overlap warning, and register_as behavior without redundant restatement. Every sentence carries useful guidance for invoking the tool correctly.

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 query complexity, full schema coverage, output schema, and read-only annotations, the description supplies the remaining operational context: what is rejected, which catalogs are denied, when to inspect schema first, and how register_as enables chaining. Nothing an agent needs in order to call 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 the schema already documents all four parameters thoroughly. The description adds little parameter-specific meaning beyond what the schema provides, aside from briefly noting that register_as stores a new dataframe with a fresh TTL.

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: running a single-statement SELECT against df_<id> dataframes. It distinguishes the tool from its siblings by identifying those dataframes as staged by ilostat_query_indicator and ilostat_compare_geographies or created by an earlier register_as.

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 explains the context of use: query staged dataframes, inspect them first with ilostat_dataframe_describe, and optionally chain results with register_as. It does not explicitly state when to prefer this over querying raw indicators directly, so it falls just short of a full when/when-not/alternatives statement.

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 the metadata categories returned, the total-code marking of breakdowns, and the error contract ('an unknown code returns found: false with guidance'). It also explains code-form handling (ID vs bare code, DF_ prefix stripping), which the annotations cannot 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?

Front-loaded with purpose and error behavior in two sentences with no filler. The first sentence is a dense enumeration of return categories, which is long but each clause carries information an agent needs to decide whether to call it.

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 safety annotations covering the read-only/idempotent profile, the description only needs to add purpose, input-form semantics, and error handling — all of which it does. Nothing needed 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 the baseline is 3, but the description adds real semantics: a bare indicator code 'describes every frequency' versus a suffixed dataset ID describing one, and the failure behavior for unknown codes. That meaning is not present in the schema 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?

States a specific verb (explain/describe) and resource (one ILOSTAT dataset) and enumerates exactly what the response covers: definition, unit/multiplier, frequency variants, breakdown codes, reference areas, aggregates, and observation status. This is clearly distinguishable from data-fetching siblings like ilostat_query_indicator and lookup siblings like ilostat_search_indicators.

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 opening clause 'before comparing numbers' implies a workflow position but never names alternatives (e.g. use ilostat_query_indicator for values, ilostat_search_indicators to find codes) or states exclusions. Usage is implied rather than explicit.

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 cover read-only/idempotent/closed-world, so the bar is lower; the description still adds real behavior: cursor pagination for long topics, the fact that exact-code lookups enumerate member countries for area_groups, and the clamp-and-notice behavior on oversized limits. It does not describe rate limits or failure modes, but that is a minor gap against the annotation coverage.

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, then a long but load-bearing enumeration of the 11 topics, then the routing sentence. The topic list is dense and could be trimmed since the enum is in the schema, but every remaining sentence 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?

An output schema exists so return values need no explanation, and the description still covers pagination, filtering semantics, cross-tool routing, and the special area_groups expansion. What is missing is only edge behavior (invalid topic, empty result shape), which the schema largely absorbs.

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; the description goes past that by spelling out the topic-to-parameter coupling (area_group membership, classif1/classif2 with classification types, sources per country) and by restating the filter's prefix/'labor' vs 'labour' matching semantics that make the filter actually usable.

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?

Opens with a specific verb+resource ('Decode ILOSTAT's code vocabulary') and then enumerates exactly which vocabularies are covered, including the trickier area_groups/classif1/classif2 cases. It also explicitly distinguishes itself from the sibling ilostat_describe_indicator, so an agent can route 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?

States the two selection modes ('Filter by text or look up exact codes'), notes the cursor case for long topics, and names the alternative tool with the condition that selects it ('ilostat_describe_indicator lists the sex and breakdown codes one dataset actually uses'). Nothing about when to reach for this tool 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?

Goes well past the readOnly/openWorld/idempotent annotations: discloses the 3-dataset ceiling, the df_<id> staging path, the row-ceiling refusal behavior for unfiltered vs filtered requests, and the latest_only fallback that can miss earlier-ending series. These are exactly the operational traits an agent cannot infer from structured fields.

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-loads the core operation before limits, validation, and staging behavior, and every clause carries operational information. It is a dense single block, but the density tracks the tool's real complexity rather than padding.

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 no explanation, and the description still covers the parts that matter: dataset caps, filter echoing, code validation, refusal thresholds, and dataframe staging. 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 12 parameters in depth. The description mostly restates the filter axes and the best-source default rather than adding syntax or semantics 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?

Opens with a specific verb+resource+scope ('Fetch observations for up to 3 ILOSTAT datasets per call') and enumerates the filter axes. It is clearly distinguishable from siblings, naming list_reference, describe_indicator, and the dataframe tools in their supporting roles.

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 concrete routing: use ilostat_list_reference for valid codes, ilostat_describe_indicator for codes a dataset actually uses, and dataframe tools when a result is staged as df_<id>. It also explains the 3-dataset cap and the remaining_dataset_ids continuation. It stops short of stating when to prefer ilostat_compare_geographies or ilostat_get_country_profile instead, so no explicit exclusions.

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 closed-world behaviour, so the safety profile is covered. The description adds real value beyond that with matching semantics (word/prefix matching, stem fallback with a naming notice, labour/labor equivalence) and the note that facet counts respect all applied filters; however, the limit is documented as being capped at 50 in the schema itself.

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 workflow are front-loaded in the first sentence, and each subsequent clause carries distinct information about matching or filtering. The middle sentence is a dense run-on packing prefix matching, stem fallback and spelling equivalence, which could be split for readability, but nothing is padding.

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 9-parameter search tool with full schema coverage, an output schema and existing annotations, the description covers everything an agent needs: result shape, filter semantics, match fallbacks, the limit cap, and the hand-off chain to sibling tools.

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 semantics the schema does not carry: that the measure filter returns every indicator of that quantity under any breakdown and counts them as ilostat_describe_indicator does, and that facet counts reflect all applied filters.

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 opening sentence states a specific verb and resource (search ILOSTAT's catalog of labour-statistics indicators) and immediately defines the unit of a hit, so the agent knows exactly what comes back. It is clearly separable from siblings like ilostat_describe_indicator and ilostat_query_indicator, which it explicitly positions downstream.

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 an explicit workflow: search here, pass a dataset ID to ilostat_describe_indicator for units and breakdowns, then to ilostat_query_indicator or ilostat_compare_geographies for values. It also tells the agent to omit the query to browse by filters and points to ilostat_list_reference for valid subject/database/classification codes.

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