Skip to main content
Glama

Search Eurostat Datasets

eurostat_search_datasets
Read-onlyIdempotent

Search the Eurostat catalogue by keyword. Returns matching datasets with codes, descriptions, period coverage, and theme breadcrumbs. Use this to discover dataset codes before calling eurostat_get_dataset_info, then eurostat_query_dataset for a slice of a dataset or eurostat_download_dataset for the whole of one. Results are limited to datasets and predefined tables — folders are excluded. The catalogue joins two sources: the dissemination table of contents, and the Comext host's dataflow list, which adds the DS-* collections — detailed trade by CN8, HS, SITC, BEC and CPA, and PRODCOM — filed under "International trade in goods - detailed data (Comext)" and "Statistics on the production of manufactured goods (PRODCOM)". Comext entries report a last-update date but no period coverage or observation count. A collection on neither list, such as the legacy PRODCOM DS-056120, is not disseminated and cannot be reached through this server.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoPage size — maximum datasets returned per page (1–100). Default is 20. To retrieve matches beyond one page, pass the returned nextCursor back as cursor; the page size is fixed by this first call.
queryYesSearch terms — at least one non-whitespace token is required. Split on whitespace into tokens; every token must match (AND), case-insensitively, somewhere across the dataset label, theme breadcrumb, or code. Word order does not matter, so "business demography NUTS 3" or "regional economic accounts" resolve without naming a label verbatim.
cursorNoOpaque pagination cursor from a previous call's nextCursor. Omit for the first page; pass it back — with the same query — to fetch the next page of matches over a stable order. A cursor is bound to the query that produced it and to the catalogue snapshot in effect at that time, so reusing one with a different query, or after the catalogue refreshes, is rejected rather than silently paging a different result set.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
queryNoSearch terms as submitted.
datasetsNoMatching datasets for the current page, up to the requested limit.
nextStepNoSuggested next action based on these results. Populated when there is a clear follow-up call.
truncatedNoTrue when more matches remain beyond this page — pass nextCursor as cursor to fetch them.
nextCursorNoOpaque cursor for the next page of matches. Pass it back as cursor with the same query; it stops working once the catalogue refreshes. Omitted on the last page.
totalMatchesNoTotal distinct dataset codes matching the query across all pages, before the page limit.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `no_match`: No datasets matched the query string. `invalid_cursor`: The cursor is malformed, came from a different query, or came from a catalogue snapshot that has since refreshed. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_match`: No datasets matched the query string — including a query naming a DS-* code that neither the dissemination table of contents nor the Comext dataflow list carries, which is a collection Eurostat does not disseminate. `invalid_cursor`: The cursor is malformed, came from a different query, or came from a catalogue snapshot that has since refreshed. Other values are possible when a failure originates below the handler."
  2. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "datasets",
      +      "query",
      +      "totalMatches",
      +      "truncated"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `no_match`: No datasets matched the query string. `invalid_cursor`: The cursor is malformed, came from a different query, or came from a catalogue snapshot that has since refreshed. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "no_match",
      +            "invalid_cursor"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "datasets",
      -  "query",
      -  "totalMatches",
      -  "truncated"
      -]
  3. Changed1 schema field changed
    • changedOutput schema / properties / datasets / items / properties / code / description
      Previous value: -"Dataset code (e.g., \"nama_10_gdp\"). Use this in eurostat_get_dataset_info and eurostat_query_dataset."New value: +"Dataset code (e.g., \"nama_10_gdp\"). Use this in eurostat_get_dataset_info, eurostat_query_dataset, and eurostat_download_dataset."
  4. Changed6 schema fields changed
    • changedInput schema / properties / cursor / description
      Previous value: -"Opaque pagination cursor from a previous call's nextCursor. Omit for the first page; pass it back to fetch the next page of matches over a stable order."New value: +"Opaque pagination cursor from a previous call's nextCursor. Omit for the first page; pass it back — with the same query — to fetch the next page of matches over a stable order. A cursor is bound to the query that produced it and to the catalogue snapshot in effect at that time, so reusing one with a different query, or after the catalogue refreshes, is rejected rather than silently paging a different result set."
    • changedInput schema / properties / query / description
      Previous value: -"Search terms. Split on whitespace into tokens; every token must match (AND), case-insensitively, somewhere across the dataset label, theme breadcrumb, or code. Word order does not matter, so \"business demography NUTS 3\" or \"regional economic accounts\" resolve without naming a label verbatim."New value: +"Search terms — at least one non-whitespace token is required. Split on whitespace into tokens; every token must match (AND), case-insensitively, somewhere across the dataset label, theme breadcrumb, or code. Word order does not matter, so \"business demography NUTS 3\" or \"regional economic accounts\" resolve without naming a label verbatim."
    • addedInput schema / properties / query / pattern
      Added value: +"\\S"
    • changedOutput schema / properties / datasets / items / properties / themePath / description
      Previous value: -"Breadcrumb path from root theme to this dataset (e.g., [\"Economy and finance\", \"National accounts\"]). Empty for top-level entries."New value: +"Breadcrumb path from root theme to this dataset (e.g., [\"Database by themes\", \"Economy and finance\"]). Eurostat files some datasets under several branches; this is the first branch that matched the query. Empty for top-level entries."
    • changedOutput schema / properties / nextCursor / description
      Previous value: -"Opaque cursor for the next page of matches. Pass it back as cursor. Omitted on the last page."New value: +"Opaque cursor for the next page of matches. Pass it back as cursor with the same query; it stops working once the catalogue refreshes. Omitted on the last page."
    • changedOutput schema / properties / totalMatches / description
      Previous value: -"Total datasets matching the query across all pages, before the page limit."New value: +"Total distinct dataset codes matching the query across all pages, before the page limit."
  5. Changed9 schema fields changed
    • addedInput schema / properties / cursor
      Added value: +{
      +  "description": "Opaque pagination cursor from a previous call's nextCursor. Omit for the first page; pass it back to fetch the next page of matches over a stable order.",
      +  "type": "string"
      +}
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of results to return (1–100). Default is 20."New value: +"Page size — maximum datasets returned per page (1–100). Default is 20. To retrieve matches beyond one page, pass the returned nextCursor back as cursor; the page size is fixed by this first call."
    • changedInput schema / properties / query / description
      Previous value: -"Search terms — case-insensitive substring match against dataset labels."New value: +"Search terms. Split on whitespace into tokens; every token must match (AND), case-insensitively, somewhere across the dataset label, theme breadcrumb, or code. Word order does not matter, so \"business demography NUTS 3\" or \"regional economic accounts\" resolve without naming a label verbatim."
    • changedOutput schema / properties / datasets / description
      Previous value: -"Matching datasets, up to the requested limit."New value: +"Matching datasets for the current page, up to the requested limit."
    • addedOutput schema / properties / nextCursor
      Added value: +{
      +  "description": "Opaque cursor for the next page of matches. Pass it back as cursor. Omitted on the last page.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / nextStep
      Added value: +{
      +  "description": "Suggested next action based on these results. Populated when there is a clear follow-up call.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / totalMatches / description
      Previous value: -"Total datasets matching the query before the limit."New value: +"Total datasets matching the query across all pages, before the page limit."
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when more matches remain beyond this page — pass nextCursor as cursor to fetch them.",
      +  "type": "boolean"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "datasets",
      -  "query",
      -  "totalMatches"
      -]New value: +[
      +  "datasets",
      +  "query",
      +  "totalMatches",
      +  "truncated"
      +]
  6. Changed3 schema fields changed
    • addedOutput schema / properties / query
      Added value: +{
      +  "description": "Search terms as submitted.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / totalMatches / description
      Previous value: -"Total number of datasets matching the query before the limit is applied."New value: +"Total datasets matching the query before the limit."
    • changedOutput schema / required
      Previous value: -[
      -  "datasets",
      -  "totalMatches"
      -]New value: +[
      +  "datasets",
      +  "query",
      +  "totalMatches"
      +]
  7. First observed

TDQS

A5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description goes further: explains the catalogue merges two sources, notes that Comext entries lack period coverage/observation count, warns that some collections are not disseminated, and clarifies pagination stability via cursor. This adds substantial behavioral context 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average but every sentence earns its place. It front-loads the purpose and workflow, then layers behavioral nuances. There is no filler or repetition; each clause adds actionable detail. The structure flows logically from purpose to usage to edge cases, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (catalogue search with pagination, two data sources, exclusions) and the presence of an output schema, the description covers all necessary aspects: what is returned, how to use it in a workflow, limitations, and parameter semantics. An agent has everything needed to invoke it correctly and interpret results, without gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema already documents all 3 parameters at 100% coverage, the description adds meaningful semantics: query tokenization rules (AND, case-insensitive, matching across label/breadcrumb/code) and cursor binding to query and catalogue snapshot. This goes well beyond the schema's basic field types, helping the agent craft effective queries and handle pagination correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Search the Eurostat catalogue by keyword') and immediately lists the returned fields (codes, descriptions, period coverage, theme breadcrumbs). It explicitly distinguishes itself from siblings by stating it is the discovery step before get_info/query/download, and contrasts with browsing by theme. No ambiguity about what this tool does or how it differs from the 7 siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit workflow: use this to find codes, then call eurostat_get_dataset_info, then query or download. It also states exclusions (folders excluded) and caveats (legacy collections like DS-056120 not reachable). This tells the agent exactly when to use it and when not to, referencing alternative tools directly.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.