Tool reference
Energetica exposes 8 tools across three groups: 5 curated query tools, 2 discovery tools, and 1 raw SQL tool. All tools return JSON serialized as text.
Curated queries
query_production
Monthly oil, gas and water production by basin, company, formation and time period (~18M records).
| Param | Type | Notes |
|---|---|---|
cuenca | string | Basin filter (e.g. NEUQUINA, GOLFO SAN JORGE, CUYANA, AUSTRAL) |
empresa | string | Operating company (e.g. YPF, PAN AMERICAN ENERGY, VISTA, TECPETROL) |
formacion | string | Geological formation (e.g. VACA MUERTA, D-129, CENTENARIO) |
fecha_desde | string | YYYY-MM |
fecha_hasta | string | YYYY-MM |
agrupar_por | enum | mes | anio | cuenca | empresa | formacion (default mes) |
recurso | enum | petroleo | gas | agua | todos (default todos) |
Returns: fecha, prod_petroleo_m3, prod_gas_miles_m3, prod_agua_m3, pozos_activos
query_wells
Search ~50,000 Argentine oil & gas wells with location, type, status, depth and cumulative production.
| Param | Type | Notes |
|---|---|---|
empresa | string | Operating company filter (ILIKE) |
cuenca | string | Basin filter |
provincia | string | Province (NEUQUEN, CHUBUT, MENDOZA, etc.) |
tipo_recurso | enum | PETROLEO | GAS | AMBOS |
tipo_estado | string | Activo | Inactivo | Abandonado |
formacion | string | Geological formation |
con_produccion | boolean | Only wells with cumulative production > 0 |
limit | number | 1-1000 (default 100) |
Returns: idpozo, sigla, nombre_propio, empresa, provincia, cuenca, area_concesion, formacion, tipo_pozo, tipo_estado, latitud, longitud, profundidad, petroleo_acumulado_m3, gas_acumulado_miles_m3, fecha_primera_prod
query_prices
International benchmark prices, Argentine local crude, and FX rates.
| Param | Type | Notes |
|---|---|---|
serie | enum | Required. WTI, BRENT, HENRY_HUB, ESCALANTE, MEDANITO, USD_OFICIAL, USD_BLUE, USD_MEP, USD_CCL |
fecha_desde | string | YYYY-MM-DD (intl/FX) or YYYY-MM (local crude) |
fecha_hasta | string | Same format as fecha_desde |
frecuencia | enum | diario | mensual | anual |
query_investments
Upstream oil & gas investments in Argentina by company, basin, year and concept (MMUSD).
| Param | Type | Notes |
|---|---|---|
empresa | string | Company filter (ILIKE) |
cuenca | string | Basin filter |
anio_desde | number | Start year |
anio_hasta | number | End year |
concepto | string | perforacion, terminacion, infraestructura, etc. |
query_trade
Argentina hydrocarbon trade balance — exports/imports of crude, refined products and gas.
| Param | Type | Notes |
|---|---|---|
anio | number | Filter by year |
flow | enum | export | import |
producto | enum | crude (HS 2709) | refined (HS 2710) | gas (HS 2711) |
Discovery
get_schema
Returns table names, columns, types, descriptions, units and example values. Use this first to understand what's available.
| Param | Type | Notes |
|---|---|---|
tabla | string | Optional. Specific table name. Omit for all tables. |
Cached for 1 hour (the schema only changes on pipeline rebuild).
get_data_freshness
Date range and row count per table. No parameters. Cached for 1 hour.
SQL escape hatch
execute_sql
Available on Professional tier and above. Execute arbitrary read-only SQL (SELECT or WITH only) against the DuckDB database.
| Param | Type | Notes |
|---|---|---|
sql | string | SELECT or WITH statement |
Validation:
- Blocks DDL/DML (DROP, ALTER, INSERT, UPDATE, DELETE, CREATE, GRANT, REVOKE)
- Blocks dangerous patterns (UNION, INFORMATION_SCHEMA, SLEEP, BENCHMARK, LOAD_FILE)
- Whitelisted to tables in the catalog only
- 30-second timeout per query
- Auto-injects LIMIT (5,000-10,000 depending on tier) if missing
Error responses
Tool errors return isError: true with a human-readable message:
- Timeout — query exceeded 30s. Suggests adding more filters.
- Circuit breaker open — DB temporarily unavailable.
- SQL validation — query rejected by validator.
- Tier restricted — execute_sql called from a non-Pro tier.