Ir al contenido
Base de conocimiento

Herramientas de grupos de encuestados — Referencia de herramientas MCP

Las herramientas de grupos gestionan conjuntos reutilizables de encuestados para las campañas. Los grupos pueden crearse manualmente o generarse a partir de una estrategia de muestreo para obtener muestras representativas. Los grupos generados por una estrategia llevan un seguimiento de su puntuación de calidad, registran los ajustes de selección con los que se generaron (tamaño solicitado, factor de sobremuestreo, algoritmo de selección, exigencia de correo electrónico, exclusiones) y pueden actualizarse con esos mismos ajustes a medida que cambia la base de encuestados. La estrategia en sí no contiene ajustes de selección, de modo que una misma estrategia puede alimentar grupos de distintos tamaños.

Lista todos los grupos de encuestados, opcionalmente filtrados por proyecto o por nombre.

Parámetro Tipo Obligatorio Predeterminado Descripción
project_id string No — Filtra por ID de proyecto
name string No — Filtro por subcadena, sin distinguir mayúsculas y minúsculas
limit integer No 100 Número máximo de resultados que se devuelven

Devuelve: { data: [...], count, limit }. Cada elemento incluye source_type, source_strategy_id, respondent_count, quality_score y los cinco ajustes de selección (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids), todos null en un grupo sin selección registrada (grupos manuales, combinados o divididos).


Obtiene un grupo de encuestados por su ID, con la lista completa de encuestados y los detalles de calidad.

Parámetro Tipo Obligatorio Predeterminado Descripción
pool_id string Sí — UUID del grupo

Devuelve: el objeto completo del grupo con id, name, description, project_id, source_type, source_strategy_id, respondent_ids, respondent_count, los cinco ajustes de selección (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids; null cuando no hay ninguna selección registrada), quality_score, quality_details, generated_at.

requested_size es lo que pidió la selección; respondent_count es cuántos miembros tiene realmente el grupo. Es legítimo que difieran: por el sobremuestreo, por la falta de encuestados elegibles o por ediciones manuales posteriores.


Crea un nuevo grupo de encuestados (tipo de origen manual).

Parámetro Tipo Obligatorio Predeterminado Descripción
name string Sí — Nombre del grupo
description string No — Descripción del grupo
project_id string No — Proyecto en el que se organiza
respondent_ids string[] No — IDs iniciales de los encuestados

Devuelve: { id, name, description, project_id, respondent_count }


Añade encuestados a un grupo existente. Los duplicados se omiten sin avisar.

Un grupo contiene solo encuestados de su propio proyecto, de modo que cualquiera que pueda leer el grupo puede leer a todos sus miembros. Se rechaza un encuestado de otro proyecto, aunque usted pueda leerlo. En una organización que comparte su panel de encuestados, y en un grupo sin proyecto, puede añadirse cualquier encuestado de la organización.

Parámetro Tipo Obligatorio Predeterminado Descripción
pool_id string Sí — UUID del grupo
respondent_ids string[] Sí — IDs de los encuestados que se añaden

Devuelve:

{
"pool_id": "...",
"added": 8,
"duplicates_skipped": 2,
"new_total": 50
}

Quita encuestados de un grupo.

Parámetro Tipo Obligatorio Predeterminado Descripción
pool_id string Sí — UUID del grupo
respondent_ids string[] Sí — IDs de los encuestados que se quitan

Devuelve:

{
"pool_id": "...",
"removed": 3,
"not_found": 1,
"new_total": 47
}

Selecciona un nuevo grupo de encuestados a partir de una estrategia de muestreo. El algoritmo de selección elige encuestados que se ajustan a las distribuciones demográficas objetivo de la estrategia. Aquí los ajustes de selección son entradas, no propiedades de la estrategia, y el nuevo grupo los guarda para que cada actualización repita la selección de la misma manera.

Parámetro Tipo Obligatorio Predeterminado Descripción
strategy_id string Sí — UUID de la estrategia de muestreo
pool_name string Sí — Nombre del nuevo grupo
description string No — Descripción del grupo
project_id string No — ID del proyecto. De forma predeterminada, el proyecto de la estrategia
requested_size integer Sí — Número de encuestados que se quiere obtener con esta selección, antes del sobremuestreo (> 0)
oversample_factor float No 1.0 Margen para la falta de respuesta sobre requested_size (≥ 1; p. ej., 1.2 = 20 % adicional)
selection_algorithm string No "greedy" "greedy" o "random_constrained"
require_email boolean No false Solo son elegibles los encuestados con dirección de correo electrónico
exclude_respondent_ids string[] No [] UUID de encuestados que nunca son elegibles para esta selección (p. ej., los de una oleada anterior)

Los ajustes no válidos (un tamaño de 0, un sobremuestreo inferior a 1, un algoritmo desconocido, una exclusión que no es un UUID de encuestado) se rechazan antes de leer ningún encuestado.

La selección solo considera a los encuestados del proyecto al que pertenece el nuevo grupo, de modo que un grupo nunca incorpora encuestados que los demás propietarios del proyecto no puedan ver. Lo mismo se aplica cuando el grupo se actualiza, sea quien sea quien lo actualice. En una organización que comparte su panel de encuestados, y en un grupo sin proyecto, la selección considera todo el panel.

