Expat Living Italy

Find comuni by criteria

find_comuni

Read-onlyIdempotent

Which Italian comuni match: region, province, population range, purchase-price and rent ranges (OMI), population change 2019–2025, and/or the verified comuni of a tax regime. Paged (max 100) and sortable. A comune with no price, rent or population-change figure is left out of the filter on it and COUNTED in missingData — never treated as cheap, free or stable; say how many were left out. The taxRegime filter lists only comuni on the regime's verified routes: a comune missing from it is NOT a 'no' (the response says so in taxRegime.note). Rows carry plain numbers; their source and vintage are in figures. Use search_comuni to turn a town name into a code, get_comune for one town's full profile.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`q`	No	Only comuni whose name contains this (case- and accent-insensitive).
`sort`	No	Sort key. A comune without a figure for the sort key always sorts last.	population
`limit`	No	Rows per page, 1–100. Default 25.
`order`	No	Default: desc for population and populationChange, asc for name, purchasePrice and rent.
`offset`	No	Rows to skip, for the next page.
`region`	No	A region name or slug, e.g. "Abruzzo" or "valle-d-aosta".
`province`	No	A province's two-letter code ("AQ") or slug ("l-aquila").
`taxRegime`	No	A verified geographic regime slug from /tax/regimes. Lists only comuni on the regime's verified routes; a comune missing from the list is NOT a "no" (the rule may admit comuni by routes not yet encoded).
`maxPopulation`	No	Residents, inclusive.
`minPopulation`	No	Residents, inclusive.
`maxRentEurM2Month`	No	Rent in EUR/m2 per month, inclusive. A comune with no rent figure is left out.
`minRentEurM2Month`	No	Rent in EUR/m2 per month, inclusive. A comune with no rent figure is left out.
`maxPurchasePriceEurM2`	No	Purchase price in EUR/m2, inclusive. A comune with no price is left out, never treated as cheap.
`minPurchasePriceEurM2`	No	Purchase price in EUR/m2, inclusive. A comune with no price is left out, never treated as cheap.
`maxPopulationChangePct`	No	Population change 2019 to 2025, in percent, inclusive.
`minPopulationChangePct`	No	Population change 2019 to 2025, in percent, inclusive. A negative value means decline.

Output Schema

TableJSON Schema

Name	Required	Description
`limit`	Yes
`total`	Yes	Comuni matching every filter, before paging.
`offset`	Yes
`applied`	Yes	The filters and sort as understood, with region and province resolved to their canonical names.
`figures`	Yes
`hasMore`	Yes
`results`	Yes
`returned`	Yes
`taxRegime`	No	Present only when taxRegime was filtered on.
`nextOffset`	Yes	Pass as offset for the next page; null on the last page.
`attribution`	Yes
`missingData`	Yes	One entry per figure you filtered on: how many comuni were left out for having no figure.

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 9, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations by disclosing the null-handling contract: comuni lacking a price, rent or population-change figure are excluded from that filter and counted in `missingData`, never treated as cheap/free/stable. It also explains that taxRegime lists only verified routes and that absence is not a 'no'. This is exactly the behavioral context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

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

Front-loaded with the filter list, then the critical caveats, then sibling routing. Dense and essentially waste-free, though the repeated null-handling explanation for price/rent is slightly verbose given the schema already states it per-parameter.

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?

An output schema exists, so return values need no explanation, and the description still adds the `missingData` and `taxRegime.note` semantics an agent needs to interpret results correctly. For a 16-parameter, zero-required query tool, nothing material 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?

With 100% schema coverage the baseline is 3, but the description adds output-side meaning: rows carry plain numbers whose source and vintage live in `figures`, and paging caps at 100. It largely mirrors the schema's own inclusive/exclusion notes, so it earns credit above baseline without being indispensable.

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?

Opens with a precise verb+resource: 'Which Italian comuni match' followed by the exact filterable dimensions (region, province, population, OMI price/rent ranges, population change, tax regime). An agent can immediately tell this is a multi-criteria filtered query and distinguish it from get_comune and search_comuni.

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?

Explicitly routes the agent to alternatives: 'Use search_comuni to turn a town name into a code, get_comune for one town's full profile.' It also states the intended usage pattern for paging/sorting and warns that the taxRegime filter is not exhaustive, so a missing comune must not be read as a negative.

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?