eurostat-mcp-server

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

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description enriches understanding by detailing the exact conditional behavior (top-level folders vs. immediate children) and the nature of the returned items ('subtheme folders and datasets in that branch'). This exceeds annotation coverage without contradicting it.

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-organized: a lead sentence, then behavior, then usage guidance, then cross-reference. Every sentence contributes to either understanding or decision-making; there is no redundant or filler content.

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 fairly simple read-only browsing tool with one optional parameter and an output schema, the description covers all necessary operational aspects: what happens with and without the parameter, what the output contains, and how it relates to other tools (search, drill-down). No significant gaps remain.

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?

The input schema already provides a full description for theme_code (100% coverage), including the example values and the 'omit to list top-level' behavior. The description reinforces this by explaining the consequence of providing vs. omitting the parameter in functional terms, adding marginal value rather than repeating 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 starts with a specific verb+resource combination: 'Navigate the Eurostat theme tree.' It clearly distinguishes itself from sibling tools by focusing on structured tree navigation, contrasting with keyword-based search. It also specifies distinct behaviors with and without a theme_code, which adds precision.

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 provides explicit guidance: 'Use this for structured discovery when you know the domain but not the dataset code, or to drill down from a broad topic to a specific dataset.' It also names the alternative and pairing tool: 'Pair with eurostat_search_datasets for keyword-based discovery.' This fully addresses when to use this tool versus the sibling.

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. The description adds substantial behavioral context: it reveals that the two stagers produce different dimension columns (code+label vs code-only plus time) and that both share five fixed measure columns, enabling cross-stager joins. It also cautions to 'read the columns reported here rather than assuming,' which is valuable beyond 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 four sentences, each conveying a distinct piece of information without redundancy. It is dense but justified given the need to explain the data model differences between stagers. It is front-loaded with the purpose and well organized.

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 annotations covering safety, a full schema for the single parameter, and an output schema present, the description completes the picture by explaining prerequisites, usage timing, schema differences between stagers, and join semantics. No critical gaps are apparent.

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?

The schema already provides 100% coverage for canvas_id, stating its source and purpose. The description reiterates this and adds the qualifier 'that reported a staged table,' but does not significantly extend the schema's meaning. 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?

The description clearly states the tool's function: 'List the tables staged on a Eurostat dataframe canvas, with their row counts and column names and types.' It also explicitly distinguishes it from siblings by positioning it as a prerequisite for eurostat_dataframe_query, making its role unambiguous.

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 direct guidance: 'Call this before eurostat_dataframe_query to learn the table and column names to write SQL against.' It also explains the canvas_id provenance from the two staging tools and warns about the differing dimension columns, providing clear context on when and how to use it.

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, but the description adds substantial context: limitations on SQL statements, column structure (obs_value, obs_flag, conf_status), and differences between stagers. This goes well beyond the annotations without contradiction.

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, conveying purpose, constraints, schema details, and cross-tool differences without redundancy. It is front-loaded with the main purpose and progressively details constraints and data model.

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 tool's complexity, the output schema exists, and annotations cover safety, the description is complete. It explains usage, constraints, column semantics, and relationships to sibling stagers, covering all necessary context for an agent to invoke it 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 coverage is 100% and the sql parameter already has an example, but the description adds critical semantics: the single-SELECT constraint, the need to reference table names from describe, and the flat-column structure with dimension code columns and measure columns. This meaningfully enriches parameter understanding.

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 runs read-only SQL SELECT on staged dataframes, with a specific purpose: to bypass the 5,000-row cap and to aggregate/join without re-fetching. It explicitly distinguishes from sibling tools like eurostat_query_dataset and eurostat_download_dataset.

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?

