Tools de crm
El dominio crm es el embudo comercial de un tenant:
cuentas, oportunidades y su máquina de estados por etapas. Cada
tool es una cáscara fina sobre una RPC — la autorización, la
máquina de estados y las validaciones viven en la base
(crm.*), nunca acá. Corre con tu propia
sesión, nunca con una clave de servicio:
ctx.db solo expone asUser, así que
ninguna tool puede saltear la RLS de pg-dynamo-<env>.
El embudo (etapas y transiciones) es DATO del tenant, no
del producto. Dos clientes con procesos comerciales
distintos son dos sets de filas distintos. Antes de
crm_move_opportunity, consultá
crm_pipeline_config para ver los code de
etapa que ese tenant eligió — no hay un set universal. Antes de
crm_initialize_tenant, la app crm tiene
que estar habilitada en el proyecto y el usuario tener acceso —
eso es auth_set_project_app y
auth_set_app_access (ver tools
de auth), los pasos 1-2 del alta de un cliente.
Un id ajeno devuelve el mismo error que "no existe".
Mover una oportunidad sin la capacidad pipeline.escribir_todo
da el mismo resultado que un id inventado — es deliberado, para no
confirmar que el id existe. crm_configure_stages y
crm_configure_transitions no llevan gate propio: la
autorización vive en las policies de crm.etapas/
crm.etapa_transiciones (capacidad
etapas.administrar) — sin ella, la base responde
42501, nunca una lista vacía.
Lectura (9)
| Tool | Qué hace | Inputs | Qué permiso hace falta | Ejemplo de prompt |
|---|---|---|---|---|
crm_tenant_status |
Dice qué le falta a un tenant para ser usable: si está
inicializado, si tiene roles, usuarios con rol, etapas y
transiciones. Que falten etapas y transiciones recién dado
de alta NO es un error — es el trabajo de configuración
del admin del tenant. Devuelve ["sin acceso"]
sin revelar si el tenant existe cuando el que llama no
tiene entitlement.
|
tenant_project_id (uuid) |
Sesión autenticada con acceso al proyecto. | "¿Qué le falta al tenant Acme para poder operar?" |
crm_search_accounts |
Busca cuentas del tenant por razón social, nombre
comercial, NIT o alias, y dice por cuál de los cuatro
coincidió. El NIT se compara normalizado (sin separadores
ni dígito de verificación). El nombre nunca es llave: para
operar sobre una cuenta usá el cuenta_id que
devuelve.
|
tenant_project_id (uuid) ·
q (texto) ·
limit (entero, opcional)
|
Sesión autenticada con acceso al proyecto. | "Buscá la cuenta 'FIC 48' en el CRM de Acme." |
crm_my_pending |
Las próximas acciones comprometidas DEL QUE LLAMA, vencidas o por vencer dentro de N días (7 por defecto). Sale de la bitácora, no de una columna que alguien tiene que acordarse de actualizar. Solo la vista propia, no la del equipo. |
tenant_project_id (uuid) ·
dias (entero, opcional)
|
Sesión autenticada con acceso al proyecto. | "¿Qué tengo pendiente esta semana en el CRM?" |
crm_pipeline_summary |
Resumen del embudo por etapa: cantidad, valor total y valor
ponderado (calculado en vivo con la probabilidad de la
etapa del tenant). Con la capacidad
pipeline.leer_todo es el embudo del tenant
entero; sin ella, solo el propio — RLS decide, la tool no
distingue.
|
tenant_project_id (uuid) |
Sesión autenticada con acceso al proyecto. | "Dame el resumen del embudo del tenant Acme." |
crm_list_opportunities |
Las oportunidades del embudo, fila por fila, con la cuenta,
el sector, el contacto principal y la próxima acción
comprometida ya resueltos. Filtros: etapas para
una columna del kanban, responsable_user_id
para la vista de una persona, incluir_terminales:
false para esconder ganadas/perdidas, q
para buscar por cuenta/código/número/descripción. Un filtro
ausente significa "no filtres", nunca "no devuelvas nada".
Paginado: cada fila trae cursor_siguiente,
opaco — no lo construyas ni lo interpretes.
|
tenant_project_id (uuid) ·
q/etapas/responsable_user_id/incluir_terminales/limit/cursor
(todos opcionales)
|
Sesión autenticada con acceso al proyecto. | "Mostrame las oportunidades del tenant Acme en la etapa 'negociación'." |
crm_pipeline_config |
La configuración del embudo de un tenant: etapas,
transiciones y lo que todavía le falta para ser usable.
Consultala ANTES de mover una oportunidad en vez de
adivinar los code de etapa.
|
tenant_project_id (uuid) |
Sesión autenticada con acceso al proyecto. | "¿Qué etapas tiene configuradas el embudo de Acme?" |
crm_list_catalog |
Los valores ACTIVOS de un catálogo del tenant (por ejemplo
sectores, soluciones,
propuestas — el tipo es texto
libre, no hay un set fijo). Un valor eliminado deja de
aparecer acá pero no se borra de la base (ver
crm_manage_catalog).
|
tenant_project_id (uuid) ·
tipo (texto)
|
Sesión autenticada con acceso al proyecto. | "Dame el catálogo de sectores del tenant Acme." |
crm_get_handoff |
El handoff de UNA oportunidad ganada: objetivo, compromisos,
riesgos, checklist, responsable y los documentos de soporte
ya adjuntados (contrato/ans/cámara de comercio/rut/propuesta).
Devuelve null si la oportunidad todavía no ganó
o si no hay acceso — nunca distingue los dos casos.
|
tenant_project_id (uuid) ·
oportunidad_id (uuid)
|
Visibilidad = la de la oportunidad (RLS de la policy, no un gate propio de la tool). | "Mostrame el handoff de la oportunidad X." |
Escritura (8)
Confirmá el ambiente con dynamo_session_status (ver
tools de ops) antes de cualquiera de estas.
| Tool | Qué hace | Inputs | Qué permiso hace falta | Ejemplo de prompt |
|---|---|---|---|---|
crm_initialize_tenant |
Da de alta un tenant del CRM: crea su configuración y un
rol administrador. Paso 3 del alta de un cliente (1-2 son
de auth) — exige que ese entitlement YA exista, no lo
otorga. Hace lo MÍNIMO a propósito: no crea etapas ni
catálogos, eso lo decide el cliente. NO es idempotente: si
el tenant ya está inicializado, falla.
El project_id es distinto en QA y en
prod para el mismo cliente: nunca reuses uno.
|
tenant_project_id (uuid) ·
nombre (texto) ·
admin_user_id (uuid)
|
Solo global-admin. | "Dá de alta el tenant CRM para el proyecto Acme." |
crm_move_opportunity |
Mueve una oportunidad de etapa por la máquina de estados DEL TENANT. La transición tiene que estar declarada por ese tenant y la etapa destino puede exigir requisitos. Escribe el evento en la bitácora en la misma transacción. Mover a la etapa en la que ya está es idempotente y no hace nada. |
opportunity_id (uuid) ·
etapa (texto, el code del tenant) ·
nota (texto, opcional)
|
Capacidad pipeline.escribir_todo (o ser el
responsable de la oportunidad).
|
"Movéme la oportunidad X a la etapa 'negociación'." |
crm_register_event |
Registra un evento en la bitácora de una oportunidad —
típicamente la próxima acción comprometida (llamada, visita,
propuesta) y su fecha, SIN mover de etapa. Es la mitad
simétrica de crm_move_opportunity, que ya
escribe un evento pero solo al transicionar.
proxima_accion y fecha son
obligatorias: sin ellas crm_my_pending no tiene
de dónde sacar el próximo compromiso.
|
tenant_project_id (uuid) ·
opportunity_id (uuid) ·
proxima_accion (texto) ·
fecha (texto) ·
tipo/nota (opcionales)
|
Capacidad pipeline.escribir (propia) o
pipeline.escribir_todo (ajena).
|
"Registrá que voy a llamar al cliente de la oportunidad X el viernes." |
crm_create_opportunity |
Crea una oportunidad en el embudo de un tenant. Nace en la
ETAPA INICIAL que definió ese tenant (la de menor orden que
no sea terminal), no en un code universal — no
existe tal cosa. El responsable es SIEMPRE quien llama, sin
parámetro para crear a nombre de otro. Si el tenant todavía
no definió etapas, falla pidiendo crm_configure_stages
primero, en vez de un error de integridad.
|
tenant_project_id (uuid) ·
descripcion (texto) ·
cuenta_id/etapa_code/valor_antes_iva/periodicidad_dias/numero_visible
(opcionales)
|
Capacidad pipeline.escribir. |
"Creá una oportunidad para la cuenta FIC 48 por $5.000.000 mensuales." |
crm_configure_stages |
Define (crea o actualiza) las etapas del embudo de un tenant. NO borra: retirar una etapa con oportunidades ya cargadas es otra operación. Un array vacío falla en vez de no hacer nada en silencio. |
tenant_project_id (uuid) ·
etapas (array de
{code, nombre, probabilidad?, orden?, es_terminal?},
mínimo 1)
|
Capacidad etapas.administrar. |
"Configurá las etapas del embudo de Acme: Prospecto, Calificado, Propuesta, Cerrado." |
crm_configure_transitions |
Define qué movimientos son legales entre etapas. Sin
transiciones ninguna oportunidad puede moverse — esta tool
y crm_configure_stages son lo que vuelve
usable un tenant recién dado de alta. Las dos etapas
tienen que existir: un desde inventado da un
error de integridad, nunca una transición fantasma.
|
tenant_project_id (uuid) ·
transiciones (array de
{desde, hasta}, mínimo 1)
|
Capacidad etapas.administrar. |
"Permití pasar de 'Prospecto' a 'Calificado' y de 'Calificado' a 'Propuesta'." |
crm_manage_catalog |
Agrega o retira UN valor de un catálogo del tenant y
devuelve el catálogo completo ya actualizado.
accion: "agregar" requiere valor;
accion: "eliminar" requiere id
(el que devuelve crm_list_catalog). Eliminar
es SIEMPRE SOFT (activo = false): un valor ya
usado por una cuenta u oportunidad no se destruye, solo
deja de ofrecerse para elegir de nuevo. Reagregar un valor
retirado lo reactiva en vez de duplicarlo.
|
tenant_project_id (uuid) ·
tipo (texto) ·
accion (enum: agregar | eliminar) ·
valor/id (según la acción)
|
Capacidad catalogo.administrar. |
"Agregá 'Retail' al catálogo de sectores del tenant Acme." |
crm_update_handoff |
Actualiza uno o varios campos de un handoff ya creado (objetivo/compromisos/riesgos/checklist/responsable) y devuelve la fila completa. Un campo omitido conserva su valor actual — no hace falta reenviar los que no cambian. |
tenant_project_id (uuid) ·
oportunidad_id (uuid) ·
objetivo/compromisos/riesgos/checklist/responsable_user_id
(todos opcionales)
|
Capacidad handoff.escribir (rol "operaciones",
o el que el tenant le haya dado esa capacidad). Un comercial
sin ella recibe 42501, no un cambio parcial.
|
"Actualizá el objetivo del handoff de la oportunidad X." |
crm_attach_handoff_document |
Adjunta (o reemplaza) UN documento manual de soporte de un
handoff: tipo es contrato,
ans (Acuerdo de Nivel de Servicio),
camara_comercio o rut — un enlace
simple, sin subida de archivo. propuesta NO se
acepta acá: esa la adjunta automático el Constructor.
Reagregar el mismo tipo reemplaza el enlace, no
duplica la fila.
|
tenant_project_id (uuid) ·
oportunidad_id (uuid) ·
tipo (enum) ·
url (texto) ·
nombre (opcional)
|
Capacidad handoff.escribir. |
"Adjuntá el contrato de la oportunidad X: [url]." |
Para errores concretos de estas tools: Troubleshooting.
Para correr los MCPs en stdio localmente en vez del
gateway: Para desarrolladores.