# Contract: Herramienta `agregar_contratos_multicliente` (agent_database)

**Feature**: `007-contratos-multicliente-multipunto`
**Consumer**: `AgentDatabaseQueryCapabilityHandler` → `AgentCommercialQueryService`
**Connection**: `agent_db_secondary`

## Protocol

```json
{
  "query_name": "agregar_contratos_multicliente",
  "parameters": {
    "operacion": "count",
    "agrupar_por": ["localidad_suministro", "mes_contrato"]
  }
}
```

## Tool: `agregar_contratos_multicliente`

| Property | Value |
|----------|-------|
| Description | Cuenta y/o agrega (suma, promedio, mín, máx) contratos MultiCliente MultiPunto (TipProCom=3) agrupando por hasta dos dimensiones. Todos los registros; sin truncar cálculo. |
| COUNT | `COUNT(DISTINCT CodProCom)` |
| FR | FR-007–FR-009, FR-010–FR-013 |

### Parameters

Paridad con `agregar_contratos_unicliente`:

| Param | Descripción |
|-------|-------------|
| `operacion` | `count` \| `suma` \| `promedio` \| `minimo` \| `maximo` |
| `medida` | `consumo_electrico`, `consumo_gas`, `potencia_p1`…`p6` (si operación numérica) |
| `metricas` | Array opcional de varias métricas |
| `agrupar_por` | 0–2 dimensiones (ver data-model.md) |
| `termino`, `localidad`, `tipo_energia`, `fec_desde`, `fec_hasta` | Filtros |
| `orden` | `total_desc` \| `total_asc` \| `dim_asc` |
| `limite` | Top-N presentación (alta cardinalidad) |

### Dimensiones permitidas

`localidad_suministro`, `localidad_representante`, `localidad_cliente_empresa`,
`provincia_suministro`, `provincia_representante`, `provincia_cliente_empresa`,
`direccion_suministro`, `mes_contrato`, `anio_contrato`,
`tarifa_electrica`, `tarifa_gas`, `tipo_energia`,
`representante`, `cliente_empresa`, `estado`,
`bucket_consumo_electrico`, `bucket_consumo_gas`.

### Response shape

```json
{
  "query_name": "agregar_contratos_multicliente",
  "operacion": "count",
  "agrupar_por": ["localidad_suministro"],
  "rows": [{ "localidad_suministro": "Madrid", "total": 120 }],
  "total_general": [{ "metrica": "total", "valor": 450 }],
  "truncated": false,
  "hay_mas": false
}
```

### Reglas

- `truncated` **siempre** `false`.
- Alta cardinalidad: `representante`, `cliente_empresa`, `direccion_suministro`.

## Routing hints

"cuántos contratos multicliente por", "distribución contratos multicliente", "consumo total multicliente por", "representante con más contratos" (con agregación).