Ir al contenido
Base de conocimiento

Herramientas de cuestionarios y QML — Referencia de herramientas MCP

Las herramientas de cuestionarios gestionan el ciclo de vida de QML: guardar nuevas versiones, validar con el análisis formal de Z3, publicar una versión en una campaña, trasladar entre proyectos y retirar la publicación. El ciclo de vida impone restricciones; por ejemplo, la retirada se bloquea si alguna campaña activa hace referencia al cuestionario.

El QML de un cuestionario reside en la base de datos de Askalot como una cadena de versiones a la que solo se añade (append-only). Cada guardado añade una nueva versión y mueve a ella la cabeza (head) del cuestionario; las versiones anteriores nunca se sobrescriben ni se eliminan.

qml_name es la dirección estable del cuestionario, con la forma projects/{project_id}/questionnaires/{questionnaire_id}.qml. Parece una ruta y se lee como tal, pero identifica un cuestionario: no hay ningún directorio que explorar ni ningún archivo que preparar. list_qml_files devuelve las direcciones que existen.

De ello se derivan tres reglas, que explican la mayor parte del comportamiento descrito a continuación:

  • Un guardado nombra la versión a partir de la que se escribió. Usted compone un guardado a partir del contenido que leyó hace un momento, y puede que otra persona haya guardado desde entonces. Por eso save_qml_file y finalize_upload reciben base_version_id, el version_id de la respuesta de lectura o de guardado de la que procede su contenido. Si la cabeza sigue siendo esa versión, su contenido pasa a ser la nueva cabeza. Si se movió y los dos cambios afectan a líneas distintas, la combinación de ambos pasa a ser la cabeza. Si ambos cambiaron las mismas líneas, no se escribe nada y la respuesta es overlap.
  • Guardar nunca se bloquea por la validación. Un borrador, un bloque pegado o una lógica a medio terminar deben poder almacenarse, así que un guardado registra el veredicto de la validación formal en la versión que se guarda y devuelve los problemas como warnings. Aparte de una dirección que no corresponde a ningún cuestionario en el que usted pueda escribir y de una llamada que el esquema de entrada rechaza, un guardado solo se rechaza por: una base que no es una versión del cuestionario (base_version_unknown), un overlap, una cabeza que se movió antes de cada intento (head_kept_moving), un cuestionario trasladado a otro proyecto mientras se ejecutaba el guardado (questionnaire_moved), una organización sellada (org_sealed) y un contenido de más de 32 KB enviado dentro de la propia llamada.
  • Publicar sí rechaza. publish_qml_file fija una versión en una campaña, que es el momento en que el instrumento llega a un encuestado; por eso es la única vía que rechaza un diseño no sólido. La versión fijada es inmutable durante toda la vida de esa campaña.

Lista todos los cuestionarios, opcionalmente filtrados por nombre.

Parámetro Tipo Obligatorio Predeterminado Descripción
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: { items: [...], count, limit }


Obtiene un cuestionario por su ID.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario

Devuelve: el objeto del cuestionario o { error }.


Crea un cuestionario nuevo a partir de contenido QML o de una plantilla de la biblioteca. El cuestionario y la versión 1 de su QML se crean a la vez, de modo que un cuestionario nunca existe sin contenido.

Parámetro Tipo Obligatorio Predeterminado Descripción
name string Con content el nombre de la plantilla Nombre visible
content string Uno de content / template — El YAML de QML, guardado como versión 1
template string Uno de content / template — Un slug de plantilla de list_questionnaire_templates; la versión 1 es el QML de esa plantilla en language, byte a byte
project_id string Sí — ID del proyecto padre
description string No — Descripción en texto libre
language string No "en"; con template, el suyo Código de idioma. Con template, el idioma en el que se copia la plantilla: uno de los languages de la biblioteca. Si se omite, su propio idioma (su configuración o, en su defecto, el predeterminado de su organización) cuando la biblioteca lo ofrece; si no, en
estimated_duration integer No — Tiempo previsto para completarlo, en minutos

Indique content o template, nunca ambos: si se indican los dos o ninguno, la llamada se rechaza y no se escribe nada. Un slug de template desconocido se responde como no encontrado, y un language que la biblioteca no ofrece se rechaza indicando los que sí ofrece.

