Herramientas de encuesta — Referencia de herramientas MCP
Las herramientas de encuesta gestionan el ciclo de ejecución de las encuestas: crear sesiones de encuesta, recorrer el flujo de los cuestionarios, enviar respuestas y generar datos de prueba sintéticos. Los ítems de tipo comentario se omiten automáticamente: quien llama nunca los recibe.
list_surveys
Sección titulada «list_surveys»Lista las encuestas, opcionalmente filtradas por cuestionario, campaña, encuestado, entrevistador o estado.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
No | — | Filtra por ID de cuestionario |
campaign_id |
string |
No | — | Filtra por ID de campaña |
respondent_id |
string |
No | — | Filtra por ID de encuestado |
interviewer_user_id |
string |
No | — | Filtra por entrevistador asignado (usuario) |
status |
string |
No | — | Filtro: "pending", "in_progress" o "completed" |
expand |
boolean |
No | false |
Rellena los objetos anidados de cuestionario, entrevistador, encuestado y campaña |
cursor |
string |
No | — | Cursor de paginación de una página anterior |
limit |
integer |
No | 50 |
Tamaño de página (máximo 100) |
Devuelve: { data: [...], next_cursor, has_more }, con paginación por cursor. Cada encuesta incluye status y un booleano derivado de solo lectura, completed (true exactamente cuando status es "completed"); status es la única fuente de verdad, y ninguna herramienta de encuestas tiene un filtro ni un dato de entrada completed.
update_survey
Sección titulada «update_survey»Actualiza los campos modificables de una encuesta. Las entidades vinculadas (cuestionario, encuestado, entrevistador, campaña) no se pueden modificar aquí: elimine la encuesta y vuelva a crearla para cambiar esos vínculos.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
survey_id |
string |
Sí | — | UUID de la encuesta |
status |
string |
No | — | Nuevo estado; establecer "completed" es la forma de expresar la finalización (no existe un dato de entrada completed aparte) |
qml_state |
object |
No | — | Avanzado: sustituye el estado del flujo de la encuesta |
current_block_id |
string |
No | — | Avanzado: cambia la posición del puntero del flujo |
current_item_id |
string |
No | — | Avanzado: cambia la posición del puntero del flujo |
Devuelve: el objeto de la encuesta actualizado (con la misma forma que las entradas de list_surveys, con completed derivado de status).
create_survey
Sección titulada «create_survey»Crea una encuesta nueva para un encuestado.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
questionnaire_id |
string |
Sí | — | Cuestionario que se utilizará |
respondent_id |
string |
Sí | — | UUID del encuestado |
interviewer_user_id |
string |
No | — | Para entrevistas telefónicas o presenciales. Omítalo en las encuestas autoadministradas |
campaign_id |
string |
No | — | Asocia la encuesta a una campaña |
Devuelve: { id, questionnaire_id, interviewer_user_id, respondent_id, campaign_id, mode }
mode se deriva y nunca se establece: field_interview cuando hay un entrevistador vinculado, ai_assisted cuando el encuestado dio su consentimiento en su asistente de IA antes de dar cualquier respuesta y direct en los demás casos. Todos los objetos de encuesta que devuelven estas herramientas lo incluyen. Consulte Modo de la encuesta.
Un encuestado tiene como máximo una encuesta activa por campaña. Si el encuestado ya tiene una, la llamada se rechaza como conflicto (REST 409) indicando el ID de esa encuesta: continúela o elimínela primero.
bulk_create_surveys
Sección titulada «bulk_create_surveys»Crea encuestas para todos los encuestados del grupo asignado a una campaña. Omite a los encuestados que ya tienen encuesta.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
Devuelve:
{ "status": "success", "campaign_id": "...", "created_count": 45, "skipped_count": 5, "surveys": [{"id": "...", "respondent_id": "..."}]}Requisitos: la campaña debe tener asignados tanto un cuestionario como un grupo de encuestados.
get_survey_current_item
Sección titulada «get_survey_current_item»Obtiene la pregunta actual de una encuesta. En la primera llamada inicializa el estado de la encuesta.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
survey_id |
string |
Sí | — | UUID de la encuesta |
Devuelve (pregunta): el ítem actual, con sus opciones de respuesta incluidas, y el tipo de control: una sola ida y vuelta contiene todo lo necesario para responder.
{ "survey_id": "...", "status": "in_progress", "item": { "id": "q_gender", "kind": "Question", "text": "What is your gender?" }, "control_type": "radio", "options": [ {"value": "male", "text": "Male"}, {"value": "female", "text": "Female"}, {"value": "other", "text": "Other"} ], "required": true}En un control deslizante (slider), options contiene un único descriptor de rango:
{"control_type": "slider", "options": [{"type": "range", "min": 18, "max": 99, "step": 1}]}Los controles editbox, range y textarea devuelven una lista options vacía; lea sus límites o su configuración de texto en el input del ítem. Tipos de control: radio, dropdown, checkbox, slider, switch, editbox, range, textarea.
Devuelve (completada): { survey_id, status: "completed", message: "..." }
submit_survey_response
Sección titulada «submit_survey_response»Envía una respuesta a la pregunta actual y avanza al ítem siguiente.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
survey_id |
string |
Sí | — | UUID de la encuesta |
item_id |
string |
Sí | — | ID del ítem que se responde |
outcome |
any |
Sí | — | Valor de la respuesta (el tipo depende del control; una respuesta de tipo Range es un par [low, high]) |
Devuelve:
{ "survey_id": "...", "status": "in_progress", "output": { }, "next": { }}status es "in_progress" o "completed". next incluye el paso siguiente (con la misma forma que get_survey_current_item), así que no necesita una consulta aparte; es null cuando la encuesta se completa. Los ítems de comentario que siguen se procesan automáticamente después de cada envío.
finish_survey
Sección titulada «finish_survey»Marca explícitamente una encuesta como completada. Úsela en los casos excepcionales en que la finalización automática no se produce.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
survey_id |
string |
Sí | — | UUID de la encuesta |
Devuelve: { status: "success" | "already_complete", survey_id, message }.
mass_fill_surveys
Sección titulada «mass_fill_surveys»Pone en cola una tarea asíncrona en segundo plano que rellena todas las encuestas pendientes de una campaña con respuestas de prueba sintéticas. No la use en campañas con datos reales de encuestados.
La herramienta devuelve un task_id de inmediato; el bucle de generación se ejecuta como trabajo en segundo plano en el propio worker de Portor. Consulte get_task_status hasta que la tarea llegue a un estado final: completed (se rellenaron todas las encuestas), partial (se rellenaron algunas y otras fallaron, p. ej. por datos de encuestado incorrectos o por un error transitorio de QML) o failed (no se rellenó ninguna encuesta, ya sea por un error de validación previo a la ejecución, como una campaña inexistente, o porque fallaron todas las encuestas de la ejecución; last_error explica el motivo). Los tres estados son excluyentes: cualquier combinación de éxitos y fallos termina en partial, nunca en failed.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | UUID de la campaña |
distribution |
string |
No | "realistic" |
Estrategia: "realistic", "random" o "llm"; cualquier otro valor se rechaza |
max_surveys |
integer |
No | — | Límite de encuestas que se rellenan. null = todas las pendientes |
profiles |
string[] |
No | ["random"] |
Perfiles de persona, asignados de forma rotativa |
concurrency |
integer |
No | 1 |
Tamaño del grupo de hilos de cada tarea para el bucle interno |
| Distribución | Cómo se eligen las respuestas | Para qué usarla |
|---|---|---|
realistic |
Ponderadas según los datos demográficos y el perfil de persona del encuestado: las preguntas de elección usan pesos que dependen del perfil; los controles deslizantes, una gaussiana; y los campos de texto, frases propias de cada perfil | Pruebas del proceso a gran volumen (rápida) |
random |
Uniforme, sin influencia demográfica | Pruebas de carga (la más rápida) |
llm |
Una llamada a Claude Haiku por pregunta, con el perfil de persona, los datos demográficos del encuestado y todas las respuestas anteriores de la encuesta, de modo que cada encuesta es coherente consigo misma. Aproximadamente un segundo por pregunta | Respuestas abiertas verosímiles; requiere credenciales de IA en su perfil |
Perfiles: young_single, married_family, retired, high_income, random.
Devuelve (de forma síncrona, tras validar la puesta en cola):
{ "task_id": "f5b6c7d8-...", "status": "pending", "campaign_id": "...", "distribution": "realistic", "profiles": ["young_single", "retired"]}Consulte get_task_status(task_id) hasta que state sea completed, partial o failed. status_text muestra el progreso en directo (p. ej. "47 of 200 surveys processed") y, en un estado final, un resumen del relleno (p. ej. "47 of 200 surveys filled (3 failed)"); last_error contiene un motivo saneado en caso de fallo. Para reintentar tras un resultado partial, vuelva a invocar mass_fill_surveys sobre la misma campaña: el relleno solo procesa las encuestas que aún no están completadas, de modo que las ya rellenadas se omiten.
Modos de distribución
Sección titulada «Modos de distribución»| Modo | Motor | Velocidad | Descripción |
|---|---|---|---|
realistic |
Aleatorio ponderado | Rápida | Ponderación demográfica según el perfil (predeterminado) |
random |
Aleatorio uniforme | Rápida | Totalmente aleatorio, sin influencia demográfica |
llm |
API de Claude Haiku | ~1 s/pregunta | Respuestas generadas por IA y coherentes con el perfil de persona. Requiere que su proveedor de razonamiento (o el de su organización) sea la API de Anthropic o AWS Bedrock, con sus credenciales guardadas |
Perfiles de persona
Sección titulada «Perfiles de persona»Se asignan de forma rotativa a los encuestados. Perfiles disponibles:
| Perfil | Edad | Ingresos | Comportamiento |
|---|---|---|---|
young_single |
25–35 | $65k | Progresista, con soltura tecnológica, prefiere las opciones intermedias |
married_family |
30–50 | $80k | Práctico, orientado a la relación calidad-precio |
retired |
65+ | $55k | Conservador, prefiere las primeras opciones o las tradicionales |
high_income |
45 | $150k+ | Centrado en la calidad, prefiere las opciones prémium |
random |
40 | $70k | Sin ningún sesgo particular |
Tratamiento según el tipo de ítem
Sección titulada «Tratamiento según el tipo de ítem»Las respuestas son códigos numéricos (las labels de un control de elección asignan códigos enteros a textos visibles; lo que se envía es el código); solo el control textarea admite texto libre. Consulte Formato de presentación de encuestas para el contrato completo.
| Tipo de ítem | Formato de la respuesta | Ejemplo |
|---|---|---|
Comment |
null (se omite automáticamente) |
Texto informativo |
Question |
Un solo número: código de respuesta / valor numérico / interruptor 1-0 (Checkbox: entero de máscara de bits; Textarea: cadena) |
2, 42, true |
QuestionGroup |
Lista de números, uno por subpregunta, todos del único control compartido del grupo | [1, 3, 2] |
MatrixQuestion |
Lista anidada de números, filas × columnas, con un control compartido | [[1, 2], [3, 1]] |
bulk_delete_surveys
Sección titulada «bulk_delete_surveys»Elimina varias encuestas según criterios de filtro. Sigue un flujo en dos pasos: llame primero con dry_run=true para previsualizar lo que se eliminará y después vuelva a llamar con dry_run=false para ejecutarlo.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
campaign_id |
string |
Sí | — | Elimina las encuestas de esta campaña |
status |
string |
No | — | Solo afecta a las encuestas con este estado: "pending", "in_progress" o "completed" |
dry_run |
boolean |
No | true |
Modo de vista previa: devuelve el recuento y una muestra sin eliminar nada |
La simulación (dry run) devuelve:
{ "dry_run": true, "count": 25, "sample": [{"id": "...", "respondent_id": "...", "status": "pending", "campaign_id": "..."}], "message": "Would delete 25 surveys. Call again with dry_run=False to execute."}La ejecución devuelve: { dry_run: false, deleted: 25 }
Gestión de errores
Sección titulada «Gestión de errores»Errores frecuentes
Sección titulada «Errores frecuentes»| Situación | Respuesta |
|---|---|
| Encuesta no encontrada | {"error": "Survey {id} not found"} |
| Campaña no encontrada | {"error": "Campaign {id} not found"} |
| Cuestionario no encontrado | {"error": "Questionnaire {id} not found"} |
| Encuesta no inicializada | {"error": "Survey not initialized. Call get_survey_current_item first."} |
| Sin grupo asignado | {"error": "Campaign has no respondent pool assigned"} |
| No hay encuestas incompletas | {"status": "no_surveys", "message": "No incomplete surveys found in campaign"} |
Máquina de estados de la encuesta
Sección titulada «Máquina de estados de la encuesta»[Not Started] → get_survey_current_item → [In Progress][In Progress] → submit_survey_response → [In Progress | Completed][In Progress] → finish_survey → [Completed]- Inicialización: la primera llamada a
get_survey_current_itemcarga el QML y crea el estado de la encuesta - Finalización automática: las encuestas se completan automáticamente cuando se responde al último ítem
- Omisión de comentarios: los ítems de comentario se procesan de forma transparente (hasta 50 consecutivos); quien llama nunca los recibe
- Persistencia: cada respuesta se guarda de inmediato en la base de datos