This server provides a standardized interface to search, explore, and retrieve Chilean municipal data from the public SINIM portal.
search_variables: Fuzzy-search ~480 SINIM variables by keyword (e.g. "patentes municipales", "ingresos propios"), with optional filtering by subject area. Matching is accent- and case-insensitive.
get_variable_info: Retrieve full metadata for a specific SINIM variable by its code (e.g. "4173").
get_data: Fetch tidy municipal records for one or more variables, with optional filters for years, municipalities (by CUT codes), region, and monetary correction (real vs. nominal pesos).
list_areas: List all SINIM catalog subject areas (e.g. finance, education, health).
list_municipios: Browse ~345 municipalities, optionally filtered by official Chilean region codes.
list_years: Discover which years have data published in SINIM, dynamically fetched so newly published years appear automatically.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-sinim search variables about education spending"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Busca, descarga y analiza datos municipales de Chile desde el Sistema Nacional de Información Municipal (SINIM), usando Python o cualquier cliente MCP.
mcp-sinim ofrece dos interfaces para consultar el Sistema Nacional de
Información Municipal (SINIM) de Chile:
un cliente síncrono de Python para análisis en notebooks y scripts;
un servidor MCP para agentes de IA y otras aplicaciones compatibles.
Ambas interfaces utilizan el mismo catálogo de variables y entregan datos
municipales ordenados, listos para trabajar con pandas.
Funciones principales:
Buscar cerca de 480 variables por texto, sin memorizar códigos id_dato.
Descargar uno o varios indicadores como paneles municipales ordenados.
Consultar los años y códigos de municipios disponibles en el portal.
Usar el paquete desde Python, notebooks o clientes MCP.
Buscar en una copia local del catálogo y almacenar metadatos en caché.
Related MCP server: Kolada MCP Server
pip install mcp-sinimRequiere Python 3.10 o una versión posterior.
from mcp_sinim import SINIMClient
client = SINIMClient(corrmon=True)
# 1) Buscar el código de una variable
resultados = client.search("patentes municipales")
print(resultados[["code", "name"]].head(3).to_string(index=False))
# 2) Descargar un panel para varios años y municipios
datos = client.get(
["4173", "1311"],
years=[2022, 2023, 2024],
municipios=["13101", "13114", "13123"], # Santiago, Las Condes, Providencia
)
print(datos.head().to_string(index=False))
# 3) Explorar años y municipios
print(client.years()[-5:])
print(client.search_municipios("providencia"))
print(client.municipios(region="13")) # código oficial de la Región Metropolitana
client.close()Las columnas principales del resultado son:
Columna | Contenido |
| Código CUT oficial del municipio. |
| Nombre del municipio. |
| Año de la observación. |
| Código de la variable SINIM. |
| Nombre de la variable. |
| Valor publicado por SINIM. |
| Unidad de medida. |
Métodos principales:
search(...): busca códigos de variables;
get(...): descarga datos municipales;
municipios(...) y search_municipios(...): consulta códigos CUT;
years(): muestra los años disponibles.
Consulta también el notebook de inicio rápido con mapa interactivo en Kepler.gl (Python 3.10–3.12), el ejemplo básico en Python y la guía de usuario en Jupyter.
Si utilizas un asistente con acceso autorizado a la terminal, como Codex, Claude Code, Cursor o Windsurf, puedes pedirle que instale el paquete y registre el servidor en tu cliente MCP. Copia y pega este prompt:
Instala
mcp-sinimdesde PyPI conpython -m pip install --upgrade mcp-sinimy regístralo en mi cliente MCP usando transportestdio, con el comandomcp-sinimy el nombre de servidorsinim. Verifica que el ejecutable exista, que el servidor inicie correctamente y que exponga sus herramientas antes de darlo por terminado. Si el comando no está disponible enPATH, configura su ruta absoluta. No modifiques otras entradas MCP.
El asistente deberá adaptar la ubicación del archivo de configuración al cliente y al sistema operativo que estés utilizando.
Revisa los comandos ejecutados y los cambios realizados en tus archivos de configuración antes de aprobarlos. No compartas credenciales ni concedas permisos adicionales que no sean necesarios.
Reinicia el cliente MCP después de guardar la configuración. Para comprobar la conexión, prueba una solicitud como:
Usa el servidor MCP
sinimpara buscar indicadores relacionados con ejecución presupuestaria municipal.
Después de instalar el paquete, inicia el servidor con:
mcp-sinimConfiguración MCP habitual:
{
"mcpServers": {
"sinim": {
"command": "mcp-sinim"
}
}
}Si el cliente MCP no encuentra el comando, usa la ruta completa del ejecutable
mcp-sinim correspondiente a tu entorno de Python.
Variable de entorno opcional:
MCP_SINIM_CACHE_DIR: directorio para la caché de metadatos.
Herramienta | Descripción |
| Busca variables SINIM por palabras clave. |
| Entrega los metadatos de una variable. |
| Descarga registros para una o varias variables. |
| Previsualiza hasta 100 registros antes de exportar. |
| Exporta un panel completo a Parquet o CSV. |
| Lista las nueve áreas temáticas del catálogo. |
| Lista municipios y permite filtrar por región. |
| Busca municipios por nombre y región. |
| Lista los años disponibles actualmente. |
Ejemplos de solicitudes para un agente conectado al servidor:
Busca variables relacionadas con ingresos propios municipales.
Descarga la variable 4173 para Santiago, Las Condes y Providencia entre 2020 y 2024.
Exporta a Parquet los ingresos por patentes de todos los municipios de la Región Metropolitana.
mcp-sinim permite construir flujos reproducibles para:
analizar ingresos propios, Fondo Común Municipal y ejecución presupuestaria;
comparar gasto, inversión y disponibilidad presupuestaria entre municipios;
estudiar indicadores de educación, salud y gestión municipal;
construir paneles históricos para investigación y políticas públicas;
exportar resultados a CSV o Parquet para Stata, R, Python o Power BI;
crear mapas municipales y conectar agentes de IA con una fuente oficial.
El servidor trabaja con indicadores publicados por SINIM; no entrega registros transaccionales como facturas, proveedores u órdenes de compra.
Los datos provienen del portal oficial SINIM Datos Municipales, administrado por la Subsecretaría de Desarrollo Regional y Administrativo (SUBDERE) del Ministerio del Interior de Chile.
Al utilizar la información, cita como fuente: Sistema Nacional de Información Municipal (SINIM), SUBDERE, Ministerio del Interior.
cod_municipio corresponde a los códigos CUT oficiales de SUBDERE para los
345 municipios presentes en SINIM.
El argumento municipios= recibe esos códigos CUT y los traduce internamente
a los identificadores utilizados por el portal.
Los filtros regionales aceptan los códigos oficiales de Chile ("1" a
"16") y, por compatibilidad, los identificadores internos de SINIM.
corrmon=True solicita la serie en valores reales, expresada en pesos del
último año publicado.
La unidad depende de cada variable. Por ejemplo, M$ significa miles de pesos.
La disponibilidad y cobertura histórica varían entre indicadores.
mcp_sinim/
├── mcp_sinim/ Cliente, catálogo, parsers y servidor MCP
│ └── data/ Copia local del catálogo de variables
├── examples/ Ejemplos, mapa Kepler.gl y guía en Jupyter
├── tests/ Pruebas automatizadas y datos de prueba
├── scripts/ Utilidades de catálogo, publicación y verificación
├── pyproject.toml Configuración del paquete
└── README.md Documentación principalgit clone https://github.com/MaykolMedrano/mcp_sinim
cd mcp_sinim
python -m venv .venv
.venv/Scripts/activate
pip install -e ".[dev]"
python -m ruff check .
python -m ruff format --check .
python -m pytestEn macOS o Linux, activa el entorno con source .venv/bin/activate.
Maykol Medrano Pontificia Universidad Católica de Chile Correo: mmedrano2@uc.cl GitHub: MaykolMedrano
Este proyecto se distribuye bajo la licencia MIT. Es un cliente independiente de código abierto y no está afiliado a SUBDERE ni al Gobierno de Chile. La disponibilidad y exactitud de los datos dependen del servicio público de SINIM.
Write a full SINIM panel to disk instead of the model's context.
Call preview_data first to sanity-check the query shape and coverage.
The export has a generous safety ceiling for pathological or extremely
long-running queries, independent of the in-context response limit.
| Name | Required | Description | Default |
|---|---|---|---|
| codes | Yes | ||
| years | Yes | ||
| format | No | parquet | |
| region | No | ||
| corrmon | No | ||
| municipios | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that data goes to disk and mentions a 'generous safety ceiling' for long-running queries, which adds useful context. However, it does not explain behaviors like file format, destination path, failure modes, or whether the operation is destructive, leaving significant gaps for a write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with a clear main action in the first sentence, a practical prerequisite in the second, and a reassurance about safety. Every sentence contributes value with no wasteful filler, making it well-structured and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no annotations, and only a basic output schema indicator, the description is incomplete. It omits parameter semantics, output location/form, and clear differentiation from get_data. The brief safety note and preview advice are helpful but do not fully cover the tool's operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description never mentions any of the six parameters, including required ones like codes and years. The description provides no additional meaning beyond the schema, failing to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Write a full SINIM panel to disk instead of the model's context.' It distinguishes from siblings like get_data and preview_data by emphasizing output to disk rather than context, and recommends preview_data as a precursor. This is a clear, specific purpose with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the user to call preview_data first for sanity-checking, which is a clear usage guideline. It implies this tool is for large exports that exceed context limits, contrasting with in-context retrieval. However, it does not explicitly enumerate alternatives or state when not to use it, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch municipal data for one or more SINIM variables.
| Name | Required | Description | Default |
|---|---|---|---|
| codes | Yes | SINIM variable codes to fetch (find them with search_variables). | |
| years | Yes | Required years to include (e.g. [2022, 2023]). | |
| region | No | Region id to filter by (see list_municipios). Defaults to all regions. Mutually exclusive with `municipios`. | |
| corrmon | No | Whether to apply monetary correction (real pesos). Defaults to the server's client default (nominal). | |
| municipios | No | Municipality legal codes to keep (e.g. ["13101"]). Defaults to all ~345 municipalities. Mutually exclusive with `region`. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Fetch', which implies a read-only operation, but it does not mention any limits, mutual exclusions, or response structure. The output schema covers return format to some extent, but behavioral traits are otherwise undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise and front-loaded. It avoids unnecessary details, though it lacks structural elements like usage examples. Every word contributes to the core meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has five parameters with mutual exclusions and a set of related sibling tools. The schema is detailed and an output schema exists, so return values are covered. However, the description does not provide overarching context or guidance on how to combine with other tools, making it minimally adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters, so the description adds little beyond the schema. It mentions 'one or more SINIM variables' which aligns with the 'codes' parameter, but does not clarify other parameters or their relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and identifies the resource as 'municipal data for one or more SINIM variables', which clearly states the tool's function. It doesn't explicitly differentiate from sibling tools like preview_data or export_data, but the name 'get_data' and the description imply core data retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as search_variables or preview_data. The description provides no context about appropriate use cases, exclusions, or selection criteria among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full metadata for a single SINIM variable code.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The SINIM variable code (``id_dato``), e.g. "4173". |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It describes a read-only operation ('Get'), but does not disclose potential side effects, authentication requirements, or the exact scope of 'full metadata'. The absence of contradiction but limited detail yields a mid score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence, but it could be more informative without sacrificing conciseness (e.g., mentioning that output includes full metadata fields). Still, it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present), the description is mostly adequate. However, it lacks details on what constitutes 'full metadata' and does not reference the output schema for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'code' already described. The description adds no additional meaning or usage context beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the specific resource ('full metadata for a single SINIM variable code'), distinguishing it from sibling tools like 'get_data' (retrieves data values) and 'search_variables' (finds variables by criteria).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing metadata for a specific variable code, but it does not explicitly state when to prefer this tool over alternatives like 'search_variables' or 'get_data', nor does it provide context on prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all SINIM subject areas (e.g. finance, education, health).
Returns: The distinct area names present in the catalog, sorted.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses that results are distinct area names and sorted, which is sufficient behavioral detail for a read-only list tool. No annotations present, so description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Clearly states purpose and return format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, an output schema, and a simple list operation, the description is fully complete. It specifies what is returned (distinct area names) and how (sorted).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Description does not need to add parameter details, and it appropriately omits them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists all SINIM subject areas with examples (finance, education, health), distinguishing it from siblings like list_municipios or list_years which list other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs alternatives. The simplicity and lack of parameters make it straightforward, but mentioning when to prefer this over other list tools would improve it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List municipalities, optionally filtered by region.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | Official region code (e.g. "13" = Región Metropolitana; a SINIM-internal id like "131" is also accepted). Defaults to all regions (~345 municipalities). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure, but it only states the basic action and filter. It omits details about result volume (~345 municipalities), pagination, or any potential side effects, leaving the agent without important behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence ('List municipalities, optionally filtered by region.') with no filler or redundancy. It is appropriately front-loaded, and every word earns its place for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, one optional parameter, and an existing output schema, the description is adequate. However, it lacks any mention of related tools or output expectations, leaving minor contextual gaps that could confuse an agent choosing between list_municipios and search_municipalities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the 'region' parameter (coverage 100%), so the baseline is 3. The description merely reiterates that filtering is optional, adding no new semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('municipalities') with an optional filter ('by region'), clearly conveying the tool's function. It doesn't explicitly differentiate from sibling 'search_municipalities' but the list vs search distinction is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving municipality lists, optionally scoped by region, but provides no explicit guidance on when to choose this over search_municipalities or list_areas, nor any exclusion criteria. It gives a clear context but no alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the years with data available in SINIM.
Discovered dynamically from the SINIM form, so newly published years appear automatically.
Returns: Available years, ascending (e.g. 2001..2025).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It explains the dynamic discovery and return format (ascending years). Though it doesn't explicitly state read-only safety, it's clear from context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, dynamic discovery detail, return format. No unnecessary words, front-loaded with the main action. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers the essential aspects: what it returns (years ascending), how it works (dynamically discovered), and example range. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so baseline is 4. The description adds value by explaining the output (available years ascending) and the dynamic nature, which is helpful beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the years with data available in SINIM. It uses a specific verb-resource pair ('list years') and distinguishes itself from sibling tools like get_data, list_areas, etc., which focus on other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions dynamic discovery and self-updating, which implies usage context, but does not provide explicit when-to-use or when-not-to-use guidance relative to sibling tools. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a query's shape and coverage before exporting its full result.
Use this bounded preview to check columns, coverage, and sample values,
then call export_data to write the complete panel to disk.
| Name | Required | Description | Default |
|---|---|---|---|
| codes | Yes | ||
| limit | No | ||
| years | Yes | ||
| region | No | ||
| corrmon | No | ||
| municipios | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It does indicate the tool is a bounded preview and contrasts it with export_data which writes to disk, implying it does not write. However, it doesn't mention auth requirements, rate limits, or any side effects beyond the read-only nature, so full transparency is not achieved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences and a line break. It front-loads the core purpose and provides actionable guidance without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema helps with return values, but the tool has six parameters with no schema descriptions and no param explanations in the description. While the purpose and usage are clear, the missing parameter semantics leave a significant gap for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter-level explanations. It only hints at the limit parameter indirectly with 'bounded preview,' but doesn't map any other parameters or provide usage examples. The description does not compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to inspect a query's shape and coverage before full export. It distinguishes itself from the sibling export_data by explicitly recommending export_data for writing the complete panel to disk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this before calling export_data, and provides a clear context: bounded preview for checking columns, coverage, and sample values. It also implies not to use it when you need the full result, which is handled by export_data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-search Chilean municipalities by name, optionally filtered by region.
Matching is accent- and case-insensitive ("nunoa" also finds "ÑUÑOA").
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default 10). | |
| query | Yes | Free-text municipality name (e.g. "santiago", "nunoa"). | |
| region | No | Optional official region code restricting the search (e.g. "13"). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It explicitly states that matching is accent- and case-insensitive, with a concrete example ('nunoa' finds 'ÑUÑOA'). It also uses the term 'fuzzy-search', implying approximate matching. This goes beyond a simple tautology and provides meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary purpose. The second sentence adds a key behavioral detail. No filler or redundant information; every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with an output schema, this description is complete. It states what the tool does, how matching behaves, and the optional region filter. The output schema covers return values, and uncertainty about ordering/pagination is acceptable given the presence of the limit parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 100% of the parameters with descriptions, but the description adds value by explaining the fuzzy/accent-insensitive matching behavior for the query parameter. It also reinforces that region is an optional filter. This enriches the schema's bare definitions without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Fuzzy-search Chilean municipalities by name, optionally filtered by region.' The verb 'fuzzy-search' is specific and distinguishes this from sibling tools like list_municipios, which likely provides a full list rather than a name-based search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the primary use case: when you need to find a municipality by name with fuzzy matching, optionally narrowing by region. It does not explicitly name alternatives or exclusions, but the context is clear enough that an agent would know to use this tool for name-based search rather than listing all municipalities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fuzzy-search SINIM variables by name, optionally filtered by area.
Matching is accent- and case-insensitive ("educacion" also finds "Educación").
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | Optional area-name filter, matched as a substring (e.g. "finanzas", "educacion"). | |
| limit | No | Maximum number of results (default 10). | |
| query | Yes | Free-text search term (e.g. "patentes municipales", "ingresos propios"). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses fuzzy, accent-insensitive, and case-insensitive matching. It doesn't mention side effects or read-only nature, but for a search tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second adds key behavioral detail. No fluff, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists and moderate complexity, description covers search intent and fuzzy behavior. Could mention pagination or sorting, but limit is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by specifying matching behavior (fuzzy, accent-insensitive) beyond the schema, and explains area filter as substring match.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'fuzzy-search' and the resource 'SINIM variables', with optional area filter, clearly distinguishing from sibling tools like get_data or get_variable_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that matching is accent- and case-insensitive, providing useful context for when to use this tool. However, it does not explicitly contrast with alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0export_dataget_data8 fields changedInput schema / properties / municipios / descriptionPrevious value: -"Municipality legal codes to keep (e.g. [\"13101\"]).\nDefaults to all ~345 municipalities."New value: +"Municipality legal codes to keep (e.g. [\"13101\"]).\nDefaults to all ~345 municipalities. Mutually exclusive with\n`region`."Input schema / properties / region / descriptionPrevious value: -"Region id to filter by (see list_municipios). Defaults to\nall regions."New value: +"Region id to filter by (see list_municipios). Defaults to\nall regions. Mutually exclusive with `municipios`."Input schema / properties / years / anyOfRemoved value: -[
- {
- "items": {
- "type": "integer"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
-]Input schema / properties / years / defaultRemoved value: -nullInput schema / properties / years / descriptionPrevious value: -"Years to include (e.g. [2022, 2023]). Defaults to ALL\navailable years — prefer passing an explicit list to keep the\nresponse small."New value: +"Required years to include (e.g. [2022, 2023])."Input schema / properties / years / itemsAdded value: +{
+ "type": "integer"
+}Input schema / properties / years / typeAdded value: +"array"Input schema / requiredPrevious value: -[
- "codes"
-]New value: +[
+ "codes",
+ "years"
+]list_municipios1 field changedInput schema / properties / region / descriptionPrevious value: -"Region id to filter by (e.g. \"131\" = Región\nMetropolitana). Defaults to all regions (~345 municipalities)."New value: +"Official region code (e.g. \"13\" = Región Metropolitana; a\nSINIM-internal id like \"131\" is also accepted). Defaults to all\nregions (~345 municipalities)."preview_datasearch_municipalitiesv0.1.0get_dataget_variable_infolist_areaslist_municipioslist_yearssearch_variablesScored across 9 tools
Most tools have clearly distinct purposes (listing vs searching vs fetching), but list_municipios and search_municipalities overlap significantly as both return municipalities, differing only in fuzzy matching. The data-related tools (get_data, preview_data, export_data) are distinct but could confuse at a glance.
The verb_noun pattern is mostly followed (list_*, search_*, get_*, preview_data, export_data), but there is an inconsistency with list_municipios using Spanish while search_municipalities uses English, and get_variable_info breaks the simple verb_noun form.
9 tools is well-scoped for a data catalog focused on discovery, search, and retrieval. Each tool serves a distinct step in the workflow without redundancy.
The tool set covers the full lifecycle of exploring and exporting SINIM data: discovering areas, municipalities, years, and variables, then fetching, previewing, and exporting. No critical gaps for the stated domain.
Financial data, credit scores, and economic indicators for 14,800+ U.S. municipalities.
INEGI MCP — Mexico's national statistics office (INEGI) Indicators API.
Query 29,500+ World Bank development indicators for 200+ countries across 60+ years.
IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.