Una copia de plantilla se escribe en el idioma en el que se leyó, y cada uno de los demás idiomas que ofrece la biblioteca la acompaña como traducción de la versión 1, de modo que pueden ofrecerse esos idiomas a los encuestados sin un paso de traducción.

Devuelve: el objeto del cuestionario creado, más version_id y version_number de la versión 1. version_id es el base_version_id para un primer guardado de ese contenido.

La creación no depende de la validación formal: content puede estar estructuralmente roto. A partir de content, el veredicto se registra con la versión 1, sin imponerse; lo que exige solidez es publicar en una campaña. A partir de una template, la validación se ejecuta en segundo plano unos segundos después de la creación, igual que tras un guardado: hasta entonces logic_validated vale false.


Lista la biblioteca de plantillas de cuestionarios: cuestionarios ya preparados (evaluaciones de cursos, opinión de clientes, inscripción a eventos, admisión de pacientes y más), agrupados en categorías. Pase un slug a create_questionnaire como template.

Parámetro Tipo Obligatorio Predeterminado Descripción
language string No el suyo El idioma de la biblioteca en el que se listan las plantillas. Si se omite, su propio idioma (su configuración o, en su defecto, el predeterminado de su organización) cuando la biblioteca lo ofrece; si no, en. Un idioma que la biblioteca no ofrece se rechaza indicando los que sí ofrece
category string No — Un slug de categoría; uno desconocido se rechaza con la lista de categorías
query string No — Palabras que deben aparecer todas en el nombre o la descripción de una plantilla, sin distinguir mayúsculas y minúsculas
limit integer No 50 Tamaño de página, de 1 a 100
cursor string No — El next_cursor de la página anterior

Devuelve: { data: [{ slug, name, category, subcategory, description }], categories: [{ slug, name }], language, language_fallback, languages, total, next_cursor, has_more }. Los nombres, las descripciones y las categorías están en language; languages lista todos los idiomas que ofrece la biblioteca, con en en primer lugar. language_fallback es true cuando no se indicó ningún language y la biblioteca aún no ofrece el suyo, de modo que la respuesta está en inglés: comuníqueselo al usuario. total cuenta todas las plantillas coincidentes; siga next_cursor mientras has_more sea true. No se lista ningún cuerpo QML: cree a partir de un slug y luego lea el cuestionario con get_qml_content.


Elimina lógicamente un cuestionario.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario

Devuelve: { success: true, questionnaire_id } o un error.

La eliminación lógica inserta un registro de copia de seguridad; restore_questionnaire (más abajo) puede recuperar el cuestionario durante un breve período.


Cambia el nombre de un cuestionario. Es una simple actualización de metadatos: la dirección del cuestionario y su cadena de versiones QML no cambian, de modo que las campañas que hacen referencia a él siguen funcionando.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario
name string Sí — Nuevo nombre visible (máx. 255 bytes)

Devuelve: el objeto del cuestionario actualizado.


Restaura un cuestionario eliminado lógicamente hace poco y vuelve a vincular sus referencias. La eliminación nunca tocó su cadena de versiones QML, así que el cuestionario restaurado vuelve exactamente con la versión que tenía.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario

Devuelve: el objeto del cuestionario restaurado, o un error si ha vencido el plazo de restauración.


Lista los cuestionarios QML de la organización. No requiere parámetros. El qml_name de cada entrada puede pasarse a cualquier otra herramienta QML.

Devuelve:

{
"items": [
{
"name": "3f9c2b10-....qml",
"qml_name": "projects/abc123/questionnaires/3f9c2b10-....qml",
"tier": "project",
"project_id": "abc123"
}
],
"count": 1
}

Obtiene un resumen rápido de la versión actual de un cuestionario: número de ítems y metadatos, sin el contenido completo.

Parámetro Tipo Obligatorio Predeterminado Descripción
qml_name string Sí — Dirección del cuestionario obtenida de list_qml_files

Devuelve: { success, qml_name, items_count, metadata }


