# Contract: Agent Database Tools (agent_database)

**Feature**: `002-agent-db-clients-contracts`  
**Consumer**: `AgentDatabaseQueryCapabilityHandler` → `AgentCommercialQueryService`  
**Connection**: `agent_db_secondary`

## Protocol (unchanged)

LLM turn 1 returns JSON:

```json
{ "query_name": "<tool>", "parameters": { "key": "value" } }
```

Or direct answer:

```json
{ "answer": "..." }
```

Turn 2: LLM interprets query results into natural language (Spanish).

## Tool catalog

### `buscar_clientes`

| Property | Value |
|----------|-------|
| Description | Busca clientes empresa por nombre, NIF, email, teléfono o dirección |
| Parameters | `termino` (string, use `%` for partial) |
| Eloquent path | `Cliente::query()->where(...)` + optional `contactoDetalleCliente.contacto` |
| FR | FR-003 |

### `buscar_contactos`

| Property | Value |
|----------|-------|
| Description | Busca contactos/representantes por nombre, NIF, email, teléfono, cargo o dirección |
| Parameters | `termino` (string) |
| Eloquent path | `Contacto` + `detallesCliente.cliente` |
| FR | FR-003 |
| Note | Replaces legacy name `buscar_representantes_contactos` (alias kept for compat) |

### `listar_propuestas_por_cliente`

| Property | Value |
|----------|-------|
| Description | Lista propuestas comerciales (contratos) de un cliente empresa |
| Parameters | `cod_cli` (int) OR `termino` (string, resolves client first) |
| Eloquent path | `Cliente` → `PropuestaComercialCliente` → `PropuestaComercial` WHERE `TipProCom=2` |
| FR | FR-004, FR-005 |

### `listar_propuestas_por_contacto`

| Property | Value |
|----------|-------|
| Description | Lista propuestas comerciales (contratos) de un contacto |
| Parameters | `cod_con_cli` (int) OR `termino` (string) |
| Eloquent path | `Contacto` → `PropuestaComercialCliente` → `PropuestaComercial` WHERE `TipProCom=3` |
| FR | FR-004, FR-005 |

### `detalle_propuesta`

| Property | Value |
|----------|-------|
| Description | Detalle de una propuesta/contrato con titular y estado |
| Parameters | One of: `cod_pro_com` (int), `ref_pro_com` (string), `id_oferta` (string) |
| Eloquent path | `PropuestaComercial` with `propuestaComercialCliente` + titular by `TipProCom` |
| FR | FR-005, FR-006 |

### `listar_cups_propuesta`

| Property | Value |
|----------|-------|
| Description | CUPs / líneas de suministro de una propuesta |
| Parameters | `cod_pro_com` (int, required) |
| Eloquent path | `PropuestaComercial` → `PropuestaComercialCliente` → `PropuestaComercialCups` |
| FR | FR-014 |

### `detalle_formalizacion`

| Property | Value |
|----------|-------|
| Description | Datos de formalización en T_Contrato si existen |
| Parameters | `cod_pro_com` (int) |
| Eloquent path | `Contrato::where('CodProCom', ...)` with `propuestaComercial` |
| FR | FR-005 (secondary) |

## Error codes (runtime)

| Code | Meaning |
|------|---------|
| `agent_db_unreachable` | Connection failed |
| `agent_query_unknown` | Invalid query_name |
| `agent_query_invalid_params` | Missing/invalid parameters |
| `agent_query_no_results` | Empty result (LLM should explain to user) |

## Response shape (internal, to LLM)

Array of associative objects (JSON-encoded rows). Max `agent.agent_database.max_results` rows (default 50).

## Backward compatibility

Legacy tools in `config/agent.php` (`buscar_representantes_contactos`, `listar_clientes`) map to new service methods or aliases during migration.