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.
list_respondent_pools
Sección titulada «list_respondent_pools»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).
get_respondent_pool
Sección titulada «get_respondent_pool»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.
create_respondent_pool
Sección titulada «create_respondent_pool»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 }
add_respondents_to_pool
Sección titulada «add_respondents_to_pool»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}remove_respondents_from_pool
Sección titulada «remove_respondents_from_pool»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}generate_pool_from_strategy
Sección titulada «generate_pool_from_strategy»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.
preview_pool_generation
Sección titulada «preview_pool_generation»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": []}refresh_pool_from_strategy
Sección titulada «refresh_pool_from_strategy»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": []}delete_respondent_pool
Sección titulada «delete_respondent_pool»Elimina un grupo de encuestados.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
pool_id |
string |
Sí | — | UUID del grupo |
Devuelve: { pool_id, deleted }
Gestión de errores
Sección titulada «Gestión de errores»Errores comunes
Sección titulada «Errores comunes»| 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"} |
Gestión de duplicados
Sección titulada «Gestión de duplicados»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.
Seguimiento del tipo de origen
Sección titulada «Seguimiento del tipo de origen»| 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 |
Filtrado por elegibilidad
Sección titulada «Filtrado por elegibilidad»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:
- Si
require_emailestá activado, se excluyen los encuestados sin correo electrónico - Se excluyen los encuestados que figuran en
exclude_respondent_ids - 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.