# Dashboards — armá tu propio panel de funnel

Cómo construir un **dashboard en vivo del funnel** de tu agente pidiéndoselo a Claude,
usando **solo las tools MCP que ya tenés**. Sin SQL, sin repos, sin hosting. El resultado
se renderiza como un **Artifact interactivo** (o, si preferís algo rápido, una tabla en el
chat). Todo queda automáticamente acotado a tus propios agentes (RLS), así que nunca ves
datos de otro creador.

Esto es exactamente lo que el equipo de Ninjō corre internamente, pero armado sobre los
datos que la gateway ya te expone. No hace falta ninguna tool nueva.

---

## 1. Los datos que ya tenés (qué tool da qué)

| Tool | Devuelve | Para el dashboard |
|------|----------|-------------------|
| `get_agent_metrics` (`days`, `min_leads`, `influencer_id?`) | Agregados KPI por agente: `leads`, `avg_funnel`, `bookings_sent`, `booking_send_rate`, `calls_booked`, `call_book_rate_total`, `pct_funnel_ge_4`, `risk_score_0_100` | Los **KPI cards** de arriba + ranking de riesgo entre agentes |
| `get_agent_insights` (`days`, `influencer_id?`) | `quick_stats` (`new_conversations_24h`, `qualified_leads_24h`, `bookings_sent_24h`), `funnel_transitions` (`transition`, `rate`), `content_sources` (`source`, `total_conversations`, `qualified_leads`, `bookings_sent`, `qualified_rate`), `hot_leads`, `stalled_by_objection` | El **embudo por etapa** + el desglose **por fuente de contenido** + a quién seguir |
| `get_conversations` (`mode`, `limit`) / `search_conversations` (filtros) | Una fila por conversación con `meta` (`funnel` 0–5, `booking_link_sent`, `call_booked`, `lead_score`, `first_message_at`, `last_message_at`) | Un funnel **a medida**, una **tabla de keywords**, o una etapa que los agregados no cubren |

Regla práctica: `get_agent_insights` + `get_agent_metrics` alcanzan para el 90% de los
dashboards. Bajás a `search_conversations` solo cuando querés una etapa o un corte que los
agregados no traen (por keyword, por rango fino, por una property específica).

---

## 2. El funnel estándar (mapeado a campos reales)

```
convos  →  calificado  →  link enviado  →  agendó / compró
```

| Etapa | De dónde sale |
|-------|---------------|
| convos | `get_agent_metrics.leads` (o `content_sources[].total_conversations`) |
| calificado | `quick_stats.qualified_leads_24h`, o `funnel ≥ 2` vía `search_conversations(min_funnel: 2)` |
| link enviado | `bookings_sent` / `booking_send_rate` (o `has_booking_link: true`) |
| agendó / compró | `calls_booked` / `call_book_rate_total` (o `call_booked: true`) |

Ojo con dos cosas al leer `get_conversations` / `search_conversations`:
`meta.booking_link_sent` y `meta.call_booked` llegan como **strings** (`"true"`), no como
booleanos. Contá como verdadero si el valor es `"true"` / `"1"` / `"yes"`. Y `funnel` es una
escala **0–5**, no un booleano de "calificado": elegí siempre un umbral explícito (≥2, ≥4).

---

## 3. La receta (lo que hace Claude)

1. Elegí la ventana en días (por defecto 30).
2. `get_agent_insights(days)` para un agente: te da `funnel_transitions`, `content_sources`
   y `quick_stats`.
3. `get_agent_metrics(days)` para los KPIs agregados de ese mismo agente.
4. (Opcional) `search_conversations(min_funnel, has_booking_link, call_booked, fechas...)`
   si querés una tabla de keywords o una etapa a medida.
5. Renderizá como **Artifact**: KPI cards arriba, barras del embudo en el medio, tabla por
   fuente de contenido abajo. Un solo archivo, **autocontenido** (datos embebidos inline, sin
   fetch externo ni CDNs), responsive.

Si el creador solo quiere el número rápido, saltá el Artifact y devolvé una tabla markdown.

---

## 4. Cómo pedirlo (ejemplos)

Ejemplos de lo que el creador puede pedir:

- "Armame un dashboard del funnel de [agente] de los últimos 30 días."
- "Hacé un panel en vivo con mis KPIs, el embudo por etapa y la conversión por fuente de contenido."
- "Mostrame el funnel de la última semana como tabla, y las top keywords por conversión."

Podés describir las etapas del funnel a tu gusto (esto es un "spec" conceptual, no un archivo):

- etapa `calificado` ← `funnel ≥ 2`
- etapa `link enviado` ← `booking_send_rate` / `has_booking_link`
- etapa `agendó` ← `call_booked`

---

## 5. Scope y multi-agente

Todo se acota solo a tus agentes (RLS): no necesitás pasar ningún filtro para ver únicamente
lo tuyo. Si manejás varias cuentas (agencia), pasá el `influencer_id` (o el header
`X-Influencer-Id`) para elegir sobre cuál construir el dashboard.

---

## 6. Gotchas

- **Las properties pueden mentir.** Si una property de "enviado/completado" no es confiable,
  medí el **entregable real**: buscá la conversación donde el link efectivamente salió
  (`search_conversations(has_booking_link: true)`, o el patrón del link en el contenido del
  mensaje). El número honesto es "el link se mandó", no "la property dice que sí".
- **`funnel` es 0–5**, no "calificado". Elegí el umbral (≥2, ≥4) y decilo en el dashboard.
- **Cuidado con los denominadores de las tasas de agenda.** `call_book_rate_total` =
  `calls_booked / leads`; `call_book_rate_per_booking_observed` = `calls_booked / bookings_sent`.
  Son números distintos: mostrá cuál estás usando.
- **No inventes números.** Si una tool no devuelve un dato, decilo; no lo rellenes con una
  estimación disfrazada de dato.
- **El dashboard es un Artifact en vivo**, se regenera cada vez que lo pedís. No es una URL
  hosteada que puedas guardar en favoritos. Si necesitás un panel persistente y compartible,
  pedíselo al equipo de Ninjō.

---

## Relacionado

- `mcp-tool-reference.md` — el mapa completo de lo que puede la gateway MCP.
- `agent-metrics.md` — el mismo funnel vía SQL directo (uso interno del equipo, con acceso a la DB).