Referencia de tools MCP¶

Esta referencia se genera desde los docstrings y las firmas de src/garua/mcp_tools/*.py.

Para actualizarla:

python scripts/generate_tools_reference.py

Si buscas una guía por tarea, empieza por las páginas de docs/guides/. Esta página sirve como inventario técnico de las tools disponibles para MCP.

Vista general (21 tools)¶

Flujo	Tools relacionadas
Buscar estaciones	`search_stations`, `filter_stations_*`, `find_stations_near`
Confirmar metadatos	`get_station_info`, `check_data_availability`
Descargar datos	`scrape_station_data`
Revisar archivos locales	`list_downloaded_files`, `read_csv_preview`, `extract_month_from_csv`
Analizar datos	`summarize_station_data_tool`, `compare_periods_tool`, `detect_anomalies_tool`
Explorar inventario	`stations_count`, `stations_summary`, `get_departments_summary`, `get_location_hierarchy`

Índice de tools¶

Grupo	Tool	Parámetros
Calidad de datos	`detect_anomalies_tool`	`station_code`, `year`, `month`, `start_year`, `end_year`, `checks`, `severity`, `auto_download`, `trace_policy`
Comparación	`compare_periods_tool`	`station_code`, `periods`, `metrics`, `aggregation`, `deduplicate`, `auto_download`
Descarga	`scrape_station_data`	`station_code`, `mode`, `year`, `month`, `start_year`, `end_year`, `individual`, `periods`, `force_download`
Archivos CSV	`extract_month_from_csv`	`year`, `month`, `station_name`, `station_code`, `station_type`, `station_category`, `source_file`, `overwrite`
Archivos CSV	`list_downloaded_files`	`station_name`, `station_code`, `station_type`, `station_category`, `year`, `month`, `csv_dir`, `include_covering_files`, `mcp_response`
Archivos CSV	`read_csv_preview`	`file_path`, `relative_path`, `station_name`, `station_code`, `station_type`, `station_category`, `year`, `month`, `max_rows`, `max_columns`
Recomendación	`recommend_station_for_point_tool`	`lat`, `lon`, `radius_km`, `station_type`, `target_altitude`, `prefer_status`, `min_years_available`, `limit`
Estaciones	`check_data_availability`	`station_code`, `before_year`, `after_year`
Estaciones	`export_all_stations_csv`	`overwrite`
Estaciones	`filter_stations_advanced`	`department`, `province`, `station_type`, `status`, `min_altitude`, `max_altitude`, `data_before_year`
Estaciones	`filter_stations_by_altitude`	`min_altitude`, `max_altitude`
Estaciones	`filter_stations_by_location`	`department`, `province`, `district`
Estaciones	`find_stations_near`	`lat`, `lon`, `radius_km`, `station_type`
Estaciones	`get_all_stations`	`limit`, `offset`
Estaciones	`get_station_info`	`code`
Estaciones	`search_stations`	`query`
Inventario	`get_departments_summary`	sin parámetros
Inventario	`get_location_hierarchy`	sin parámetros
Inventario	`stations_count`	sin parámetros
Inventario	`stations_summary`	sin parámetros
Resumen	`summarize_station_data_tool`	`station_code`, `year`, `month`, `start_year`, `end_year`, `metrics`, `include_quality`, `auto_download`, `trace_policy`

Detalle por grupo¶

Calidad de datos¶

detect_anomalies_tool

Detecta anomalías y problemas de calidad en datos SENAMHI descargados para una estación y periodo.

Prompt de ejemplo

Valida la calidad de datos de julio 2025 para la estación 108047

Cuándo usarla. Úsala para auditoría de calidad; no reemplaza resumen ni comparación.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`station_code`	`str`	Sí	`—`	Código interno de la estación SENAMHI (ej: '107008', '100090').
`year`	`int \| None`	No	`None`	Año específico a analizar (ej: 2025).
`month`	`int \| None`	No	`None`	Mes específico (1-12). Requiere year.
`start_year`	`int \| None`	No	`None`	Año inicial del periodo a analizar.
`end_year`	`int \| None`	No	`None`	Año final del periodo a analizar.
`checks`	`list[str] \| None`	No	`None`	Lista opcional de checks a ejecutar. Si es None, usa checks por defecto según el esquema detectado.
`severity`	`Literal['all', 'info', 'warning', 'critical']`	No	`'all'`	Filtro de severidad: all, info, warning o critical. Por defecto all.
`auto_download`	`bool`	No	`False`	Si True, intenta resolver faltantes automáticamente. Actualmente no implementado.
`trace_policy`	`Literal['as_0_05', 'as_0', 'as_null']`	No	`'as_0_05'`	Política para T en precipitación: as_0_05, as_0 o as_null. Por defecto as_0_05.

Comparación¶

compare_periods_tool

Compara dos o más periodos de datos de una estación SENAMHI con esquema autodetectado.

Prompt de ejemplo

Compara marzo 2025 vs marzo 2026 para la estación 108047

Cuándo usarla. Úsala solo para dos o más periodos de una misma estación.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`station_code`	`str`	Sí	`—`	Código interno de la estación SENAMHI (ej: '107008', '100090'). Obténlo primero con search_stations.
`periods`	`list[dict]`	Sí	`—`	Lista de periodos a comparar. Cada periodo debe tener: - label: Etiqueta descriptiva (ej: 'Diciembre 2024') - year: Año (ej: 2024) - month: Mes opcional (1-12) Ejemplo: [{'label': 'Dic 2024', 'year': 2024, 'month': 12}, {'label': 'Dic 2025', 'year': 2025, 'month': 12}]
`metrics`	`list[str] \| None`	No	`None`	Métricas específicas a calcular. Si es None, usa todas las disponibles. Métricas meteorológicas convencionales: temp_max_avg, temp_min_avg, humidity_avg, precip_total, rainy_days, max_daily_precip Métricas meteorológicas automáticas: temp_avg, temp_max, temp_min, humidity_avg, precip_total, rainy_hours, rainy_days, wind_speed_avg, wind_speed_max, wind_direction_avg Métricas hidrológicas: river_level_avg, river_level_max, river_level_min, precip_total, rainy_hours, rainy_days
`aggregation`	`str`	No	`'auto'`	Tipo de agregación. Usar 'auto' (por ahora único valor soportado).
`deduplicate`	`bool`	No	`True`	Si True, elimina registros duplicados basándose en fecha/hora antes de calcular. Recomendado: True.
`auto_download`	`bool`	No	`False`	Si True, intenta descargar datos faltantes automáticamente. Actualmente no implementado - los datos deben existir localmente.

Descarga¶

scrape_station_data

Descarga datos históricos del SENAMHI para una estación y los guarda como CSV.

Prompt de ejemplo

Descarga julio 2025 de la estación 108047

Cuándo usarla. Descarga datos; no resume ni valida. Luego usa preview, resumen, comparación o validación.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`station_code`	`str`	Sí	`—`	Código interno de la estación (ej: '100090'). Usa search_stations primero si no tienes el código.
`mode`	`str \| None`	No	`None`	Modo de descarga: 'month' = un mes específico (requiere year + month), 'year' = un año completo (requiere year), 'period' = rango de años (requiere start_year + end_year). Opcional si se usa el parámetro 'periods'.
`year`	`int \| None`	No	`None`	Año (ej: 2025). Requerido para mode='month' o mode='year'.
`month`	`int \| None`	No	`None`	Mes como número (1-12). Requerido para mode='month'.
`start_year`	`int \| None`	No	`None`	Año de inicio del rango. Requerido para mode='period'.
`end_year`	`int \| None`	No	`None`	Año de fin del rango. Requerido para mode='period'.
`individual`	`bool`	No	`False`	True = genera un CSV por mes. False (por defecto) = CSV consolidado.
`periods`	`list[ScrapingPeriod] \| None`	No	`None`	Lista de periodos específicos a descargar en una sola sesión de navegador (MÁS EFICIENTE para múltiples meses). Cada periodo debe tener 'year' y 'month'. Máximo 12 periodos. Ejemplo: [{'year': 2025, 'month': 3}, {'year': 2026, 'month': 3}]. Si se provee, ignora mode/year/month/start_year/end_year. BENEFICIO: Abre el navegador UNA SOLA VEZ en lugar de N veces.
`force_download`	`bool`	No	`False`	Si True, fuerza la descarga incluso si ya existe un archivo para ese periodo. Útil para obtener datos actualizados o corregidos. Por defecto: False.

Archivos CSV¶

extract_month_from_csv

Extrae un mes desde un CSV anual o multianual y crea un CSV mensual.

Prompt de ejemplo

Extrae julio 2025 desde el CSV consolidado de la estación 108047

Cuándo usarla. Úsala cuando un mes está dentro de un CSV anual o multianual.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`year`	`int`	Sí	`—`	Año a extraer.
`month`	`int`	Sí	`—`	Mes a extraer (1-12).
`station_name`	`str \| None`	No	`None`	Nombre de la estación, por ejemplo 'Cajabamba'.
`station_code`	`str \| None`	No	`None`	Código de estación. Recomendado para evitar ambigüedad.
`station_type`	`str \| None`	No	`None`	Tipo de estación: M para meteorológica, H para hidrológica.
`station_category`	`str \| None`	No	`None`	Categoría de estación, por ejemplo CO, EMA, HLM, EHA.
`source_file`	`str \| None`	No	`None`	Archivo origen opcional. Puede ser filename dentro de la carpeta de estación o relative_path devuelto por list_downloaded_files.
`overwrite`	`bool`	No	`False`	Si True, sobrescribe el CSV mensual si ya existe.

list_downloaded_files

Lista archivos CSV descargados localmente por Garúa.

Prompt de ejemplo

Lista archivos descargados para la estación 108047 en 2025

Cuándo usarla. Úsala para confirmar si ya existen CSV locales antes de analizar.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`station_name`	`str \| None`	No	`None`	Nombre de la estación para filtrar (ej: 'Cabana', 'Cachicadan'). Si se omite, lista todas.
`station_code`	`str \| None`	No	`None`	Código interno de la estación SENAMHI (ej: '107008', '100090') para filtrar. Obténlo primero con search_stations. Requiere station_name si se especifica.
`station_type`	`str \| None`	No	`None`	Tipo de estación para filtrar (M para meteorológica, H para hidrológica). Requiere station_name si se especifica.
`station_category`	`str \| None`	No	`None`	Categoría de estación para filtrar (ej: EMA, CO). Requiere station_name si se especifica.
`year`	`int \| None`	No	`None`	Año para filtrar archivos que contengan datos de ese año (ej: 2025).
`month`	`int \| None`	No	`None`	Mes para filtrar archivos individuales (1-12). Requiere year si se especifica.
`csv_dir`	`str \| None`	No	`None`	Ruta del directorio CSV para listar archivos (opcional). Por defecto busca en la carpeta de salida configurada.
`include_covering_files`	`bool`	No	`True`	Si es True, incluye archivos consolidados que cubren rangos de años, incluso si no son específicos del año/mes filtrado. Por defecto False.
`mcp_response`	`bool`	No	`True`	Si True, devuelve una respuesta MCP completa. Por defecto False.

read_csv_preview

Muestra una vista previa tabular de un CSV descargado localmente.

Prompt de ejemplo

Muestra una vista previa del CSV de julio 2025 para la estación 108047

Cuándo usarla. Úsala para inspeccionar columnas y una muestra de filas antes de calcular métricas.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`file_path`	`str \| None`	No	`None`	Ruta completa o relativa del CSV dentro de la carpeta CSV de Garua. Recomendado usar el campo path devuelto por list_downloaded_files.
`relative_path`	`str \| None`	No	`None`	Ruta relativa legacy del CSV dentro de la carpeta CSV de Garua (ej: 'Cajabamba_107008_M_CO/Cajabamba-2025.csv'). Se mantiene por compatibilidad; prefiere file_path.
`station_name`	`str \| None`	No	`None`	Nombre de la estación para búsqueda automática del CSV.
`station_code`	`str \| None`	No	`None`	Código de estación para búsqueda precisa del CSV. Recomendado si hay estaciones con el mismo nombre.
`station_type`	`str \| None`	No	`None`	Tipo de estación: M para meteorológica, H para hidrológica.
`station_category`	`str \| None`	No	`None`	Categoría de estación, por ejemplo CO, EMA, HLM, EHA.
`year`	`int \| None`	No	`None`	Año a mostrar/filtrar dentro del CSV.
`month`	`int \| None`	No	`None`	Mes a filtrar dentro del CSV (1-12). Requiere year.
`max_rows`	`int`	No	`20`	—
`max_columns`	`int`	No	`20`	—

Recomendación¶

recommend_station_for_point_tool

Recomienda las mejores estaciones SENAMHI para un punto geográfico dado.

Prompt de ejemplo

Recomienda una estación para lat -7.61, lon -77.82 con altitud 3000 msnm

Cuándo usarla. Úsala cuando la selección de estación debe justificarse por criterios múltiples.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`lat`	`float`	Sí	`—`	Latitud del punto de interés en grados decimales. Negativo para el hemisferio Sur.
`lon`	`float`	Sí	`—`	Longitud del punto de interés en grados decimales. Negativo para el oeste.
`radius_km`	`float`	No	`100.0`	Radio máximo de búsqueda en kilómetros. Por defecto 100 km.
`station_type`	`Literal['M', 'H', 'all']`	No	`'M'`	Tipo de estación: 'M' (meteorológica), 'H' (hidrológica), 'all' (ambas). Por defecto 'M'.
`target_altitude`	`float \| None`	No	`None`	Altitud del proyecto o punto de interés en metros sobre el nivel del mar (msnm). Si se proporciona, las estaciones con altitud similar tendrán mejor score.
`prefer_status`	`list[str] \| None`	No	`None`	Lista de estados operativos en orden de prioridad. Ejemplo: ['REAL', 'AUTOMATICA', 'DIFERIDO']. Si no se especifica, usa prioridades por defecto.
`min_years_available`	`int \| None`	No	`None`	Mínimo de años de datos históricos requeridos. Excluye estaciones con menos años de historial. Ejemplo: 5 para proyectos que requieren series largas.
`limit`	`int`	No	`5`	Cantidad máxima de recomendaciones a devolver. Por defecto 5, máximo 20.

Estaciones¶

check_data_availability

Consulta desde cuándo hay datos históricos disponibles para estaciones SENAMHI.

Prompt de ejemplo

¿Desde cuándo hay datos para la estación 108047?

Cuándo usarla. Úsala antes de descargar o comparar periodos históricos.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`station_code`	`str \| None`	No	`None`	Código de una estación específica (ej: '100090'). Si se provee, retorna info de esa estación.
`before_year`	`int \| None`	No	`None`	Filtra estaciones con datos disponibles ANTES de este año (ej: 2010 para series largas).
`after_year`	`int \| None`	No	`None`	Filtra estaciones con datos disponibles DESPUÉS de este año (ej: 2022 para series recientes).

export_all_stations_csv

Exporta el catálogo completo de estaciones SENAMHI a un archivo CSV.

Prompt de ejemplo

Exporta el catálogo completo de estaciones a CSV

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`overwrite`	`bool`	No	`True`	Si es True, regenera el CSV aunque ya exista. Si es False, reutiliza el archivo existente cuando esté disponible.

filter_stations_advanced

Filtra estaciones SENAMHI combinando varios criterios en una sola consulta.

Prompt de ejemplo

Busca estaciones meteorológicas activas en Puno sobre 3500 msnm

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`department`	`str \| None`	No	`None`	Departamento del Perú (ej: 'Arequipa', 'Puno'). Case-insensitive, parcial.
`province`	`str \| None`	No	`None`	Provincia (ej: 'Caylloma'). Case-insensitive, parcial.
`station_type`	`str \| None`	No	`None`	Tipo: 'M' = meteorológica, 'H' = hidrológica. Omitir para ambos.
`status`	`str \| None`	No	`None`	Estado operativo: 'REAL' (transmisión en tiempo real), 'DIFERIDO', 'AUTOMATICA'.
`min_altitude`	`float \| None`	No	`None`	Altitud mínima en msnm.
`max_altitude`	`float \| None`	No	`None`	Altitud máxima en msnm.
`data_before_year`	`int \| None`	No	`None`	Solo estaciones con datos disponibles desde ANTES de este año (para series largas).

filter_stations_by_altitude

Filtra estaciones SENAMHI por rango de altitud en msnm.

Prompt de ejemplo

Busca estaciones sobre 3000 msnm

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`min_altitude`	`float \| None`	No	`None`	Altitud mínima en metros sobre el nivel del mar (msnm). Ej: 3000 para zonas altoandinas.
`max_altitude`	`float \| None`	No	`None`	Altitud máxima en msnm. Ej: 500 para zonas costeras o valles bajos.

filter_stations_by_location

Filtra estaciones SENAMHI por ubicación administrativa del Perú.

Prompt de ejemplo

Busca estaciones en Arequipa, provincia Caylloma

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`department`	`str \| None`	No	`None`	Nombre del departamento (ej: 'Cajamarca', 'Arequipa'). Case-insensitive, parcial.
`province`	`str \| None`	No	`None`	Nombre de la provincia (ej: 'Contumaza', 'Caylloma'). Case-insensitive, parcial.
`district`	`str \| None`	No	`None`	Nombre del distrito. Case-insensitive, parcial.

find_stations_near

Encuentra estaciones SENAMHI cercanas a un punto geográfico.

Prompt de ejemplo

Busca estaciones cerca de lat -7.61, lon -77.82

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`lat`	`float`	Sí	`—`	Latitud del punto central en grados decimales (ej: -9.5, -13.5). Negativo para el hemisferio Sur.
`lon`	`float`	Sí	`—`	Longitud del punto central en grados decimales (ej: -77.5, -76.3). Negativo para el oeste.
`radius_km`	`float`	No	`50.0`	Radio de búsqueda en kilómetros. Por defecto 50 km.
`station_type`	`str`	No	`'all'`	Tipo de estación: 'all' (todas), 'M' (meteorológicas), 'H' (hidrológicas).

get_all_stations

Devuelve una página del catálogo de estaciones SENAMHI disponibles.

Prompt de ejemplo

Lista las primeras estaciones disponibles

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`limit`	`int`	No	`100`	Cantidad máxima de estaciones a devolver en esta página. Usa export_all_stations_csv si necesitas el catálogo completo.
`offset`	`int`	No	`0`	Cantidad de estaciones a omitir antes de devolver resultados.

get_station_info

Obtiene la ficha completa de una estación SENAMHI por código.

Prompt de ejemplo

Dame la ficha de la estación 108047

Cuándo usarla. Úsala después de buscar cuando necesites confirmar metadatos de una estación.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`code`	`str`	Sí	`—`	Código interno de la estación (ej: '100090', '153209'). Obtenlo primero con search_stations si no lo tienes.

search_stations

Busca estaciones SENAMHI por código o por nombre.

Prompt de ejemplo

Busca estaciones llamadas Cabana

Cuándo usarla. Úsala antes de descargar o analizar cuando el código de estación no esté confirmado.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`query`	`str`	Sí	`—`	Código exacto de la estación (ej: '100090') o nombre parcial (ej: 'Cabana', 'Juli'). La búsqueda por nombre es case-insensitive y admite coincidencias parciales.

Inventario¶

get_departments_summary

Devuelve estadísticas de estaciones agrupadas por departamento del Perú.

Prompt de ejemplo

¿Qué departamentos tienen más estaciones?

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Sin parámetros.

get_location_hierarchy

Devuelve la jerarquía administrativa de ubicaciones con conteos de estaciones.

Prompt de ejemplo

Muestra la jerarquía de ubicaciones con estaciones

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Sin parámetros.

stations_count

Devuelve el número total de estaciones SENAMHI disponibles en el catálogo local.

Prompt de ejemplo

¿Cuántas estaciones tienes disponibles?

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Sin parámetros.

stations_summary

Devuelve un resumen global de estaciones por tipo y estado operativo.

Prompt de ejemplo

Resume el inventario de estaciones por tipo y estado

Cuándo usarla. Revisa la guía de usuario relacionada antes de usarla en flujos largos.

Parámetros

Sin parámetros.

Resumen¶

summarize_station_data_tool

Resume datos SENAMHI de una estación para un mes, año o periodo individual.

Prompt de ejemplo

Resume julio 2025 para la estación 108047

Cuándo usarla. Úsala para un solo periodo. Para dos o más periodos usa comparación.

Parámetros

Parámetro	Tipo	Requerido	Default	Descripción
`station_code`	`str`	Sí	`—`	Código interno de la estación SENAMHI (ej: '107008', '100090'). Obténlo primero con search_stations o get_station_info.
`year`	`int \| None`	No	`None`	Año específico a resumir (ej: 2025).
`month`	`int \| None`	No	`None`	Mes específico (1-12). Requiere year.
`start_year`	`int \| None`	No	`None`	Año inicial si se resume un rango de años.
`end_year`	`int \| None`	No	`None`	Año final si se resume un rango de años.
`metrics`	`list[str] \| None`	No	`None`	Métricas específicas a calcular. Si es None, usa las del esquema detectado. Meteorológica convencional: temp_max_avg, temp_min_avg, humidity_avg, precip_total, rainy_days, dry_days, missing_days, trace_days, max_daily_precip Meteorológica automática: temp_avg, precip_total, rainy_hours, rainy_days, dry_hours, wind_speed_avg, wind_speed_max Hidrológica: river_level_avg/max/min, precip_total, rainy_hours
`include_quality`	`bool`	No	`True`	Si True, incluye diagnóstico resumido de calidad reutilizando validate_dataset (duplicados, S/D, T, fechas faltantes).
`auto_download`	`bool`	No	`False`	Si True, intenta descargar datos faltantes. Actualmente no implementado — los datos deben existir localmente.
`trace_policy`	`Literal['as_0_05', 'as_0', 'as_null']`	No	`'as_0_05'`	Política para trazas T en precipitación: as_0_05 (default), as_0 o as_null.