Muestra un ítem de la versión actual de un cuestionario tal como lo ve un encuestado. Un host que renderiza MCP Apps (como Claude) abre un panel de solo lectura con los controles reales del ítem; cualquier otro host recibe el mismo ítem como texto JSON.

Parámetro Tipo Obligatorio Predeterminado Descripción
qml_name string Sí — Dirección del cuestionario obtenida de list_qml_files
item_id string Sí — El id del ítem

Devuelve: los campos renderizados del ítem (id, kind, title, input y questions, rows o columns cuando el ítem los tiene), con cualquier marcado de su texto saneado. Un ítem o una dirección desconocidos producen un error de la herramienta.


Recupera el YAML sin procesar de la versión actual de un cuestionario.

Parámetro Tipo Obligatorio Predeterminado Descripción
qml_name string Sí — Dirección del cuestionario

Devuelve: { success, qml_name, content, size_bytes, version_id, version_number } para contenido de hasta 32 KB. version_id nombra la versión que es content; páselo como base_version_id cuando guarde contenido escrito a partir de esta respuesta.

Por encima de 32 KB, el contenido no se incluye en la propia respuesta: la respuesta es { success, qml_name, download_url, size_bytes, version_id, version_number, note }, donde download_url es un enlace de corta duración (reutilizable hasta que caduque) que se descarga directamente por HTTPS (sin necesidad de más autenticación). El enlace sirve version_id aunque un guardado haya movido la cabeza desde que lo solicitó, de modo que sus bytes son la versión que usted indica como base_version_id al guardar. Vuelva a llamar a get_qml_content si el enlace ha caducado.


Guarda contenido QML en un cuestionario existente, escrito a partir de una versión que usted indica. Guardar nunca se bloquea por un YAML roto o por infracciones del esquema: un borrador en curso, todavía no válido, se guarda igualmente, y los problemas se devuelven como una lista warnings en lugar de rechazar la escritura.

Parámetro Tipo Obligatorio Predeterminado Descripción
qml_name string Sí — Dirección de un cuestionario existente
content string Sí — Contenido YAML de QML, de hasta 32 KB
base_version_id string Sí — La versión a partir de la que se escribió el contenido: el version_id de su respuesta más reciente de get_qml_content, create_questionnaire o de guardado para este cuestionario
project_id string No — Si se indica, debe coincidir con el proyecto del cuestionario; una discrepancia se rechaza en lugar de ignorarse

Primero lea, luego guarde. Llame a get_qml_content, aplique su cambio al contenido que devuelve y guarde con su version_id como base_version_id. Tras un guardado, el siguiente guardado indica el version_id que devolvió ese guardado, nunca uno anterior.

Devuelve: { success, qml_name, questionnaire_id, version_id, version_number, created, merged, content_changed, bytes_written, logic_validated, content?, content_note?, warnings? }.

Qué ocurrió En la respuesta
La base seguía siendo la cabeza created: true, merged: false. Su contenido es la nueva cabeza
Alguien guardó entretanto, en otras líneas created: true, merged: true, content_changed: true. La cabeza contiene ambos cambios y content la incluye: sustituye a su copia. Las líneas que usted no escribió son del otro autor
Su contenido ya es la cabeza created: false. No se escribe nada
Su contenido es igual a su base y la cabeza se movió created: false, content_changed: true, con el content de la cabeza

content se incluye solo cuando el contenido guardado ocupa menos de 32 KB; en caso contrario, content_note indica que se llame a get_qml_content. warnings no aparece en un guardado limpio, o es una lista de problemas de análisis o de esquema en un borrador guardado pero imperfecto.

Un guardado que no escribe nada responde { success: false, error, detail }:

error Significado Qué hacer
overlap Alguien guardó entretanto y cambió las mismas líneas. Incluye head_version_id, head_version_number, conflict_count Llame a get_qml_content, aplique su cambio a lo que devuelve y guarde con su version_id. No vuelva a enviar el mismo contenido con el id más reciente: eso reemplazaría el otro guardado
base_version_unknown base_version_id está en blanco, no es un id de versión o no es una versión de este cuestionario Llame a get_qml_content y guarde con el version_id que devuelve
head_kept_moving El cuestionario se volvió a guardar antes de cada uno de los tres intentos Vuelva a leer y reintente
org_sealed La organización está sellada No puede escribirse nada
questionnaire_moved El cuestionario se trasladó a otro proyecto mientras se ejecutaba el guardado Llame a list_qml_files para obtener su dirección actual, léalo con get_qml_content y vuelva a guardar

