Tilastokeskus StatFin MCP Server

Query Statistical Data

query_table

Read-onlyIdempotent

Retrieve specific statistical data from Finnish StatFin tables by defining variable selections and filters for precise results.

Instructions

Execute a query to retrieve actual statistical data from a table.

WORKFLOW: search_statistics → get_table_metadata → query_table

Selection types:

filter: "item" + values: ["KU091", "2024"] → specific values
filter: "top" + top: 5 → latest 5 values (good for time variables)
filter: "all" → all values (use carefully, can be large!)

Example - Helsinki population for last 5 years (the variable codes below are from table 11re.px; YOUR table's codes WILL differ - always read them from get_table_metadata first, never reuse these): { "tableId": "11re.px", "selections": [ {"variable": "alue_23_20260101", "filter": "item", "values": ["KU091"]}, {"variable": "timeperiod_y", "filter": "top", "top": 5}, {"variable": "sukupuoli_9_20180101", "filter": "item", "values": ["SSS"]}, {"variable": "ikaryhma_10_20180101", "filter": "item", "values": ["SSS"]}, {"variable": "contentscode", "filter": "item", "values": ["vaerak-vaesto"]} ] }

IMPORTANT: Variable codes are table-specific; get them from get_table_metadata. Use VALUE CODES (KU091, SSS), not labels (Helsinki, Total).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Max rows. If query exceeds this, it fails with an error suggesting more specific selections.
`tableId`	Yes	Table ID from search_statistics or list_tables. Example: "11re.px"
`language`	No	Label language in results. Default "fi".	fi
`selections`	Yes	One entry per variable. IMPORTANT: Include all non-optional variables or query will return too much data.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	No	Query results (only present if success=true)
`error`	No	Error message (only present if success=false)
`success`	Yes	True if query succeeded, false if error
`metadata`	No	Dataset metadata (source, last updated, label)
`rowCount`	No	Number of data rows returned
`queryInfo`	Yes	Query execution metadata

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 15, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior, lowering the burden. The description adds useful behavioral context beyond annotations: the 'all' filter can return large datasets, variable codes are table-specific, and the example shows how selections are structured. It does not contradict annotations.

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 long but every section earns its place: purpose, workflow, selection-type semantics, a concrete example, and critical warnings. It is front-loaded with the core action and workflow, and the example is highly instructive rather than filler.

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, the 100% schema coverage, and the presence of an output schema, the description is complete. It covers the required workflow, selection semantics, the need for table-specific codes, and caution around large result sets. Nothing essential for an agent to call this tool correctly is missing.

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

Parameters4/5

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 significant meaning beyond the schema by explaining the three selection types with concrete examples and emphasizing value codes over labels. The example JSON demonstrates exactly how to populate selections, which is valuable for correct invocation.

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 clearly states the tool executes a query to retrieve actual statistical data from a table, using a specific verb and resource. It also positions the tool within a workflow (search_statistics → get_table_metadata → query_table), which differentiates it from sibling tools like search_statistics and get_table_metadata.

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

Usage Guidelines4/5

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

The WORKFLOW line explicitly places query_table as the final step after search_statistics and get_table_metadata, giving clear sequencing. The description also warns to read variable codes from get_table_metadata first and never reuse codes, but it does not explicitly state when not to use query_table or name alternative tools for other needs.

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

Deploy Server