Expat Living Italy

Get one comune's profile

get_comune

Read-onlyIdempotent

One Italian comune's population, foreign residents by citizenship, property purchase/rent price, price-to-rent, verified tax-regime eligibility, its province's rollup, seismicZone (the official zona sismica 1-4: a legal classification, not a forecast and not a verdict on any building; quote it with its label and say so — a comune that straddles zones has no single zone, never round it; the zone has nothing to do with tax eligibility, and is not the 7% regime’s “seismic” routes, which depend on the 2009 and 2016-17 earthquake areas), layers (climate, air quality, crime, healthcare quality, age, population change and every other Italy-map layer) and provinceWellbeing (ISTAT BES indicators, polarity-aware percentiles) — looked up by 6-digit ISTAT code. Each layer's grain and measuredFor say whose number it is: a province or region value is not a measurement of this comune — say so when you quote it. Every field is wrapped in a provenance envelope (source, vintage, extractedOn, license); repeat the vintage when you state the number, and if a value is null, say why rather than treating it as zero.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`istatCode`	Yes	6-digit ISTAT comune code, e.g. 075029.

Output Schema

TableJSON Schema

Name	Required	Description
`place`	Yes
`layers`	Yes	Every other map layer's value for this place, at the grain its source publishes. A null value means the source has no figure for this place (see `reason`).
`articles`	No	Published articles about this comune — the reporting behind the numbers. Credit required to reuse.
`population`	Yes
`attribution`	Yes
`seismicZone`	Yes	The comune's official seismic zone (zona sismica). A legal classification, not a forecast and not a verdict on any building. value is null, never a default zone, when the Department's table has no row for this comune.
`provinceRollup`	Yes
`priceToRentYears`	Yes	Years of rent that equal the purchase price. Not a yield, an ROI, or a payback period.
`provinceWellbeing`	Yes	ISTAT BES well-being indicators for this comune's province — province-level, not a comune measurement.
`purchasePriceEurM2`	Yes
`rentPriceEurM2Month`	Yes
`taxRegimeEligibility`	Yes	Verified regimes only — "placesNotPeople": geographic eligibility, not personal advice.
`totalForeignResidents`	Yes	Sum of foreignResidentsByCitizenship: only the citizenships this site tracks, so a floor, not every foreign resident — Moroccan, Chinese and Indian residents, among others, are not counted. For every foreign resident, see foreignResidentsAllCitizenships. null when the citizenship dataset has no row for this comune.
`foreignResidentsByCitizenship`	Yes	Counts by ISO-2 citizenship code. Citizenship, not birthplace — excludes foreign-born Italian citizens. value is null, never a zero-filled object, when ISTAT's citizenship dataset has no row at all for this comune.
`foreignResidentsAllCitizenships`	Yes	Residents holding any foreign citizenship: ISTAT's own total, not limited to the citizenships tracked in foreignResidentsByCitizenship. Citizenship, not birthplace. value is null, never 0, when ISTAT sends no total for this comune.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 15, 2026

addedOutput schema / properties / seismicZone