La validación formal se ejecuta en segundo plano, unos segundos después del guardado, sobre la versión que sea entonces la cabeza (la suya o la combinación), y su veredicto se registra en esa versión, de modo que la solidez de una versión sigue pudiendo consultarse más tarde, incluso tras nuevas ediciones. Hasta entonces, el logic_validated de la respuesta de guardado es null y logic_validation_note lo indica, y get_questionnaire da logic_validated: false; responde con el veredicto en cuanto llega, y validate_qml_file lo devuelve cuando se le solicita. Un guardado que introduce una regresión pasa el cuestionario a no validado sin bloquear la escritura; su publicación en una campaña se rechaza hasta que se corrija.

Se rechaza una dirección que no corresponde a ningún cuestionario: llame primero a create_questionnaire.

El contenido de más de 32 KB se rechaza con {"error": "content_too_large_for_inline_save"} y no se escribe nada. Use request_upload_url / finalize_upload (más abajo) en lugar de recortar el contenido para que quepa.


Un mecanismo en dos pasos para guardar contenido QML demasiado grande para el límite de 32 KB que save_qml_file admite dentro de la propia llamada. El contenido nunca aparece en una llamada a herramienta: usted solicita un identificador de subida, sube los bytes directamente por HTTPS y luego finaliza.

  1. request_upload_url(qml_name, project_id?): genera un identificador de subida de corta duración, de un solo uso y con tamaño limitado.

    Devuelve: { upload_url, artifact_id, max_size_bytes, expires_in }

  2. Suba los bytes QML sin procesar directamente a upload_url (un PUT HTTP, fuera de la llamada a la herramienta MCP).

  3. finalize_upload(artifact_id, base_version_id): guarda el contenido subido exactamente como lo guardaría save_qml_file sobre esa base: guardado, combinado con un guardado más reciente o rechazado. base_version_id es obligatorio y significa lo mismo que en save_qml_file. Puede reintentarse sin riesgo con el mismo artifact_id: tras una finalización que guardó, o que respondió overlap, un reintento devuelve la primera respuesta y no escribe nada, sea cual sea la base que indique.

    Devuelve: la misma estructura que save_qml_file

    Un overlap consume el identificador, porque los bytes subidos se escribieron a partir de la versión antigua: vuelva a leer, vuelva a aplicar su cambio y suba el resultado con un identificador nuevo. base_version_unknown y head_kept_moving conservan el identificador, de modo que una llamada corregida guarda la misma carga.


Ejecuta la validación formal SMT de Z3 sobre la versión actual de un cuestionario. Analiza la alcanzabilidad, la coherencia y la satisfacibilidad de las poscondiciones de cada ítem.

Parámetro Tipo Obligatorio Predeterminado Descripción
qml_name string Sí — Dirección del cuestionario

Devuelve:

{
"is_valid": true,
"item_count": 12,
"block_count": 3,
"item_classifications": {
"q_age": {
"precondition": "REACHABLE",
"postcondition": "CONTINGENT"
}
},
"statistics": {
"preconditions": {"REACHABLE": 11, "NEVER": 1},
"postconditions": {"CONTINGENT": 8, "TAUTOLOGICAL": 3, "INFEASIBLE": 1}
},
"issues": [
{
"item_id": "q_unreachable",
"severity": "error",
"type": "unreachable_item",
"message": "Item is unreachable",
"suggestion": "Check preconditions"
}
],
"validation_report": "..."
}

Estados de precondición (¿puede alcanzarse el ítem?):

Estado Significado
REACHABLE El ítem puede alcanzarse en al menos una ruta del flujo
NEVER El ítem es inalcanzable: código muerto
UNKNOWN El análisis no pudo determinar la alcanzabilidad

Estados de poscondición (¿pueden satisfacerse las condiciones del ítem?):

