# Contract: Herramienta `listar_contratos_multicliente` (agent_database)

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

## Protocol

LLM turno 1:

```json
{ "query_name": "listar_contratos_multicliente", "parameters": { "vista": "listado" } }
```

## Tool: `listar_contratos_multicliente`

| Property | Value |
|----------|-------|
| Description | Lista o detalla contratos MultiCliente MultiPunto (TipProCom=3): representante legal/contacto, cliente empresa vinculado y datos de suministro (CUPS, tarifas, potencias, consumos). Excluye Unicliente (TipProCom 1 y 2). Orden por fecha de contrato desc. |
| Scope | `TipProCom = 3` exclusivamente; **INNER JOIN** `T_Contrato` por `CodProCom` (solo formalizados) |
| Eloquent path | `PropuestaComercialCups` → `whereHas(propuestaComercial, TipProCom=3)` + `contacto` + `leftJoin detalle→cliente` + suministro |
| FR | FR-001–FR-006, FR-010–FR-013 |

### Parameters

| Param | Tipo | Default | Descripción |
|-------|------|---------|-------------|
| `vista` | string | `listado` | `listado` (agrupado por contrato) \| `detalle` (una fila por CUPS) |
| `termino` | string | — | Filtro en representante (NIF, nombre, email, tel, dirección) **o** cliente empresa (nombre, CIF, email, tel, dirección). |
| `direccion_suministro` | string | — | Filtro dirección punto de suministro. |
| `cups` | string | — | CUPS eléctrico o gas. |
| `tarifa` | string | — | Nombre tarifa eléctrica o gas. |
| `tipo_energia` | string | — | `electrico` \| `gas` |
| `localidad` | string | — | Localidad suministro, representante o cliente empresa. |
| `fec_desde` / `fec_hasta` | date | — | Rango `FecProCom`. |
| `orden` | string | `fecha_desc` | `fecha_desc` \| `fecha_asc` |
| `limite` | int | — | Acotado por `contratos_multicliente.max_rows`. |

### Límite de filas

- **NO** usa `max_results` (50).
- Usa `agent.agent_database.contratos_multicliente.max_rows` (default 500).

### Response shape

Igual patrón que `listar_contratos_unicliente`: `rows`, `truncated`, `count`. Vista listado agrupa por `CodProCom` con `puntos_suministro` anidados; incluye campos de representante y cliente empresa en cabecera de contrato.

## Routing hints

"contratos multicliente", "multicliente multipunto", "representante legal contratos", "listar contratos tipprocom 3".