Provides explicit when-to-use guidance (bypassing caps, aggregating/joining) and when-not-to-use (non-SELECT verbs, chaining, external data functions rejected). Also instructs to call eurostat_dataframe_describe first for table/column names.

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, but the description adds critical behavioral context beyond that: 'Transfers are bounded by a byte budget enforced while streaming: when it is spent the download stops and budgetExceeded is set, leaving a prefix of the dataset rather than an error.' It also explains that only preview_limit rows come back inline and the rest are available only on canvas deployments. No contradiction with 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 long but every sentence adds essential information: main purpose, comparison, HTTP format rationale, filter usage, period advice, byte budget behavior, and preview semantics. It is front-loaded with the primary action and structured logically from general to specific. 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?

Given the tool's complexity (bulk download, streaming, canvas staging, byte budgets), the description covers all key aspects: what it does, wire format, prerequisites, filtering, period handling, transfer limits, and how to access the full data. The presence of an output schema reduces the need to explain return values, and the description still mentions the budgetExceeded flag and preview_limit behavior. It is comprehensive and sufficient.

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?

The input schema already covers all parameters (100% coverage), providing a solid baseline. The description adds extra meaning by explaining relationships: filters are 'the same dimension-code map eurostat_query_dataset uses,' since_period/until_period 'removes period columns from the TSV rather than blanking their cells,' and preview_limit is 'orientation, not the result set.' This is valuable beyond the schema, but not all parameters need extra 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 opens with 'Download a Eurostat dataset in bulk through the SDMX 2.1 TSV endpoint and stage every observation as a SQL table on the dataframe canvas,' which is a specific verb+resource+scope. It explicitly distinguishes from sibling eurostat_query_dataset by calling it 'the route to a whole dataset' versus 'a slice of one.'

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 states when to use this tool vs alternatives, naming eurostat_query_dataset for slices. It gives concrete prerequisites ('call eurostat_get_dataset_info first for the dimension codes and eurostat_get_dimension_values for their values') and advises to 'Narrow with since_period/until_period rather than asking for the most recent N periods,' explaining the reason. It also describes fallback usage via eurostat_dataframe_query.

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 read-only, open-world, and idempotent behavior. The description adds important runtime behavior beyond that: it returns up to 10 sample values per dimension, and it notes that eurostat_download_dataset builds its positional filter key from this dimension list, so invalid dimension names are rejected. This enriches the agent's understanding without contradicting 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 three sentences long, front-loaded with the primary purpose, and each sentence adds distinct value: what it returns, when to call it, and limitations (sample values vs. full set). No filler or 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?

With one well-described parameter, an output schema present, and thorough annotations, the description still manages to cover the key contextual aspects: the return contents, the recommended usage order, the sample-limit behavior, and alternatives. The tool is simple enough that no further context is needed.

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?

The schema covers 100% of parameter descriptions (dataset_code includes its own help text with examples and pointers to search tools), so the baseline is 3. The tool description itself does not add further parameter semantics beyond what the schema already provides, but it also doesn't need to given the 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 identifies the tool's function with a specific verb ('Fetch') and resource ('metadata for a Eurostat dataset'), outlining the key pieces of metadata (dimensions, time range, observation count, last-update date). It also distinguishes itself from siblings by explaining its role as an exploratory step before querying or downloading, and contrasts with eurostat_get_dimension_values for full dimension lists.

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?

Explicit usage guidance is provided: 'Call this before eurostat_query_dataset or eurostat_download_dataset' and 'use eurostat_get_dimension_values to list the full set for large dimensions.' This clearly states when to use this tool and when to use an alternative, making the appropriate context unmistakable.

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 declare readOnly, openWorld, and idempotent, so the safety profile is covered. The description adds behavioral context about geo_level filtering and the consequences of invalid codes in sibling tools, which is informative beyond the 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?

Four sentences, each serving a distinct purpose: core listing, usage triggers, geo_filter guidance, and validation rationale. The final sentence is complex but remains coherent and front-loaded with the main action.

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 covers purpose, usage, and validation context. With an output schema present and annotations covering safety, no major gaps remain. Minor details like response ordering are not critical for this listing 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 coverage is 100% with each parameter described. The description adds examples and reinforces the geo_level restriction but doesn't introduce new semantic meaning 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?