Estado Significado
TAUTOLOGICAL La condición siempre es verdadera (redundante)
CONTINGENT La condición depende de las respuestas (normal)
INFEASIBLE La condición nunca puede satisfacerse
UNKNOWN El análisis no pudo determinarlo
Tipo Gravedad Descripción
unreachable_item error La precondición es NEVER: ítem muerto
code_answered_item warning Un codeBlock guarda la respuesta del ítem antes de que el recorrido llegue a él en todos los recorridos en los que se cumple su condición de acceso, de modo que nunca se pregunta. Mueva el codeBlock después del ítem si debe preguntarse
infeasible_postcondition error La poscondición nunca puede satisfacerse
globally_false_postcondition error La poscondición siempre es falsa
tautological_postcondition warning La poscondición siempre es verdadera (redundante)
comment_titled_as_question warning Un Comment solo de visualización tiene como título una petición, por lo que se muestra sin ningún campo para responderla
roster_subject_not_answerable warning El subjectFrom de un Roster nombra un ítem que nunca puede proporcionar un sujeto (inexistente, fuera del bloque o un Comment)
none_unsafe_reference warning Una condición hace una comparación de orden o un cálculo con un ítem que no se pregunta en todas las rutas que llegan a ella: el resultado de ese ítem es None y el predicado lanza una excepción. La igualdad con None es segura y no se señala
inexact_condition warning Una condición lee un ítem que puede quedar sin responder en un lugar donde el validador no puede saber si leer None la hace fallar (bajo not, en un operando de or que no sea el último, o en cualquier parte de una poscondición). Una contradicción se sigue informando, pero no se demuestra que la condición sea siempre verdadera. Compruebe primero que hay respuesta: q.outcome is not None and (…) en una precondición, q.outcome is None or (…) en una poscondición
uninitialized_read warning Una condición o un codeBlock lee una variable a la que un encuestado puede llegar antes de que se haya ejecutado ninguna asignación: se asigna más tarde, solo en una rama, o en un ítem que su propia condición de acceso puede omitir. La lectura lanza una excepción: una precondición omite el ítem, mientras que una poscondición acepta la respuesta sin comprobarla y un codeBlock se detiene a medias, y ambas cosas excluyen la encuesta de los conjuntos de datos. Asigne un valor predeterminado en codeInit, asigne en ambas ramas o condicione la lectura igual que la asignación
self_assignment warning Una sentencia de un codeBlock asigna un valor a sí mismo (q.outcome = q.outcome): no cambia nada, pero parece una derivación
mandated_answer_postcondition warning Una poscondición solo admite una respuesta de un control de elección, de modo que un encuestado que dé cualquier otra respuesta no puede avanzar y esa respuesta nunca se registra. En su lugar, bifurque el flujo según la respuesta
combinable_none_option warning Una opción de Checkbox del tipo “None of the above” («Ninguna de las anteriores») puede marcarse junto con las opciones que niega, y ninguna poscondición rechaza esa combinación
questionnaire_level_condition warning Una clave precondition/postcondition en el nivel raíz. Las condiciones solo se evalúan en el nivel de ítem y de bloque, así que esta nunca se ejecuta
language_not_judged warning El idioma del cuestionario está fuera de los idiomas admitidos, así que no se ejecutaron las comprobaciones basadas en palabras: la parte de redacción de comment_titled_as_question (un ? en el título de un Comment se sigue comprobando) y combinable_none_option. Revíselas a mano
file_not_found error La dirección no corresponde a ningún cuestionario
validation_error error Excepción durante el análisis sintáctico o el análisis

Calcula un cuadro de puntuación de calidad del diseño (dimensiones D2–D8) para la versión actual de un cuestionario. Úselo después de que validate_qml_file no devuelva ningún error: la validación demuestra la solidez lógica; esto evalúa la calidad del diseño (economía del instrumento, densidad de controles de calidad, cobertura de verificación, complejidad estructural, coherencia del orden, diversidad de rutas y equilibrio de la carga). La densidad de controles de calidad se mide sobre las entradas numéricas del cuestionario, las respuestas que un encuestado escribe o ajusta con un control deslizante, en las que una poscondición añade un límite de validez que el propio control no impone. Los ítems de elección se excluyen de esa tasa, porque su conjunto de etiquetas ya fija la respuesta; una poscondición que vincula una elección con otra se indica por separado como control de coherencia. Es determinista y orientativo: las notas nunca afectan a is_valid ni a la publicación.

