istat-mcp

ISTAT MCP Server - Workflow Guide

Language Detection — First Step (mandatory)

Before doing anything else, detect the language of the user's first message.

User writes in	Set	Apply to
Italian	lang=it	all responses, labels, summaries, warnings, get_concepts calls, "Fonti dati" section
English	lang=en	all responses, labels, summaries, warnings, get_concepts calls, "Data Sources" section

Rules:

• Detect once at the start; keep lang fixed for the entire conversation even if the user later switches language.
• Every response — including tool-call summaries, warnings, and the closing data-sources section — must use the detected language.
• When calling get_concepts, always pass "lang": "<detected>" (e.g. {"concept_id": "FREQ", "lang": "it"}).
• If the language cannot be determined (e.g. the first message is a bare dataflow ID), default to lang=it.

Quick Start

If the query targets a specific territory (region, province, municipality), start by resolving the territory:

1. Resolve territory with get_territorial_codes → get REF_AREA codes
2. Discover the dataflow with discover_dataflows
3. Get metadata with get_constraints (one call returns dimensions + valid codes + descriptions)
4. Fetch data with get_data using the codes from steps 0 and 2

Skip step 0 only when the query is about Italy as a whole (REF_AREA: IT).

Time Period Rule

Default behaviour — last available year, month or quarter. Unless the user explicitly requests a time series or a specific period, always use get_data without start_period/end_period and with lastNObservations=1 . Using lastNObservations=1 returns only the last available observation. This keeps responses compact and avoids flooding the context with multi-decade series.

Time series — explicit request. Use start_period / end_period only when the user explicitly asks for:

• time series for a specific years range ("dal 2015 al 2026", "from 2010 to 2026")
• Time series starting from a specific year ("dal 2015 in poi", "from 2015 onwards")
• time series for a specific month/quarter ("mostrami la serie storica mensile", "show me the quarterly series"). In this case show data only for the last 2 available years to avoid flooding the context with too many observations.