Herramientas de campaña — Referencia de herramientas MCP
Las herramientas de campaña gestionan el ciclo de vida de las campañas de encuesta: crear campañas, asignar entrevistadores y grupos de encuestados, repartir la carga de trabajo y enviar invitaciones. Muchas operaciones siguen un patrón de respuesta en bloque con los campos added/skipped/reasons.
list_campaigns
Sección titulada «list_campaigns»Lista todas las campañas, opcionalmente filtradas por proyecto, nombre o estado.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
project_id |
string |
No | — | Filtra por ID de proyecto |
name |
string |
No | — | Filtra por nombre de campaña |
status |
string |
No | — | Filtra por estado |
limit |
integer |
No | 100 |
Número máximo de resultados que se devuelven |
Devuelve: { items: [...], count, limit }
get_campaign
Sección titulada «get_campaign»Obtiene una campaña por su ID.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
Devuelve: el objeto de la campaña o { error }. Incluye offered_languages: los idiomas que pueden elegir los encuestados; primero el idioma de origen del cuestionario y después cada traducción completa de la versión fijada, cada una como { locale, name, human_edited }. Una campaña sin versión fijada solo ofrece el idioma de origen.
create_campaign
Sección titulada «create_campaign»Crea una campaña nueva. El modo de la campaña se determina automáticamente según haya o no entrevistadores asignados.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
name |
string |
Sí | — | Nombre visible de la campaña |
project_id |
string |
Sí | — | ID del proyecto al que pertenece |
questionnaire_id |
string |
Sí | — | Cuestionario que se utilizará |
status |
string |
No | "draft" |
Estado inicial: draft, active o scheduled. Cualquier otro valor se rechaza |
admits_volunteers |
boolean |
Sí | — | Si pueden participar personas que nunca se extrajeron para el grupo de la campaña (participantes espontáneos, el enlace abierto). No tiene valor predeterminado: indíquelo. |
offers_ai_channel |
boolean |
Sí | — | Si los encuestados pueden responder también a la encuesta en su propio asistente de IA. No tiene valor predeterminado: indíquelo. |
intro_text |
string |
Cuando offers_ai_channel es true |
— | Quién recoge los datos y con qué fin; se muestra literalmente antes de la primera pregunta |
consent_text |
string |
Cuando offers_ai_channel es true |
— | Lo que acepta el encuestado; se muestra literalmente, y siempre se añade a continuación un párrafo fijo sobre el proveedor de IA |
Devuelve: el objeto de la campaña creada.
update_campaign solo cambia status siguiendo el ciclo de vida de la campaña: draft → active o scheduled; scheduled → active o draft; active → paused, completed o aborted; paused → active, completed o aborted; completed o aborted → draft. Cualquier otro cambio, o un estado desconocido, se rechaza y no se modifica nada.
update_campaign también acepta offers_ai_channel, intro_text y consent_text, todos opcionales; si se omiten, se conserva el valor almacenado en la campaña. Los textos se comprueban sobre el resultado: activar el asistente en una campaña que ya tiene ambos textos no requiere volver a indicarlos, y vaciar un texto mientras se ofrece el asistente se rechaza. Desactivar el asistente invalida todos los códigos de emparejamiento aún no utilizados; los encuestados que ya están conectados pueden terminar.
add_interviewers_to_campaign
Sección titulada «add_interviewers_to_campaign»Añade entrevistadores (usuarios con el rol de entrevistador) a una campaña. Sigue el patrón de respuesta en bloque.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
user_ids |
string[] |
Sí | — | Lista de ID de usuario que se añaden como entrevistadores |
Devuelve:
{ "campaign_id": "...", "added": ["uid1"], "already_present": ["uid2"], "skipped": [{"id": "uid3", "reason": "User not found"}], "total_added": 1}Motivos de omisión: "User not found" (usuario no encontrado), "No interviewer role" (sin rol de entrevistador).
remove_interviewers_from_campaign
Sección titulada «remove_interviewers_from_campaign»Retira entrevistadores de una campaña.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
user_ids |
string[] |
Sí | — | Lista de ID de usuario que se retiran |
Devuelve:
{ "campaign_id": "...", "removed": ["uid1"], "not_found": ["uid2"], "total_removed": 1}update_campaign_questionnaire
Sección titulada «update_campaign_questionnaire»Cambia el cuestionario asignado a una campaña.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
questionnaire_id |
string |
Sí | — | UUID del nuevo cuestionario |
Devuelve:
{ "campaign_id": "...", "old_questionnaire_id": "...", "new_questionnaire_id": "...", "success": true, "warning": "Campaign has existing surveys — they reference the old questionnaire"}assign_respondents_to_interviewer
Sección titulada «assign_respondents_to_interviewer»Asigna encuestados concretos a un entrevistador concreto dentro de una campaña para repartir la carga de trabajo.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
interviewer_id |
string |
Sí | — | UUID del usuario entrevistador |
respondent_ids |
string[] |
Sí | — | Lista de ID de encuestados que se asignan |
Devuelve:
{ "assigned": ["r1"], "already_assigned": ["r2"], "not_in_campaign": ["r3"]}unassign_respondents_from_interviewer
Sección titulada «unassign_respondents_from_interviewer»Retira encuestados de la asignación de un entrevistador. Los encuestados siguen en el grupo de la campaña, pero quedan sin asignar.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
interviewer_id |
string |
Sí | — | UUID del usuario entrevistador |
respondent_ids |
string[] |
Sí | — | Lista de ID de encuestados cuya asignación se retira |
Devuelve:
{ "unassigned": ["r1"], "not_assigned": ["r2"]}get_interviewer_workload
Sección titulada «get_interviewer_workload»Obtiene la carga de trabajo de un entrevistador concreto en una campaña: los encuestados asignados y el estado de finalización de sus encuestas.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
interviewer_id |
string |
Sí | — | UUID del usuario entrevistador |
Devuelve:
{ "campaign_id": "...", "interviewer_id": "...", "assigned_respondents": [ {"id": "...", "name": "...", "email": "...", "age": 35, "gender": "female", "location": "Berlin"} ], "survey_status": { "respondent_id": {"survey_id": "...", "status": "completed", "completed": true} }, "statistics": { "total_assigned": 10, "completed": 3, "in_progress": 2, "not_started": 5, "completion_rate": 0.3 }}get_unassigned_respondents
Sección titulada «get_unassigned_respondents»Obtiene los encuestados de una campaña que aún no están asignados a ningún entrevistador.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
Devuelve:
{ "campaign_id": "...", "unassigned_count": 5, "unassigned_respondents": [ {"id": "...", "name": "...", "email": "...", "age": 28, "gender": "male", "location": "Munich"} ]}assign_pool_to_campaign
Sección titulada «assign_pool_to_campaign»Asigna un grupo de encuestados a una campaña. Vincula el grupo para que bulk_create_surveys pueda crear encuestas para todos los encuestados del grupo.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
pool_id |
string |
Sí | — | UUID del grupo de encuestados |
Devuelve:
{ "campaign_id": "...", "pool_id": "...", "pool_name": "Urban Millennials", "respondent_count": 200, "previous_pool_id": null}get_campaign_pool
Sección titulada «get_campaign_pool»Obtiene el grupo de encuestados asignado a una campaña.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
Devuelve (con grupo asignado):
{ "campaign_id": "...", "pool_id": "...", "pool_name": "...", "pool_description": "...", "respondent_count": 200, "respondent_ids": ["..."], "source_type": "strategy", "source_strategy_id": "...", "quality_score": 0.95, "has_pool": true}Devuelve (sin grupo): { campaign_id, pool_id: null, has_pool: false, message: "..." }
send_campaign_invitations
Sección titulada «send_campaign_invitations»Envía los correos de invitación a la encuesta a los encuestados de la campaña. Envía correos reales con acceso mediante enlace mágico.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
respondent_ids |
string[] |
No | — | Encuestados concretos a los que invitar |
send_to_all_uninvited |
boolean |
No | false |
Envía a todos los encuestados que aún no han sido invitados |
Cada invitación se redacta en el idioma de su destinatario: el idioma preferido del encuestado cuando la campaña ofrece una traducción completa a ese idioma o, en caso contrario, el idioma de origen del cuestionario.
Devuelve:
{ "campaign_id": "...", "results": { "sent": [{"respondent_id": "...", "name": "...", "email": "...", "survey_id": "...", "survey_url": "..."}], "skipped": [{"respondent_id": "...", "name": "...", "reason": "No email address"}], "failed": [{"respondent_id": "...", "name": "...", "reason": "Email send failed: ..."}] }, "summary": {"sent": 8, "skipped": 1, "failed": 1}}Cuando la campaña ofrece el asistente de IA, cada correo de invitación añade un párrafo que remite al encuestado a la opción de IA de su página de la encuesta, y cada entrada de sent incluye además connector_url, la dirección del conector del encuestado.
Requisitos de cada encuestado para recibir la invitación:
- Debe tener una dirección de correo electrónico
notification_preferenceno debe ser"none"- La encuesta no debe estar ya completada ni en curso
- La campaña debe aceptarlo. Invitar a alguien que la campaña nunca extrajo para su grupo requiere una campaña que admita voluntarios y que esté en pleno trabajo de campo: el mismo filtro de admisión por el que pasa un participante espontáneo. Su encuesta se registra entonces como de voluntario y no como un caso extraído, de modo que el conjunto de datos puede seguir distinguiendo ambos.
Motivos de omisión: "Respondent not found" (encuestado no encontrado), "No email address" (sin dirección de correo), "Opted out of notifications" (ha rechazado las notificaciones), "Survey already completed" (encuesta ya completada), "Survey already in_progress" (encuesta ya en curso), además de un rechazo que indica cuál de las dos condiciones del filtro de admisión no se cumplió: la campaña no acepta participantes espontáneos o no está en trabajo de campo en ese momento.
Herramientas de cadena
Sección titulada «Herramientas de cadena»Dos de las secuencias anteriores también están disponibles como una sola llamada. No son atajos que se salten nada: cada paso es la misma herramienta documentada en esta página, de modo que se escriben los mismos registros, se generan los mismos eventos de auditoría y cualquier rechazo que daría una herramienta individual se devuelve aquí sin cambios, más stopped_at_step, que indica de qué paso procede la detención. No se deshace nada, así que una cadena que se detiene a medias conserva lo que construyeron los pasos anteriores y usted continúa con las herramientas individuales.
Una cadena comprueba sus derechos de uso para cada paso antes de construir nada. Si su suscripción no cubre un paso posterior, se rechaza de antemano en lugar de entregarle un trabajo de campo a medio preparar.
prepare_campaign_fielding
Sección titulada «prepare_campaign_fielding»Ejecuta toda la cadena de preparación del trabajo de campo de una campaña: crea la estrategia de muestreo, genera el grupo de encuestados, asigna el grupo a la campaña, publica (y fija) la versión del cuestionario que usará la campaña y crea las encuestas.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | Campaña que se prepara. Debe tener ya asignado el cuestionario que se pretende usar |
admits_volunteers |
boolean |
Sí | ninguno | La política de admisión de voluntarios de este trabajo de campo, indicada explícitamente. No hay valor predeterminado y debe coincidir con la configuración de la propia campaña; si no es la correcta, cámbiela antes con update_campaign |
strategy_name |
string |
Sí | — | Nombre de la estrategia de muestreo que crea esta ejecución |
target_size |
integer |
Sí | — | El tamaño solicitado de la extracción del grupo: encuestados que se extraen, antes del sobremuestreo (> 0). Se pasa a la extracción como requested_size y se guarda en el grupo |
factors |
object[] |
No | [] |
Factores de distribución demográfica con los que la estrategia evalúa el ajuste |
selection_algorithm |
string |
No | "greedy" |
Algoritmo de selección para la extracción del grupo ("greedy" o "random_constrained") |
oversample_factor |
number |
No | 1.0 |
Multiplicador de sobremuestreo para la extracción del grupo (≥ 1) |
quality_metric |
string |
No | "rmse" |
Métrica con la que la estrategia evalúa el ajuste: "rmse", "mae", "chi_square" o "max_deviation". Cualquier otro valor se rechaza antes de construir nada |
require_email |
boolean |
No | false |
La extracción del grupo solo admite encuestados que tengan dirección de correo electrónico |
pool_name |
string |
No | — | Nombre del grupo generado; por defecto, una etiqueta derivada de la estrategia |
La estrategia que crea esta ejecución solo contiene factors y quality_metric. Los ajustes de selección (target_size, oversample_factor, selection_algorithm, require_email) pasan al paso del grupo y se guardan en el grupo, exactamente como los guardaría una llamada directa a generate_pool_from_strategy.
Devuelve: ready_to_invite, el strategy_id, pool_id, pool_respondent_count, qml_version_id, los offered_languages que pueden elegir los encuestados para esa versión (como en get_campaign) y los surveys_created / surveys_skipped que produjo, más next_step. Si se detiene: stopped_at_step con el error y el detail del paso que lo rechazó, y todo lo que los pasos anteriores ya habían construido.
Por qué importa el paso de publicación. Una cadena montada a mano suele olvidar la publicación, y una campaña sin versión fijada resuelve la versión más reciente del cuestionario en el momento de la lectura, de modo que una edición hecha en pleno trabajo de campo cambia en silencio el instrumento para encuestados que ya han respondido.
Volver a ejecutarla extrae de nuevo. Cada ejecución crea una estrategia y un grupo nuevos y vuelve a vincular la campaña a ellos (un grupo es de un solo uso); después recorre el nuevo grupo y omite a los encuestados que ya tienen una encuesta en esta campaña. Con una lista de encuestados mayor que target_size, una segunda ejecución añade por tanto encuestados recién extraídos en lugar de sustituir a nadie.
simulate_campaign_responses
Sección titulada «simulate_campaign_responses»Crea las encuestas de la campaña y después genera respuestas sintéticas sobre ellas. Consulte mass_fill_surveys para saber qué hace cada modo de distribución y cada perfil de persona.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | Campaña cuyas encuestas se crean y después se rellenan |
distribution |
string |
No | "realistic" |
"realistic", "random" o "llm" |
max_surveys |
integer |
No | — | Límite de encuestas de la campaña que se rellenan |
profiles |
string[] |
No | ["random"] |
Nombres de los perfiles de persona que se asignan de forma rotativa a los encuestados |
concurrency |
integer |
No | 1 |
Paralelismo del bucle interno del relleno |
Devuelve: surveys_created / surveys_skipped, y un task_id para el relleno con status: "pending". Consúltelo con get_task_status exactamente igual que una ejecución de mass_fill_surveys. Si se detiene: stopped_at_step con el error y el detail del paso que lo rechazó, y task_id: null.
Gestión de errores
Sección titulada «Gestión de errores»Errores frecuentes
Sección titulada «Errores frecuentes»| Situación | Respuesta |
|---|---|
| Campaña no encontrada | {"error": "Campaign {id} not found"} |
| Entrevistador no asignado a la campaña | {"error": "Interviewer {id} is not assigned to this campaign"} |
| Sin cuestionario/grupo | {"error": "Campaign has no questionnaire assigned"} |
Patrón de operaciones en bloque
Sección titulada «Patrón de operaciones en bloque»La mayoría de las herramientas de campaña que aceptan listas de ID devuelven resultados estructurados en lugar de fallar por elementos individuales:
{ "added": ["id1"], "already_present": ["id2"], "skipped": [{"id": "id3", "reason": "User not found"}], "total_added": 1}Este patrón se aplica a: add_interviewers_to_campaign, remove_interviewers_from_campaign, assign_respondents_to_interviewer, unassign_respondents_from_interviewer y send_campaign_invitations.
Cada elemento omitido o fallido incluye un campo reason que explica por qué se excluyó de la operación.