Parámetro Tipo Obligatorio Predeterminado Descripción
qml_name string Sí — Dirección del cuestionario

Devuelve:

{
"dimensions": {
"instrument_economy": {
"id": "D2",
"grade": "strong",
"metrics": { },
"offenders": [{"item_id": "...", "detail": "..."}],
"truncated": false
}
},
"item_count": 12,
"notes": []
}

El grade de cada dimensión es strong, adequate, weak o not_applicable. Una dirección desconocida o un fallo del análisis devuelve { error }.


Publica un cuestionario en una campaña: la vía al trabajo de campo y la única herramienta de esta referencia que rechaza un diseño no sólido.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario que se lleva a campo
campaign_id string Sí — UUID de la campaña en la que se fija

La versión actual del cuestionario se valida formalmente, el veredicto se registra en esa versión y solo un veredicto limpio la fija en la campaña.

Devuelve: { success, questionnaire_id, campaign_id, qml_version_id, logic_validated }

En caso de rechazo: { error, issues }; issues lista los problemas de gravedad error que hay que corregir. No se fija nada, así que la campaña sigue en campo con lo que tuviera.

La campaña ya debe hacer referencia a este cuestionario; si lleva a campo otro distinto, vuelva a vincularla primero con update_campaign_questionnaire.


Traslada un cuestionario a otro proyecto. El ID del cuestionario no cambia y su cadena de versiones queda intacta, de modo que las campañas que hacen referencia a él —incluidas las fijadas en una versión anterior— siguen funcionando. Un traslado no es una edición.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario
target_project_id string Sí — UUID del proyecto de destino

Devuelve: { success, questionnaire_id, qml_name }; qml_name es la nueva dirección.


Retira un cuestionario de su proyecto eliminándolo lógicamente. Su cadena de versiones QML se conserva —una campaña completada puede seguir fijada en una de esas versiones—, de modo que la retirada saca el cuestionario de su conjunto de trabajo sin borrar lo que se llevó a campo. Se bloquea si el cuestionario tiene campañas activas.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario

Devuelve: { success, questionnaire_id } o un error.


Una traducción es texto traducido junto a una versión de un cuestionario, una por idioma. Solo sustituye el texto visible para el encuestado; los ids, los códigos de opción, las condiciones y el veredicto de Z3 siguen siendo los del original. Solo se ofrece a los encuestados una traducción completa. Conceptos, congelación y el selector del encuestado: Traducir un cuestionario.

Cada herramienta de traducción indica questionnaire_id, version_id (el version_id que respondió get_qml_content o un guardado) y, salvo la de listado, locale (en, es, fr, de o hu, nunca el idioma de origen del propio cuestionario). Cada una traslada primero las traducciones de la versión anterior a la versión indicada, de modo que una versión recién guardada ya contiene cada texto cuyo original no cambió.

Las claves de texto nombran un texto visible para el encuestado: questionnaire/title, block:<id>/title, item:<id>/title, item:<id>/labels/<code> (etiquetas de opción, por código), item:<id>/rows/<n> y /columns/<n> (matriz), item:<id>/questions/<n> (grupo de preguntas), item:<id>/left, /right, /on, /off, /placeholder y .../postcondition/<n>/hint (el mensaje que se muestra cuando se rechaza una respuesta). Consulte las claves exactas de una versión en source_texts de get_qml_translation.

Todas las traducciones de una versión, por idioma.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario
version_id string Sí — Una versión de ese cuestionario

Devuelve: { questionnaire_id, version_id, source_language, translations: [{ locale, started, withdrawn, complete, untranslated, frozen, human_edited, updated_at }] }, con una entrada por cada idioma admitido excepto el de origen, de modo que la lista también nombra los idiomas que nadie ha empezado (started: false, con untranslated vacío: lo están todas las claves, y get_qml_translation las lista) y aquellos cuya traducción se eliminó (withdrawn: true). untranslated lista las claves de texto que aún faltan; frozen significa que se respondió una encuesta en ese idioma, por lo que no admite guardados ni eliminaciones; human_edited significa que una persona la editó en el editor.