The description opens with a clear verb+resource: 'List all valid values for a specific dimension in a Eurostat dataset.' It differentiates from siblings by focusing on dimension values, with examples like 'all unit codes for nama_10_gdp', making its purpose unmistakable.

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: 'Use this when eurostat_get_dataset_info returns more values than the 10-item sample, or to confirm exact codes before querying.' It also contrasts with eurostat_query_dataset and eurostat_download_dataset regarding invalid codes, providing clear selection criteria.

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 declare readOnlyHint, idempotentHint, and openWorldHint, the description adds substantial behavioral context: the 5,000 inline row cap, the OBS_FLAG and CONF_STATUS markers (including why values may be null), the async response error for large unfiltered queries, and the silent-return behavior for invalid dimension values. It also discloses mutual exclusivity constraints among parameters. These are meaningful traits not visible in 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 dense but well-structured: it leads with the core action and return format, then prerequisites, filter strategy, period handling, cap handling, and sibling alternatives. Every sentence adds operational value—no filler or repetition. It is front-loaded with the most important information and organized as a logical sequence of decision points for the agent.

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 tool's complexity (8 parameters, nested objects, rich output schema, and 7 siblings), the description is exceptionally complete. It covers purpose, return shape, row caps, error conditions, parameter relationships, prerequisites, and explicit fallback paths. The presence of an output schema removes the need to document return values in detail, but the description still explains domain-specific markers (OBS_FLAG, CONF_STATUS) and staging behavior, fully equipping the agent to select and invoke the 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%, giving a baseline of 3, but the description enriches parameter understanding considerably. It explains the semantic difference between filters.geo and geo_level, the purpose of last_n_periods (N most recent periods without knowing end date), mutual exclusivity of since_period/until_period with last_n_periods, and the canvas_id reuse pattern for staging. It also warns that invalid dimension values silently return no data, which schema descriptions don't 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?

The description opens with a specific verb+resource: 'Fetch statistical data from a Eurostat dataset with dimension filters.' It clearly distinguishes itself from siblings by explicitly stating this tool 'fetches a slice' while 'eurostat_download_dataset reads the SDMX bulk endpoint instead' for a whole dataset. The return format is specified (decoded observations with codes, labels, values, statuses), making the tool's purpose unambiguous.

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 when-to-use guidance: call eurostat_get_dataset_info first to discover valid dimension codes, use filters.geo for country codes or geo_level for NUTS hierarchy (mutually exclusive), and use last_n_periods for recent periods without a known end date. It also states when NOT to use the tool: for whole datasets, eurostat_download_dataset is 'the cheaper route'; past the inline cap, read the staged table with eurostat_dataframe_query rather than re-querying. This goes beyond implied usage to clear alternatives and 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 openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: results are limited to datasets and predefined tables (folders excluded) and that it returns period coverage and breadcrumbs. It does not detail pagination behavior, but that is covered in the input schema's cursor description, so no contradiction or major gap.

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 four sentences, each earning its place: what the tool does, what it returns, how it fits into the sibling workflow, and its scope limitation. It is front-loaded with the core purpose and contains no redundant or vague phrasing.

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 rich input schema (all parameters documented), the presence of an output schema, and annotations covering safety and openness, the description is complete enough for an agent to select and correctly invoke the tool. It explains the discovery workflow, return contents, and scope limitations; remaining details like pagination mechanics are already in the structured 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 coverage is 100%, and each parameter already has a detailed description explaining semantics (e.g., query tokenization, AND matching, pagination cursor). The description merely says 'by keyword' and does not add parameter-level meaning beyond the schema, 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 clearly states the action ('Search the Eurostat catalogue by keyword') and specifies the resource and return contents (codes, descriptions, period coverage, theme breadcrumbs). It also distinguishes the tool from siblings by positioning it as the discovery step before eurostat_get_dataset_info, eurostat_query_dataset, or eurostat_download_dataset.

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 lays out the recommended workflow: use this to discover dataset codes, then call get_dataset_info, and then query or download for data. It also notes an exclusion ('folders are excluded') which implies the alternative browse_themes for folder navigation, satisfying when-not guidance.

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