Added value: +{
+  "additionalProperties": false,
+  "description": "The comune's official seismic zone (zona sismica). A legal classification, not a forecast and not a verdict on any building. value is null, never a default zone, when the Department's table has no row for this comune.",
+  "properties": {
+    "coverage": {
+      "additionalProperties": false,
+      "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+      "properties": {
+        "in": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "of": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "in",
+        "of"
+      ],
+      "type": "object"
+    },
+    "extractedOn": {
+      "description": "ISO date this value was extracted from the source.",
+      "type": "string"
+    },
+    "license": {
+      "type": "string"
+    },
+    "method": {
+      "description": "URL to the methodology page for this dataset.",
+      "type": "string"
+    },
+    "reason": {
+      "description": "Present only when value is null: why this place has no figure.",
+      "type": "string"
+    },
+    "source": {
+      "type": "string"
+    },
+    "unit": {
+      "type": "string"
+    },
+    "value": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "hazardClass": {
+              "anyOf": [
+                {
+                  "maximum": 4,
+                  "minimum": 1,
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The map layer's value: 5 minus the zone, so 4 is the highest hazard (official zone 1). null when split."
+            },
+            "label": {
+              "description": "The Department of Civil Protection's label as published: \"3\", a regional sub-zone such as \"2B\" or \"3S\", or a combined label such as \"2A-3A-3B\".",
+              "type": "string"
+            },
+            "officialZone": {
+              "anyOf": [
+                {
+                  "maximum": 4,
+                  "minimum": 1,
+                  "type": "integer"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The national zone, 1 (highest hazard) to 4 (lowest). null when the comune straddles zones."
+            },
+            "reading": {
+              "description": "What the classification is and is not. A legal classification used for planning and building control — not a forecast, and not an assessment of any building.",
+              "type": "string"
+            },
+            "zonesInvolved": {
+              "description": "Every national zone the label names; more than one means the comune straddles zones.",
+              "items": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "officialZone",
+            "label",
+            "hazardClass",
+            "zonesInvolved",
+            "reading"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "vintage": {
+      "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "value",
+    "unit",
+    "source",
+    "vintage",
+    "extractedOn",
+    "method",
+    "license"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "place",
-  "population",
-  "foreignResidentsByCitizenship",
-  "totalForeignResidents",
-  "foreignResidentsAllCitizenships",
-  "purchasePriceEurM2",
-  "rentPriceEurM2Month",
-  "priceToRentYears",
-  "taxRegimeEligibility",
-  "provinceRollup",
-  "layers",
-  "provinceWellbeing",
-  "attribution"
-]New value: +[
+  "place",
+  "population",
+  "foreignResidentsByCitizenship",
+  "totalForeignResidents",
+  "foreignResidentsAllCitizenships",
+  "purchasePriceEurM2",
+  "rentPriceEurM2Month",
+  "priceToRentYears",
+  "taxRegimeEligibility",
+  "provinceRollup",
+  "seismicZone",
+  "layers",
+  "provinceWellbeing",
+  "attribution"
+]

Changed2 schema fields changedOct 12, 2026

changedOutput schema / properties / foreignResidentsAllCitizenships / description

Previous value: -"Residents holding any foreign citizenship: ISTAT's own total, not limited to the 25 citizenships tracked in foreignResidentsByCitizenship. Citizenship, not birthplace. value is null, never 0, when ISTAT sends no total for this comune."New value: +"Residents holding any foreign citizenship: ISTAT's own total, not limited to the citizenships tracked in foreignResidentsByCitizenship. Citizenship, not birthplace. value is null, never 0, when ISTAT sends no total for this comune."

changedOutput schema / properties / totalForeignResidents / description

Previous value: -"Sum of foreignResidentsByCitizenship: only the citizenships this site tracks (25), so a floor, not every foreign resident — Romanian, Albanian and Moroccan residents, among others, are not counted. For every foreign resident, see foreignResidentsAllCitizenships. null when the citizenship dataset has no row for this comune."New value: +"Sum of foreignResidentsByCitizenship: only the citizenships this site tracks, so a floor, not every foreign resident — Moroccan, Chinese and Indian residents, among others, are not counted. For every foreign resident, see foreignResidentsAllCitizenships. null when the citizenship dataset has no row for this comune."

Changed3 schema fields changedOct 10, 2026

addedOutput schema / properties / foreignResidentsAllCitizenships

Added value: +{
+  "additionalProperties": false,
+  "description": "Residents holding any foreign citizenship: ISTAT's own total, not limited to the 25 citizenships tracked in foreignResidentsByCitizenship. Citizenship, not birthplace. value is null, never 0, when ISTAT sends no total for this comune.",
+  "properties": {
+    "coverage": {
+      "additionalProperties": false,
+      "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+      "properties": {
+        "in": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "of": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "in",
+        "of"
+      ],
+      "type": "object"
+    },
+    "extractedOn": {
+      "description": "ISO date this value was extracted from the source.",
+      "type": "string"
+    },
+    "license": {
+      "type": "string"
+    },
+    "method": {
+      "description": "URL to the methodology page for this dataset.",
+      "type": "string"
+    },
+    "reason": {
+      "description": "Present only when value is null: why this place has no figure.",
+      "type": "string"
+    },
+    "source": {
+      "type": "string"
+    },
+    "unit": {
+      "type": "string"
+    },
+    "value": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "vintage": {
+      "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "value",
+    "unit",
+    "source",
+    "vintage",
+    "extractedOn",
+    "method",
+    "license"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / totalForeignResidents / description

Previous value: -"Sum of foreignResidentsByCitizenship: only the citizenships this site tracks (25), so a floor, not every foreign resident — Romanian, Albanian and Moroccan residents, among others, are not counted. null when the citizenship dataset has no row for this comune."New value: +"Sum of foreignResidentsByCitizenship: only the citizenships this site tracks (25), so a floor, not every foreign resident — Romanian, Albanian and Moroccan residents, among others, are not counted. For every foreign resident, see foreignResidentsAllCitizenships. null when the citizenship dataset has no row for this comune."

changedOutput schema / required

Previous value: -[
-  "place",
-  "population",
-  "foreignResidentsByCitizenship",
-  "totalForeignResidents",
-  "purchasePriceEurM2",
-  "rentPriceEurM2Month",
-  "priceToRentYears",
-  "taxRegimeEligibility",
-  "provinceRollup",
-  "layers",
-  "provinceWellbeing",
-  "attribution"
-]New value: +[
+  "place",
+  "population",
+  "foreignResidentsByCitizenship",
+  "totalForeignResidents",
+  "foreignResidentsAllCitizenships",
+  "purchasePriceEurM2",
+  "rentPriceEurM2Month",
+  "priceToRentYears",
+  "taxRegimeEligibility",
+  "provinceRollup",
+  "layers",
+  "provinceWellbeing",
+  "attribution"
+]

Changed1 schema field changedOct 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "articles": {
+      "description": "Published articles about this comune — the reporting behind the numbers. Credit required to reuse.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "markdownUrl": {
+            "type": "string"
+          },
+          "slug": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "slug",
+          "title",
+          "url",
+          "markdownUrl"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "attribution": {
+      "additionalProperties": false,
+      "properties": {
+        "citeAs": {
+          "description": "A ready-made citation line.",
+          "type": "string"
+        },
+        "page": {
+          "description": "The expatliving.it page these figures come from — link it when you quote them.",
+          "type": "string"
+        },
+        "publisher": {
+          "type": "string"
+        },
+        "request": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "publisher",
+        "url",
+        "citeAs",
+        "request"
+      ],
+      "type": "object"
+    },
+    "foreignResidentsByCitizenship": {
+      "additionalProperties": false,
+      "description": "Counts by ISO-2 citizenship code. Citizenship, not birthplace — excludes foreign-born Italian citizens. value is null, never a zero-filled object, when ISTAT's citizenship dataset has no row at all for this comune.",
+      "properties": {
+        "coverage": {
+          "additionalProperties": false,
+          "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+          "properties": {
+            "in": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "of": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "in",
+            "of"
+          ],
+          "type": "object"
+        },
+        "extractedOn": {
+          "description": "ISO date this value was extracted from the source.",
+          "type": "string"
+        },
+        "license": {
+          "type": "string"
+        },
+        "method": {
+          "description": "URL to the methodology page for this dataset.",
+          "type": "string"
+        },
+        "reason": {
+          "description": "Present only when value is null: why this place has no figure.",
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "value": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "number"
+              },
+              "propertyNames": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "vintage": {
+          "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "value",
+        "unit",
+        "source",
+        "vintage",
+        "extractedOn",
+        "method",
+        "license"
+      ],
+      "type": "object"
+    },
+    "layers": {
+      "description": "Every other map layer's value for this place, at the grain its source publishes. A null value means the source has no figure for this place (see `reason`).",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "coverage": {
+            "additionalProperties": false,
+            "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+            "properties": {
+              "in": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "of": {
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              }
+            },
+            "required": [
+              "in",
+              "of"
+            ],
+            "type": "object"
+          },
+          "download": {
+            "description": "The whole dataset, as published JSON (every place, with its meta block).",
+            "type": "string"
+          },
+          "extractedOn": {
+            "description": "ISO date this value was extracted from the source.",
+            "type": "string"
+          },
+          "grain": {
+            "description": "The level this value is measured at. Only \"comune\" is a measurement of this comune itself.",
+            "enum": [
+              "comune",
+              "province",
+              "region"
+            ],
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "license": {
+            "type": "string"
+          },
+          "measuredFor": {
+            "description": "The place the value describes, e.g. \"L'Aquila (province)\".",
+            "type": "string"
+          },
+          "method": {
+            "description": "URL to the methodology page for this dataset.",
+            "type": "string"
+          },
+          "note": {
+            "description": "The source's own coverage caveat, where it has one.",
+            "type": "string"
+          },
+          "page": {
+            "description": "The map page for this layer on expatliving.it — link readers here.",
+            "type": "string"
+          },
+          "reason": {
+            "description": "Present only when value is null: why this place has no figure.",
+            "type": "string"
+          },
+          "slug": {
+            "description": "The dataset slug, as in GET /datasets.",
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "unit": {
+            "type": "string"
+          },
+          "value": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "vintage": {
+            "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "value",
+          "unit",
+          "source",
+          "vintage",
+          "extractedOn",
+          "method",
+          "license",
+          "slug",
+          "label",
+          "grain",
+          "measuredFor",
+          "page",
+          "download"
+        ],
+        "type": "object"
+      },
+      "maxItems": 100,
+      "type": "array"
+    },
+    "place": {
+      "additionalProperties": false,
+      "properties": {
+        "istatCode": {
+          "description": "6-digit ISTAT comune code, e.g. 075029.",
+          "type": "string"
+        },
+        "lat": {
+          "type": "number"
+        },
+        "lng": {
+          "type": "number"
+        },
+        "name": {
+          "type": "string"
+        },
+        "page": {
+          "description": "This comune's profile page on expatliving.it — link it when you quote any figure below.",
+          "type": "string"
+        },
+        "province": {
+          "type": "string"
+        },
+        "provinceCode": {
+          "type": "string"
+        },
+        "provinceSlug": {
+          "type": "string"
+        },
+        "region": {
+          "type": "string"
+        },
+        "regionSlug": {
+          "type": "string"
+        },
+        "slug": {
+          "description": "Stable URL slug for /data/comune/{slug} — never changes, even if a comune merges.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "istatCode",
+        "slug",
+        "name",
+        "province",
+        "provinceCode",
+        "provinceSlug",
+        "region",
+        "regionSlug",
+        "lat",
+        "lng",
+        "page"
+      ],
+      "type": "object"
+    },
+    "population": {
+      "additionalProperties": false,
+      "properties": {
+        "coverage": {
+          "additionalProperties": false,
+          "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+          "properties": {
+            "in": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "of": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "in",
+            "of"
+          ],
+          "type": "object"
+        },
+        "extractedOn": {
+          "description": "ISO date this value was extracted from the source.",
+          "type": "string"
+        },
+        "license": {
+          "type": "string"
+        },
+        "method": {
+          "description": "URL to the methodology page for this dataset.",
+          "type": "string"
+        },
+        "reason": {
+          "description": "Present only when value is null: why this place has no figure.",
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "value": {
+          "anyOf": [
+            {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "vintage": {
+          "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "value",
+        "unit",
+        "source",
+        "vintage",
+        "extractedOn",
+        "method",
+        "license"
+      ],
+      "type": "object"
+    },
+    "priceToRentYears": {
+      "additionalProperties": false,
+      "description": "Years of rent that equal the purchase price. Not a yield, an ROI, or a payback period.",
+      "properties": {
+        "coverage": {
+          "additionalProperties": false,
+          "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+          "properties": {
+            "in": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "of": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "in",
+            "of"
+          ],
+          "type": "object"
+        },
+        "extractedOn": {
+          "description": "ISO date this value was extracted from the source.",
+          "type": "string"
+        },
+        "license": {
+          "type": "string"
+        },
+        "method": {
+          "description": "URL to the methodology page for this dataset.",
+          "type": "string"
+        },
+        "reason": {
+          "description": "Present only when value is null: why this place has no figure.",
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "value": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "vintage": {
+          "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "value",
+        "unit",
+        "source",
+        "vintage",
+        "extractedOn",
+        "method",
+        "license"
+      ],
+      "type": "object"
+    },
+    "provinceRollup": {
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "purchasePriceEurM2": {
+          "additionalProperties": false,
+          "properties": {
+            "coverage": {
+              "additionalProperties": false,
+              "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+              "properties": {
+                "in": {
+                  "maximum": 9007199254740991,
+                  "minimum": -9007199254740991,
+                  "type": "integer"
+                },
+                "of": {
+                  "maximum": 9007199254740991,
+                  "minimum": -9007199254740991,
+                  "type": "integer"
+                }
+              },
+              "required": [
+                "in",
+                "of"
+              ],
+              "type": "object"
+            },
+            "extractedOn": {
+              "description": "ISO date this value was extracted from the source.",
+              "type": "string"
+            },
+            "license": {
+              "type": "string"
+            },
+            "method": {
+              "description": "URL to the methodology page for this dataset.",
+              "type": "string"
+            },
+            "reason": {
+              "description": "Present only when value is null: why this place has no figure.",
+              "type": "string"
+            },
+            "source": {
+              "type": "string"
+            },
+            "unit": {
+              "type": "string"
+            },
+            "value": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "vintage": {
+              "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "value",
+            "unit",
+            "source",
+            "vintage",
+            "extractedOn",
+            "method",
+            "license"
+          ],
+          "type": "object"
+        },
+        "rentPriceEurM2Month": {
+          "additionalProperties": false,
+          "properties": {
+            "coverage": {
+              "additionalProperties": false,
+              "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+              "properties": {
+                "in": {
+                  "maximum": 9007199254740991,
+                  "minimum": -9007199254740991,
+                  "type": "integer"
+                },
+                "of": {
+                  "maximum": 9007199254740991,
+                  "minimum": -9007199254740991,
+                  "type": "integer"
+                }
+              },
+              "required": [
+                "in",
+                "of"
+              ],
+              "type": "object"
+            },
+            "extractedOn": {
+              "description": "ISO date this value was extracted from the source.",
+              "type": "string"
+            },
+            "license": {
+              "type": "string"
+            },
+            "method": {
+              "description": "URL to the methodology page for this dataset.",
+              "type": "string"
+            },
+            "reason": {
+              "description": "Present only when value is null: why this place has no figure.",
+              "type": "string"
+            },
+            "source": {
+              "type": "string"
+            },
+            "unit": {
+              "type": "string"
+            },
+            "value": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "vintage": {
+              "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "value",
+            "unit",
+            "source",
+            "vintage",
+            "extractedOn",
+            "method",
+            "license"
+          ],
+          "type": "object"
+        },
+        "slug": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "code",
+        "slug",
+        "purchasePriceEurM2",
+        "rentPriceEurM2Month"
+      ],
+      "type": "object"
+    },
+    "provinceWellbeing": {
+      "additionalProperties": false,
+      "description": "ISTAT BES well-being indicators for this comune's province — province-level, not a comune measurement.",
+      "properties": {
+        "coverage": {
+          "additionalProperties": false,
+          "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+          "properties": {
+            "in": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "of": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "in",
+            "of"
+          ],
+          "type": "object"
+        },
+        "extractedOn": {
+          "description": "ISO date this value was extracted from the source.",
+          "type": "string"
+        },
+        "grain": {
+          "const": "province",
+          "type": "string"
+        },
+        "license": {
+          "type": "string"
+        },
+        "measuredFor": {
+          "type": "string"
+        },
+        "method": {
+          "description": "URL to the methodology page for this dataset.",
+          "type": "string"
+        },
+        "page": {
+          "type": "string"
+        },
+        "reason": {
+          "description": "Present only when value is null: why this place has no figure.",
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "value": {
+          "anyOf": [
+            {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "code": {
+                    "type": "string"
+                  },
+                  "domain": {
+                    "type": "string"
+                  },
+                  "label": {
+                    "type": "string"
+                  },
+                  "percentile": {
+                    "description": "0–100 rank among Italy's provinces, polarity-aware: higher is always better, whichever way the raw value runs.",
+                    "type": "number"
+                  },
+                  "polarity": {
+                    "description": "\"high\": a higher raw value is better; \"low\": a lower one is.",
+                    "enum": [
+                      "high",
+                      "low"
+                    ],
+                    "type": "string"
+                  },
+                  "unit": {
+                    "type": "string"
+                  },
+                  "value": {
+                    "description": "The raw indicator value.",
+                    "type": "number"
+                  },
+                  "year": {
+                    "description": "The year this observation describes — indicators update on different cycles.",
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "code",
+                  "domain",
+                  "label",
+                  "unit",
+                  "polarity",
+                  "value",
+                  "year",
+                  "percentile"
+                ],
+                "type": "object"
+              },
+              "maxItems": 80,
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "vintage": {
+          "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "value",
+        "unit",
+        "source",
+        "vintage",
+        "extractedOn",
+        "method",
+        "license",
+        "grain",
+        "measuredFor",
+        "page"
+      ],
+      "type": "object"
+    },
+    "purchasePriceEurM2": {
+      "additionalProperties": false,
+      "properties": {
+        "coverage": {
+          "additionalProperties": false,
+          "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+          "properties": {
+            "in": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "of": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "in",
+            "of"
+          ],
+          "type": "object"
+        },
+        "extractedOn": {
+          "description": "ISO date this value was extracted from the source.",
+          "type": "string"
+        },
+        "license": {
+          "type": "string"
+        },
+        "method": {
+          "description": "URL to the methodology page for this dataset.",
+          "type": "string"
+        },
+        "reason": {
+          "description": "Present only when value is null: why this place has no figure.",
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "value": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "vintage": {
+          "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "value",
+        "unit",
+        "source",
+        "vintage",
+        "extractedOn",
+        "method",
+        "license"
+      ],
+      "type": "object"
+    },
+    "rentPriceEurM2Month": {
+      "additionalProperties": false,
+      "properties": {
+        "coverage": {
+          "additionalProperties": false,
+          "description": "How many of Italy's places this dataset covers at all, e.g. 7587 of 7894 comuni.",
+          "properties": {
+            "in": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "of": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "in",
+            "of"
+          ],
+          "type": "object"
+        },
+        "extractedOn": {
+          "description": "ISO date this value was extracted from the source.",
+          "type": "string"
+        },
+        "license": {
+          "type": "string"
+        },
+        "method": {
+          "description": "URL to the methodology page for this dataset.",
+          "type": "string"
+        },
+        "reason": {
+          "description": "Present only when value is null: why this place has no figure.",
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "value": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "vintage": {
+          "description": "The period the value describes, e.g. \"2025H2\" or \"2025\" — not when it was fetched.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "value",
+        "unit",
+        "source",
+        "vintage",
+        "extractedOn",
+        "method",
+        "license"
+      ],
+      "type": "object"
+    },
+    "taxRegimeEligibility": {
+      "description": "Verified regimes only — \"placesNotPeople\": geographic eligibility, not personal advice.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "headroom": {
+            "description": "Residents between this comune and the ceiling.",
+            "type": "number"
+          },
+          "href": {
+            "description": "Path to this regime's own page on expatliving.it.",
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "maxPopulation": {
+            "description": "The regime's population ceiling, when it has one.",
+            "type": "number"
+          },
+          "ruleIsIncomplete": {
+            "description": "True when the rule admits comuni by routes not yet verified — silence about OTHER regimes proves nothing.",
+            "type": "boolean"
+          },
+          "slug": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "slug",
+          "label",
+          "href",
+          "ruleIsIncomplete"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "totalForeignResidents": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Sum of foreignResidentsByCitizenship: only the citizenships this site tracks (25), so a floor, not every foreign resident — Romanian, Albanian and Moroccan residents, among others, are not counted. null when the citizenship dataset has no row for this comune."
+    }
+  },
+  "required": [
+    "place",
+    "population",
+    "foreignResidentsByCitizenship",
+    "totalForeignResidents",
+    "purchasePriceEurM2",
+    "rentPriceEurM2Month",
+    "priceToRentYears",
+    "taxRegimeEligibility",
+    "provinceRollup",
+    "layers",
+    "provinceWellbeing",
+    "attribution"
+  ],
+  "type": "object"
+}

First observedSep 27, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations only declare readOnly/idempotent/closed-world; the description goes far beyond, disclosing the provenance envelope (source, vintage, extractedOn, license), null semantics ('say why rather than treating it as zero'), and grain/measuredFor semantics warning that province or region values are not measurements of this comune. It also flags that seismicZone is a legal classification with no bearing on tax eligibility — substantial behavioral context an agent could not 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.

Conciseness2/5

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

It is front-loaded with the resource, but the body is a single ~200-word run-on sentence built from stacked em-dashes and nested parentheticals, most notably a sprawling seismicZone aside. Field-level caveats of that length would be better placed in the output schema, and the wall-of-text format hurts scannability.

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?

Despite an output schema existing (so return values need not be explained), the description supplies the interpretation rules an agent needs to quote the data responsibly — grain/measuredFor attribution, vintage repetition, null handling, and the seismicZone caveat. Nothing required to call or correctly report this tool is missing.

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

Parameters3/5

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents istatCode with format and example. The description only restates 'looked up by 6-digit ISTAT code', adding no syntax or edge-case detail beyond the schema. Baseline 3 applies.

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 names the exact resource (one Italian comune's profile) and enumerates the returned content domains — population, foreign residents, property prices, tax-regime eligibility, seismicZone, layers, provinceWellbeing — plus the lookup key. An agent can distinguish this from get_province, find_comuni, and search_comuni 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.

Usage Guidelines3/5

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

Usage is implied by the 'looked up by 6-digit ISTAT code' framing, which positions it as the single-record fetch after discovery via search_comuni/find_comuni, but no sibling is named and no when-not condition is given (e.g. use get_province for province rollups). The description spends its guidance budget on interpretation rules rather than tool routing.

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

All Expat Living Italy tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?