Ejemplo:

{
"strategy_id": "...",
"pool_name": "Urban Millennials — main wave",
"requested_size": 200,
"oversample_factor": 1.2
}

Devuelve:

{
"pool_id": "...",
"pool_name": "Urban Millennials — main wave",
"strategy_id": "...",
"respondent_count": 240,
"requested_size": 200,
"effective_size": 240,
"quality_score": 0.94,
"quality_details": { },
"computation_time_ms": 145,
"warnings": []
}

effective_size es requested_size × oversample_factor (redondeado hacia abajo), el número al que apunta la selección. Cuando hay muy pocos encuestados elegibles, el grupo recibe menos miembros y warnings incluye un mensaje de déficit que nombra ambos tamaños, por ejemplo Could not fill the draw: 90 of 120 drawn (requested 100 x oversample 1.2); only 90 candidates eligible.

El grupo creado tiene source_type: "strategy" y guarda el source_strategy_id y los ajustes de selección para actualizarlo más adelante. Para seleccionar con otro tamaño, genere otro grupo a partir de la misma estrategia.


Previsualiza la generación de un grupo sin crearlo. Ejecuta la misma selección que generate_pool_from_strategy y devuelve las métricas de calidad.

Parámetro Tipo Obligatorio Predeterminado Descripción
strategy_id string Sí — UUID de la estrategia de muestreo
project_id string No — El proyecto al que pertenecería el grupo, igual que en generate_pool_from_strategy. De forma predeterminada, el proyecto de la estrategia
max_preview integer No 100 Número máximo de IDs de encuestados que se incluyen en la previsualización

También admite los mismos ajustes de selección que generate_pool_from_strategy: requested_size (obligatorio), oversample_factor, selection_algorithm, require_email, exclude_respondent_ids.

Devuelve:

{
"eligible_count": 500,
"requested_size": 200,
"effective_size": 200,
"selected_count": 200,
"quality_score": 0.94,
"quality_details": { },
"sample_respondent_ids": ["..."],
"computation_time_ms": 130,
"warnings": []
}

Vuelve a seleccionar, sin cambiar su identidad, un grupo generado por una estrategia frente a la base de encuestados actual. Solo funciona con grupos que tienen source_type: "strategy". La actualización no recibe ajustes de selección: repite la selección con el tamaño solicitado, el factor de sobremuestreo, el algoritmo, la exigencia de correo electrónico y las exclusiones que el grupo guardó al generarse, frente a los factores actuales de la estrategia. Para cambiar el tamaño, genere un grupo nuevo y asígnelo a la campaña.

Parámetro Tipo Obligatorio Predeterminado Descripción
pool_id string Sí — UUID del grupo (debe haberse generado a partir de una estrategia)

Devuelve:

{
"pool_id": "...",
"previous_size": 195,
"new_size": 200,
"added": 10,
"removed": 5,
"requested_size": 200,
"effective_size": 200,
"quality_score": 0.96,
"quality_details": { },
"warnings": []
}

Elimina un grupo de encuestados.

Parámetro Tipo Obligatorio Predeterminado Descripción
pool_id string Sí — UUID del grupo

Devuelve: { pool_id, deleted }


Situación Respuesta
Grupo no encontrado {"error": "Pool {id} not found"}
Estrategia no encontrada, o en un proyecto que quien llama no puede leer (generar, previsualizar) {"error": "Strategy {id} not found"}
No hay encuestados elegibles {"error": "No eligible respondents available for this strategy"}
No generado a partir de una estrategia {"error": "Pool was not generated from a strategy — cannot refresh"}
Estrategia de origen eliminada, o en un proyecto que quien llama no puede leer (actualizar) {"error": "Source strategy {id} not found"}
Grupo de estrategia sin selección registrada (actualizar) Conflicto: el grupo no registra ajustes de selección, por lo que no puede actualizarse. Genere en su lugar un grupo nuevo a partir de la estrategia con el tamaño que desee y asígnelo a la campaña.
No es propietario del proyecto del grupo {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"}

add_respondents_to_pool usa operaciones de conjuntos para detectar duplicados. Los duplicados se omiten sin avisar y se reflejan en el recuento duplicates_skipped; no se produce ningún error.

Tipo de origen Creado por Puede actualizarse
"manual" create_respondent_pool No
"strategy" generate_pool_from_strategy Sí, con los ajustes de selección guardados en el grupo

Toda selección (generar, previsualizar, actualizar) parte de los encuestados que usted puede ver: todo el panel en una organización privada o para un administrador; en otro caso, los encuestados de los proyectos de los que es propietario. Esto se aplica también a la estrategia predeterminada de la organización, de modo que una selección nunca nombra a un encuestado que list_respondents no le mostraría.

Después los filtra, antes de elegir, según los ajustes de selección:

  1. Si require_email está activado, se excluyen los encuestados sin correo electrónico
  2. Se excluyen los encuestados que figuran en exclude_respondent_ids
  3. Si no queda ningún encuestado elegible, generar y actualizar devuelven un error (una actualización nunca vacía un grupo); la previsualización devuelve eligible_count: 0

Un miembro quitado de un grupo a mano no se añade a exclude_respondent_ids, de modo que la siguiente actualización puede volver a seleccionarlo.