La traducción de un idioma, con el original que traduce.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario
version_id string Sí — Una versión de ese cuestionario
locale string Sí — Idioma de destino

Devuelve: los campos del listado para ese idioma más texts (clave → texto traducido), source_language y source_texts (cada clave traducible → su texto original, en el orden del documento). Un idioma que aún no tiene traducción responde con texts vacío y updated_at: null.

Guarda texto traducido para un idioma. El guardado es parcial: texts se combina sobre la traducción guardada, y cada clave que usted omita conserva su texto guardado, de modo que para completar huecos basta con enviar las claves que figuran en untranslated.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario
version_id string Sí — Una versión de ese cuestionario
locale string Sí — Idioma de destino
texts object Sí — Clave de texto → texto traducido
base_updated_at string | null Sí — El updated_at que respondió su lectura; null cuando no respondió ninguna traducción guardada

Devuelve: la traducción guardada (texts, complete, untranslated, frozen, human_edited, updated_at). Un guardado posterior indica el updated_at que respondió este. Un guardado por MCP o por la API se registra como escrito por un agente y nunca marca la traducción como human_edited.

Rechazo Significado Qué hacer
Claves no válidas (solicitud incorrecta, una línea por clave) Una clave nombra un ítem, un bloque o un código de opción que el original no tiene, un índice fuera de rango, una lista posicional (rows, columns, questions, indicaciones de poscondición) enviada en parte, un valor que no es texto, o marcado como <script> Corrija exactamente las claves indicadas y vuelva a guardar
translation_conflict (409) La traducción cambió desde que la leyó, normalmente por una edición de un investigador Vuelva a leer con get_qml_translation, vuelva a aplicar su cambio y guarde con el nuevo updated_at
translation_frozen (409) Se ha respondido una encuesta en este idioma con esta versión No reintente. Guarde una nueva versión del cuestionario, tradúzcala allí y pase la campaña a ella
Idioma de origen (solicitud incorrecta) El idioma es el del propio cuestionario Edite el propio QML o traduzca a otro idioma
No encontrado La versión no es una versión de este cuestionario Lea el cuestionario con get_qml_content e indique el version_id que responde

Elimina la traducción de un idioma para una versión. Una traducción congelada se rechaza (translation_frozen), y un idioma sin traducción devuelve un error de no encontrado.

Parámetro Tipo Obligatorio Predeterminado Descripción
questionnaire_id string Sí — UUID del cuestionario
version_id string Sí — Una versión de ese cuestionario
locale string Sí — Idioma que se elimina

Devuelve: { questionnaire_id, version_id, locale, deleted: true }.


Situación Respuesta
Retirar con campañas activas {"error": "Cannot unpublish: questionnaire has active campaign {campaign_id}"}
Publicar una versión no sólida {"error": "...", "issues": [...]}: no se fija nada
Publicar en una campaña que lleva a campo otro cuestionario {"error": "Campaign {id} fields questionnaire {other}, not {id}. Use update_campaign_questionnaire to rebind it first."}
Ya está en el proyecto de destino {"error": "Questionnaire is already in this project"}

Todas las herramientas resuelven los cuestionarios solo dentro de su propia organización. Una dirección que pertenece a otra organización es indistinguible de una que no existe, y un project_id que no coincide con el proyecto del propio cuestionario se rechaza en lugar de ignorarse en silencio.

Situación Respuesta
Cuestionario no encontrado {"error": "Questionnaire {id} not found"}
Contexto de organización no establecido {"error": "Organization context not set"}
La dirección no corresponde a ningún cuestionario {"error": "QML document '{name}' not found for this organization"}
El guardado no indica ninguna base utilizable {"success": false, "error": "base_version_unknown", "detail": "..."}
El guardado se solapa con un guardado más reciente {"success": false, "error": "overlap", "head_version_id": "...", "head_version_number": n, "conflict_count": n}
Error de análisis de QML {"error": "Failed to parse QML: {details}"}