> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/docs/es/desarrolladores/tools.md).

# Herramientas

Referencia de herramientas del servidor MCP de AirOps: da a Claude, Cursor y otros asistentes de IA acceso programático a analíticas de AEO, Brand Kits, Grids, bases de conocimiento, Playbooks y flujos de trabajo en tu AirOps wo

El servidor MCP de AirOps ofrece a asistentes de IA como Claude y Cursor acceso programático y nativo de IA a tu espacio de trabajo de AirOps. Esta página enumera las herramientas que expone para acceder a tus datos y administrarlos, organizadas en varias áreas: **AEO** (Optimización del motor de respuestas) para analíticas de visibilidad de IA, configuración de prompts e informes, **Gestión de marca** para gestionar la identidad de marca, el estilo de escritura y los recursos visuales, **Grids** para leer, escribir y crear datos de Grid de forma programática, **Bases de conocimiento** para búsqueda semántica e ingesta de documentos, y **Playbooks y flujos de trabajo** para inspeccionar definiciones, revisar comentarios y ejecutar trabajos.

Las herramientas de listar y obtener admiten filtrado, selección de campos, ordenación y paginación cuando corresponda. Las herramientas de escritura documentan sus campos obligatorios en cada sección.

## Acceso al plan

Las herramientas de recursos requieren un espacio de trabajo de pago. Las pruebas del nivel de pago siguen siendo elegibles. Los espacios de trabajo gratuitos pueden conectarse, descubrir herramientas y usar `list_workspaces`, pero las solicitudes de sus datos devuelven una restricción del plan. Si perteneces tanto a espacios de trabajo gratuitos como de pago, elige un espacio de trabajo de pago para las consultas y cambios de recursos.

## Espacio de trabajo y Brand Kit

### `list_workspaces`

Enumera todos los espacios de trabajo a los que tienes acceso.

**Devuelve:** ID del espacio de trabajo, nombre, slug y nivel de suscripción.

| Parámetro   | Valores             |
| ----------- | ------------------- |
| **Filtros** | nombre, nivel       |
| **Ordenar** | nombre, created\_at |

***

### `list_brand_kits`

Enumera todos los Brand Kits a los que tienes acceso. Devuelve `brand_management_enabled` y `aeo_enabled` banderas para cada Brand Kit, para que sepas qué capacidades están disponibles.

* Usar `get_brand_kit` para Brand Kits con `brand_management_enabled: true`
* Usar `get_insights_settings` para Brand Kits con `aeo_enabled: true`

**Devuelve:** ID del Brand Kit, nombre, descripción, URL, nombre del espacio de trabajo, `brand_management_enabled`, y `aeo_enabled`.

| Parámetro   | Valores                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| **Filtros** | workspace\_name, brand\_name, brand\_url, brand\_management\_enabled, aeo\_enabled |
| **Ordenar** | brand\_name, created\_at                                                           |

***

### `get_brand_kit`

Obtén un Brand Kit específico por ID para la gestión de marca y la creación de contenido. Devuelve la identidad de marca, el estilo de escritura y las entidades relacionadas.

**Requiere:** `id`

**Devuelve:** Nombre de marca, URL, descripción, personalidad de escritura, tono de escritura, estado y marcas de tiempo. Opcionalmente incluye entidades relacionadas con datos anidados.

| Parámetro   | Valores                                                                                                                                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Incluye** | product\_lines, product\_lines.competitors, audiences, audiences.writing\_rules, content\_types, content\_types.content\_samples, content\_types.writing\_rules, regions, regions.writing\_rules, writing\_rules, custom\_variables |

***

### `get_insights_settings`

Obtén la configuración de información de AEO para un Brand Kit. Devuelve la información necesaria para usar cualquier herramienta de AEO y análisis.

**Requiere:** `id`

**Devuelve:** ID del Brand Kit, nombre, URL, países, estado de AEO, número de prompts, descripción del cliente, competidores con URLs de dominio y personas.

***

### `update_brand_kit`

Actualiza los campos base de un Brand Kit. Solo se cambian los campos proporcionados.

**Requiere:** `brand_kit_id`

**Campos actualizables:** `nombre de la marca`, `brand_url`, `brand_about`, `writing_persona`, `writing_tone`

***

### `list_topics`

Enumera los temas configurados para un Brand Kit.

**Requiere:** `brand_kit_id`

**Devuelve:** ID del tema, nombre y color.

| Parámetro   | Valores             |
| ----------- | ------------------- |
| **Filtros** | nombre              |
| **Ordenar** | nombre, created\_at |

***

### `create_topic`

Crea un nuevo tema para un Brand Kit. Los temas agrupan los prompts rastreados y las vistas analíticas por tema.

**Requiere:** `brand_kit_id`, `nombre`

**Campos opcionales:** `color`

***

### `update_topic`

Actualiza el nombre o el color de un tema. Las asignaciones de prompts existentes permanecen adjuntas al tema.

**Requiere:** `brand_kit_id`, `topic_id`

**Campos:** `nombre`, `color`

***

### `delete_topic`

Elimina un tema de un Brand Kit.

**Requiere:** `brand_kit_id`, `topic_id`

{% hint style="warning" %}
Eliminar un tema puede afectar la organización de prompts y las vistas de informes. Confirma el tema y su impacto posterior antes de llamar a esta herramienta.
{% endhint %}

***

### `list_personas`

Enumera las personas configuradas para un Brand Kit.

**Requiere:** `brand_kit_id`

**Devuelve:** ID de la persona, título y descripción.

| Parámetro   | Valores            |
| ----------- | ------------------ |
| **Filtros** | title              |
| **Ordenar** | title, created\_at |

***

### `publish_brand_kit`

Publica el borrador actual de un Brand Kit para que los cambios se activen. Todos los cambios realizados mediante `update_brand_kit` y `manage_brand_kit_*` se aplican a un borrador. Al publicar, el borrador pasa a activo y se crea un borrador nuevo a partir de él.

**Requiere:** `brand_kit_id`

{% hint style="warning" %}
Confirma siempre con el usuario antes de publicar. Esto hace que todos los cambios pendientes pasen a estar activos.
{% endhint %}

***

### `create_brand_kit_recap_entry`

Registra una entrada de resumen que sintetice los cambios del Brand Kit realizados durante una sesión MCP. Usa esto una vez, cerca del final de una sesión que haya cambiado el Brand Kit, con evidencia como URLs de origen, nombres de página o citas breves en `body_markdown`.

**Requiere:** `brand_kit_id`, `title`

**Campos opcionales:** `body_markdown`

**Devuelve:** ID de la entrada de resumen, título, fuente y mensaje de éxito.

***

## Gestión del Brand Kit

Herramientas para crear y actualizar entidades del Brand Kit. Cada herramienta admite tanto crear (omitir `id`) y actualizar (proporcionar `id`) operaciones. En la actualización, solo se cambian los campos proporcionados.

{% hint style="info" %}
Los cambios se guardan en un **borrador**. Usa `publish_brand_kit` para hacerlos activos.
{% endhint %}

### `manage_brand_kit_product_line`

Crea o actualiza una línea de producto para un Brand Kit.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `url`, `details`, `positioning`, `ideal_customer_profile`

***

### `manage_brand_kit_competitor`

Crea o actualiza un competidor para un Brand Kit. Los competidores deben estar asociados con al menos una línea de producto.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `domain`, `product_line_ids` (se requiere al menos uno)

***

### `manage_brand_kit_audience`

Crea o actualiza una audiencia para un Brand Kit.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `descripción`

***

### `manage_brand_kit_region`

Crea o actualiza una región para un Brand Kit.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `descripción`, `icon_name` (icono de bandera, por ej., `flag-us`)

***

### `manage_brand_kit_content_type`

Crea o actualiza un tipo de contenido para un Brand Kit. Al crear, puedes proporcionar una `sample_url` para inicializar el tipo de contenido. El sistema rastreará la URL y usará IA para generar los campos automáticamente.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `template_outline`, `cta_text`, `cta_url`, `header_case` (title\_case, sentence\_case, personalizado), `header_case_custom_value`, `sample_url` (solo al crear)

***

### `manage_brand_kit_content_sample`

Crea o actualiza una muestra de contenido para un Brand Kit. Al crear, la URL de la muestra se procesa de forma asíncrona para extraer el contenido.

**Requiere:** `brand_kit_id`

**Campos:** `url` (obligatorio al crear), `content_type_id` (obligatorio al crear), `content` (solo al actualizar), `audience_ids`, `region_ids`

***

### `manage_brand_kit_writing_rule`

Crea o actualiza una regla de escritura para un Brand Kit. Las reglas pueden ser globales o limitarse a un solo tipo de contenido, audiencia o región (mutuamente excluyentes). El alcance se establece solo al crear.

**Requiere:** `brand_kit_id`

**Campos:** `texto` (obligatorio al crear), `content_type_id` (solo al crear), `audience_id` (solo al crear), `region_id` (solo al crear)

***

### `manage_brand_kit_custom_variable`

Crea o actualiza una variable personalizada para un Brand Kit. Las variables personalizadas no se recomiendan para la mayoría de los casos de uso. Es preferible usar regiones, audiencias, tipos de contenido o reglas de escritura.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `value` (obligatorio al crear)

***

### `create_brand_kit_direct_upload`

Inicia una carga directa de recursos visuales del Brand Kit, como logotipos, ejemplos visuales y archivos de fuentes. La herramienta devuelve una URL de carga firmada previamente, encabezados de carga y un `signed_id` para pasar a la herramienta de gestión del recurso visual correspondiente.

**Requiere:** `brand_kit_id`, `filename`, `content_type`, `byte_size`, `checksum`

**Devuelve:** `signed_id`, `upload_url`, y `upload_headers`.

***

### `manage_brand_kit_palette`

Crea o actualiza una paleta de colores para un borrador de Brand Kit.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear)

***

### `manage_brand_kit_palette_color`

Crea o actualiza un color dentro de una paleta de Brand Kit.

**Requiere:** `brand_kit_id`

**Campos:** `palette_id` (obligatorio al crear), `nombre` (obligatorio al crear), `value` (obligatorio al crear), `usage_instructions`

***

### `manage_brand_kit_logo_variant`

Crea o actualiza una variante de logotipo para un borrador de Brand Kit. Adjunta un archivo con `signed_id` desde `create_brand_kit_direct_upload` o con un `file_url`.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `background_color`, `usage_instructions`, `signed_id`, `file_url`

***

### `manage_brand_kit_logo_size`

Crea o actualiza las dimensiones recomendadas del logotipo y las instrucciones de uso.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `width`, `height`, `usage_instructions`

***

### `manage_brand_kit_font`

Crea o actualiza una fuente de Brand Kit. Adjunta un archivo de fuente con `signed_id` desde `create_brand_kit_direct_upload` o con un `file_url`.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `usage_instructions`, `google_font_link`, `signed_id`, `file_url`

***

### `manage_brand_kit_type_size`

Crea o actualiza un tamaño tipográfico asociado con una fuente de Brand Kit.

**Requiere:** `brand_kit_id`

**Campos:** `font_id`, `nombre` (obligatorio al crear), `weight`, `size`, `line_height`, `usage_instructions`

***

### `manage_brand_kit_usage_rule`

Crea o actualiza una regla de uso del Brand Kit. `applies_to` se establece al crear y no puede cambiarse después.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `applies_to` (obligatorio al crear)

***

### `manage_brand_kit_visual_use_case`

Crea o actualiza un caso de uso visual, un grupo con nombre de ejemplos visuales con instrucciones compartidas.

**Requiere:** `brand_kit_id`

**Campos:** `nombre` (obligatorio al crear), `instructions`

***

### `manage_brand_kit_visual_example`

Crea o actualiza un ejemplo visual para un Brand Kit. Los ejemplos visuales deben agruparse bajo un caso de uso visual. Adjunta una imagen con `signed_id` desde `create_brand_kit_direct_upload` o con un `file_url`.

**Requiere:** `brand_kit_id`

**Campos:** `visual_use_case_id` (obligatorio al crear), `title` (obligatorio al crear), `sample_url`, `usage_instructions`, `signed_id`, `file_url`

***

### Edita un borrador de Brand Kit <a href="#suggest_brand_kit_edits" id="suggest_brand_kit_edits"></a>

Usar `update_brand_kit` para los campos base y la herramienta apropiada `manage_brand_kit_*` para las entidades relacionadas. Resume los cambios previstos y obtiene la confirmación del usuario antes de aplicarlos.

Estas herramientas escriben directamente en el borrador. Vuelve a leer el borrador para verificar el resultado y dile al usuario que los cambios aún no están activos. Pide confirmación explícita antes de llamar a `publish_brand_kit`; publicar es una acción aparte que activa todos los cambios pendientes.

Los anteriores `suggest_brand_kit_edits` la herramienta de revisión interactiva ya no está disponible.

***

## Prompts y respuestas de AEO

### `list_aeo_prompts`

Enumera los prompts de IA rastreados para un Brand Kit.

**Requiere:** `brand_kit_id`

**Devuelve:** ID del prompt, texto, palabra clave, si se menciona la marca, volumen, ID del tema, marcas de tiempo, mention\_rate, citation\_rate y tendencias.

| Parámetro            | Valores                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------ |
| **Filtros**          | text, strategy, brand\_mentioned, topic\_id, prompt\_volume, mention\_rate, citation\_rate |
| **Ordenar**          | text, created\_at, prompt\_volume, mention\_rate, citation\_rate                           |
| **Incluye**          | topic, tags                                                                                |
| **Filtros de fecha** | start\_date, end\_date, providers, countries, personas                                     |

***

### `create_aeo_prompt`

Crea un nuevo prompt de AEO rastreado para un Brand Kit. Los trabajos en segundo plano analizan el prompt, extraen palabras clave y calculan métricas de volumen después de la creación.

**Requiere:** `brand_kit_id`, `texto`, `topic_id`

**Campos opcionales:** `countries`, `persona_ids`, `platforms`

{% hint style="warning" %}
Crear prompts puede afectar el volumen de respuestas. Confirma el texto del prompt, el tema y las asignaciones con el usuario antes de llamar a esta herramienta.
{% endhint %}

***

### `get_prompt_answers`

Obtén respuestas de IA para un prompt específico.

**Requiere:** `prompt_id`

**Devuelve:** ID de la respuesta, texto (truncado), proveedor, país, brand\_mentioned, brand\_cited, marcas de tiempo y los campos de solo lectura del prompt `intent_stage` (`awareness`, `consideration`, `evaluation`, `purchase`, o `null`).

| Parámetro   | Valores             |
| ----------- | ------------------- |
| **Filtros** | countries, personas |
| **Ordenar** | created\_at         |
| **Incluye** | persona             |

***

### `get_answer`

Obtén una respuesta de IA específica por ID con el contenido completo del texto.

**Requiere:** `id`

**Devuelve:** Texto completo de la respuesta (no truncado), proveedor, país, brand\_mentioned, brand\_cited, solo lectura `intent_stage`, y opcionalmente citas, menciones y detalles de la persona.

| Parámetro   | Valores                      |
| ----------- | ---------------------------- |
| **Incluye** | citations, mentions, persona |

Usa esto después de `get_prompt_answers` para recuperar el texto completo de la respuesta con las URLs de cita y las posiciones.

***

### `list_answers`

Enumera las respuestas de IA en todo un Brand Kit con filtros por rango de fechas, proveedores, países, personas y otras dimensiones de AEO. Usa esto cuando necesites respuestas de muchos prompts en lugar de respuestas de un solo prompt.

**Requiere:** `brand_kit_id`

Cada respuesta incluye los campos de solo lectura del prompt `intent_stage`, o `null` cuando la clasificación no está disponible.

***

## Configuración de AEO y gestión de prompts

### `create_aeo_persona`

Crea una nueva persona de AEO para un Brand Kit. Las personas representan las perspectivas de usuario usadas para simular consultas de búsqueda de IA.

**Requiere:** `brand_kit_id`, `title`, `descripción`

**Campos opcionales:** `add_to_all_prompts`

***

### `add_aeo_region`

Añade un código de país ISO alfa-2 a las regiones de AEO configuradas de un Brand Kit.

**Requiere:** `brand_kit_id`, `country_code`

**Campos opcionales:** `add_to_all_prompts`

***

### `list_tags`

Enumera las etiquetas de AEO configuradas para un Brand Kit.

**Requiere:** `brand_kit_id`

| Parámetro   | Valores             |
| ----------- | ------------------- |
| **Filtros** | nombre              |
| **Ordenar** | nombre, created\_at |

***

### `create_aeo_tag`

Crea una nueva etiqueta de AEO en un Brand Kit. Las etiquetas son rótulos definidos por el usuario que pueden aplicarse a prompts.

**Requiere:** `brand_kit_id`, `nombre`

**Campos opcionales:** `color`

***

### `update_aeo_tag`

Actualiza el nombre o el color de una etiqueta de AEO. Las etiquetas de prompts existentes se conservan.

**Requiere:** `brand_kit_id`, `tag_id`

**Campos:** `nombre`, `color`

***

### `delete_aeo_tag`

Elimina una etiqueta de AEO de un Brand Kit y quítala de todos los prompts que la usen.

**Requiere:** `brand_kit_id`, `tag_id`

{% hint style="warning" %}
Esta acción elimina la etiqueta de forma permanente y quita sus asignaciones de prompts. Confirma la etiqueta y su impacto antes de llamarla.
{% endhint %}

***

### `bulk_update_aeo_prompt_tags`

Añade o elimina una o más etiquetas en un lote de prompts de AEO en una sola transacción.

**Requiere:** `brand_kit_id`, `prompt_ids`, `operation`, `tag_ids`

**Operaciones:** `add`, `remove`

***

### `update_aeo_prompt_assignments`

Prepara cambios de asignación en borrador para uno o más prompts de AEO. Las asignaciones incluyen países, personas y plataformas. Los cambios no se publican hasta `commit_aeo_prompt_assignments` se ejecute.

**Requiere:** `brand_kit_id`, `prompts`

**Campos del prompt:** `prompt_id`, `countries`, `persona_ids`, `platforms`

***

### `get_aeo_prompt_assignments_status`

Inspecciona el estado actual del borrador de asignaciones de prompts para un Brand Kit. Úsalo para comprobar si existe un borrador, si tiene cambios y si confirmarlo excedería el límite de respuestas del espacio de trabajo.

**Requiere:** `brand_kit_id`

***

### `commit_aeo_prompt_assignments`

Confirma el borrador actual de asignaciones de prompts para hacerlo activo. Esto reemplaza las asignaciones activas de países, personas y plataformas por el estado del borrador.

**Requiere:** `brand_kit_id`

{% hint style="warning" %}
Esto afecta a las asignaciones activas de seguimiento de AEO. Confirma con el usuario antes de confirmar.
{% endhint %}

***

### `discard_aeo_prompt_assignments`

Descarta el borrador actual de asignaciones de prompts y crea un borrador nuevo a partir de las asignaciones activas.

**Requiere:** `brand_kit_id`

{% hint style="warning" %}
Esto descarta todas las ediciones de asignación pendientes en el borrador compartido, incluidas las ediciones de la interfaz no guardadas. Confirma con el usuario antes de llamarlo.
{% endhint %}

***

## Citas y dominios

Usar `prompt_type` con operador `EQUALS` y valor `brand` o `category` para filtrar según si el prompt menciona tu marca. Usa `brand_mentioned` con operador `EQ` y valor `true` o `false` para filtrar según si la página que cita menciona tu marca.

Los antiguos `brand_mentioned EQUALS brand/category` y `brand_referenced EQ true/false` filtros siguen aceptándose como alias de compatibilidad. Prefiere los nombres explícitos anteriores; tienen prioridad cuando se proporcionan tanto filtros antiguos como nuevos. El `brand_mentioned` filtro sobre `list_aeo_prompts` sigue refiriéndose al texto del prompt.

### `list_aeo_citations`

Enumera citas (URLs) con métricas para un Brand Kit. Muestra URLs individuales que se citan en respuestas de IA.

**Requiere:** `brand_kit_id`

**Devuelve:** URL, nombre de dominio, categoría de dominio, cantidad de citas, cuota de citas, tasa de citas, puntuación de influencia, tipo de página, sentimiento de marca, tendencias y metadatos sociales cuando estén disponibles.

La `social` el objeto identifica la plataforma y contiene `content` y `account` sobres con metadatos, métricas y estado de sincronización. Es `null` cuando no existe un registro social compatible. La cuenta puede ser `null` cuando existe contenido sin una cuenta asociada. La recopilación pendiente o fallida puede dejar metadatos incompletos.

Los metadatos del contenido de YouTube incluyen `duration_seconds`, `format`, y `sponsorship_status`. La duración puede ser `null`; el formato y el estado de patrocinio usan `unknown` cuando no esté disponible.

| Parámetro            | Valores                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Filtros**          | domain\_category, domain\_id, topic\_id, prompt\_type, brand\_mentioned, page\_type, brand\_sentiment, mentioned\_competitor\_domains |
| **Ordenar**          | citation\_count, citation\_share, citation\_rate, influence\_score                                                                    |
| **Filtros de fecha** | start\_date, end\_date, providers, countries, personas                                                                                |

**Categorías de dominio:** Propios, Competidores, Sociales, Comunidades, Reseñas, Medios, Educativos, Mercados, Productos, Afiliados, Otros

***

### `get_aeo_citation`

Obtén detalles y prompts que citan una URL específica.

**Requiere:** `brand_kit_id`, `id` (el ID de la cita/URL)

**Devuelve:** Detalles de la URL, métricas de cita, desglose de la puntuación de influencia, tipo de página, sentimiento de marca, competidores mencionados y el mismo `social` sobre devuelto por `list_aeo_citations`.

***

### `list_aeo_domains`

Enumera los dominios citados en las respuestas de IA para un Brand Kit. Agregado por dominio con métricas de cita.

**Requiere:** `brand_kit_id`

**Devuelve:** ID del dominio, nombre, categoría, URL del logotipo, cantidad de citas, cantidad de URLs, cuota de citas, tasa de citas y tendencias.

| Parámetro            | Valores                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------- |
| **Filtros**          | domain\_category, topic\_id, prompt\_type, brand\_mentioned, page\_type, brand\_sentiment |
| **Ordenar**          | citation\_count, citation\_share, citation\_rate                                          |
| **Filtros de fecha** | start\_date, end\_date, providers, countries, personas                                    |

***

## Anuncios y anunciantes observados por AEO

Anuncios que AirOps observa en las respuestas de ChatGPT y Google AI Mode para tus prompts rastreados. Estas herramientas consultan datos de anuncios observados usados por [Ads](/docs/es/insights/ads.md), incluidos **Biblioteca de anuncios**, por lo que no necesitan conexión a una cuenta de ChatGPT Ads.

{% hint style="info" %}
La cobertura se limita a los anuncios que AirOps ha visto en su propia recopilación de respuestas. Estas cifras no describen la cobertura total del mercado, la intención de segmentación, la entrega de impresiones ni el gasto del anunciante.
{% endhint %}

### `list_aeo_ads`

Enumera los anuncios observados en las respuestas de ChatGPT y Google AI Mode para un Brand Kit. Cada fila representa una plataforma y un par de creatividades observado. La misma creatividad en dos plataformas produce dos filas, cada una con sus propios conteos de actividad.

**Requiere:** `brand_kit_id`

**Devuelve:** Proveedor, ID de creatividad observada, ID de familia observada, nombre del anunciante, dominio, tipo y logotipo, título y cuerpo del anuncio, apariciones, respuestas, prompts, frecuencia, first\_seen, last\_seen y days\_active.

| Parámetro            | Valores                                                      |
| -------------------- | ------------------------------------------------------------ |
| **Filtros**          | topic\_id, prompt\_id, prompt\_type                          |
| **Filtros de fecha** | start\_date, end\_date, providers, countries, personas, tags |

**Tipos de anunciante:** propio, competidor, otro

`list_aeo_ads` incluye ambos proveedores compatibles de forma predeterminada. Pasa `providers: ["chat_gpt"]` o `providers: ["google_ai_mode"]` para limitar el alcance. Usa `prompt_type IGUAL A brand/category` para la clasificación del prompt; el anterior `brand_mentioned` filtro de tipo de prompt sigue siendo un alias de compatibilidad.

***

### `get_aeo_ad`

Obtén un anuncio observado, incluida su imagen creativa y la URL de destino.

**Requiere:** `brand_kit_id`, `id` (el `observed_creative_id` devuelto por `list_aeo_ads`)

**Devuelve:** Proveedor, ID de creatividad observada, ID de familia observada, nombre del anunciante, dominio, tipo y logotipo, título y cuerpo del anuncio, image\_url, target\_url, first\_seen, last\_seen y days\_active.

Pasa el proveedor de la fila como un `providers` arreglo junto con su ID creativo, por ejemplo `providers: ["google_ai_mode"]`. Las solicitudes de detalle usan ChatGPT de forma predeterminada cuando no se especifica un proveedor y requieren un único proveedor cuando se proporciona uno.

Las métricas por ventana reportadas por `list_aeo_ads` (apariciones, respuestas, prompts, frecuencia) no se devuelven aquí.

***

### `list_aeo_advertisers`

Lista los anunciantes observados en las respuestas de ChatGPT y Google AI Mode para un Brand Kit. Cada anuncio observado se agrupa bajo el anunciante que lo publicó, identificado por su dominio canónico.

**Requiere:** `brand_kit_id`

**Devuelve:** ID del anunciante, nombre, dominio, tipo, URL del logotipo, recuento único de anuncios, apariciones, respuestas, prompts, first\_seen y last\_seen.

| Parámetro            | Valores                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| **Filtros**          | topic\_id, prompt\_id, prompt\_type                                                               |
| **Ordenar**          | advertiser\_name, advertiser\_domain, ads, appearances, answers, prompts, first\_seen, last\_seen |
| **Filtros de fecha** | start\_date, end\_date, providers, countries, personas, tags                                      |

Los resultados se ordenan por recuento único de anuncios, primero el más prolífico, a menos que pases **Ordenar**. Usa `list_aeo_ads` para los anuncios individuales detrás de los recuentos de cada anunciante.

***

## Playbooks y comentarios

Lee las definiciones de Playbook, inspecciona las salidas de las Session y los comentarios del revisor, y ejecuta o publica Playbooks con los permisos de tu espacio de trabajo existentes. Publicar y ejecutar requieren autenticación OAuth del usuario. Las ejecuciones pueden consumir créditos del espacio de trabajo y realizar las acciones configuradas en el Playbook.

### `list_playbooks`

Lista los Playbooks editables, incluidos los metadatos de borrador y de la versión activa.

**Requiere:** `workspace_id`

**Opcional:** `búsqueda` (título), `página` (predeterminado 1), `por_página` (predeterminado 20, máximo 50).

### `get_playbook`

Lee la configuración y definición de un Playbook en Markdown. Las referencias de integración no exponen credenciales.

**Requiere:** `playbook_id`

**Opcional:** `version_number`. Omítelo para leer el borrador actual (**Última**); proporciona un número para leer una versión publicada inmutable.

### `list_playbook_sessions`

Lista las Sessions en orden cronológico inverso.

**Requiere:** `workspace_id`

**Opcional:** `playbook_id`, `estado`, `búsqueda` (nombre de la Session o del creador), `página` (predeterminado 1), `por_página` (predeterminado 20, máximo 50). Las Sessions archivadas usan el estado público `archivado`.

### `get_playbook_session`

Inspecciona los metadatos de la Session y una página de eventos, incluyendo texto, resultados de herramientas, artefactos y estado de finalización.

**Requiere:** `session_id`

**Opcional:** `after_id` (cursor del evento), `limit` (predeterminado 20, máximo 50).

Pasa el `next_after_id` como `after_id` devuelto para continuar hasta que sea `null`. Las vistas previas de texto están limitadas a 2.000 caracteres; `content_truncated: true` indica que existe más texto. Usa `read_playbook_output` para ver la salida completa.

### `read_playbook_output`

Lee una salida de texto en páginas basadas en caracteres. Los artefactos de texto colaborativos reflejan el contenido actual del editor, incluidas las ediciones realizadas después de la ejecución. Los artefactos binarios no son compatibles.

**Requiere:** `session_id` y exactamente uno de `event_id` o `artifact_path`. Las rutas de artefactos deben identificar un archivo bajo `artifacts/external/`.

**Opcional:** `offset` (predeterminado 0), `max_chars` (predeterminado 20.000, máximo 200.000).

**Devuelve:** `content`, `offset`, `total_chars`, y `next_offset`. Pasa `next_offset` de vuelta como `offset` hasta que sea `null`.

### `list_artifact_comments`

Lee los comentarios del revisor con autor, marcas de tiempo, estado de resolución y el anclaje disponible o el contexto del texto circundante.

**Requiere:** `session_id`

**Opcional:** `artifact_path` para limitar los resultados a un solo artefacto.

Usa los comentarios junto con `read_playbook_output` para revisar los comentarios en contexto. Las sugerencias de cambios registrados se cuentan por separado en `suggestions_count`; no son hilos de comentarios. Esta herramienta lee los comentarios sin modificarlos.

### `publish_playbook`

Publica el borrador actual como una nueva versión activa.

**Requiere:** `playbook_id` y autenticación OAuth del usuario.

**Opcional:** `notes` para la versión publicada.

**Devuelve:** El ID de la versión activa y los metadatos de la versión. Confirma el borrador y la intención de publicación antes de llamar a esta herramienta; publicar activa el borrador pendiente.

### `run_playbook`

Inicia una Session asíncrona. Cada llamada inicia una nueva ejecución.

**Requiere:** `playbook_id` y autenticación OAuth del usuario.

**Opcional:** `inputs` indexadas por nombre de entrada, `message`, y `version_number`.

De forma predeterminada, esto ejecuta el borrador actual (**Última**). Pasa `version_number` para ejecutar una versión publicada específica. Ejecutar un borrador no lo publica. Confirma la versión, las entradas y la ejecución previstas antes de comenzar.

**Devuelve:** `session_id`, `session_uuid`, estado e información de la versión. Consulta periódicamente `get_playbook_session`, luego lee las salidas y comentarios según sea necesario.

## Workflows

Lista los Workflows ejecutables e inicia o inspecciona ejecuciones con los permisos de tu espacio de trabajo. Las ejecuciones pueden consumir créditos y realizar las acciones configuradas del Workflow.

### `list_workflows`

Lista los Workflows publicados que puedes ejecutar. Se excluyen los recursos solo de borrador, eliminados, de agente y heredados.

**Requiere:** `workspace_id`

**Opcional:** `búsqueda`, `página` (predeterminado 1), `por_página` (predeterminado 20, máximo 50).

### `run_workflow`

Inicia una ejecución asíncrona. Cada llamada inicia una nueva ejecución.

**Requiere:** `workflow_id`

**Opcional:** `inputs` indexadas por nombre de entrada y `version_number`.

El valor predeterminado es la versión publicada activa. Pasa `version_number` para seleccionar otra versión publicada. Confirma el Workflow, las entradas y la ejecución previstos antes de comenzar.

**Devuelve:** `execution_id`, estado e información del Workflow/versión.

### `get_workflow_execution`

Inspecciona el estado, la salida o el error de una ejecución.

**Requiere:** `execution_id` devuelto por `run_workflow`.

Consulta periódicamente esta herramienta para seguir la ejecución a través de estados como `pendiente`, `en ejecución`, `requiere revisión`, `éxito`, `error`, o `cancelado`. Un ID de ejecución devuelto significa que la ejecución ha comenzado; verifica su estado antes de considerar completa su salida.

## Ejemplo: revisar una ejecución de Playbook

1. Encuentra el Playbook con `list_playbooks` e inspecciona su definición con `get_playbook`.
2. Encuentra una Session con `list_playbook_sessions`, luego lee sus eventos con `get_playbook_session`.
3. Lee el texto completo con `read_playbook_output` y los comentarios del revisor con `list_artifact_comments`.
4. Resume la salida y los comentarios sin resolver para el revisor.

## Analítica de páginas

### `list_pages`

Lista páginas con métricas de AEO, Google Search Console y GA4.

**Requiere:** `brand_kit_id`

**Devuelve:** Para cada página: URL, ruta de carpeta, palabra clave principal y métricas:

* **AEO:** citations\_count, citation\_rate, prompts\_count y tendencias
* **GSC:** clics, impresiones, ctr, posición y tendencias
* **GA4:** tráfico, sesiones, engagement, average\_session\_engagement y tendencias
* **Analítica de agentes:** `user_browse` (visitas de agentes de IA), `ai_training` (rastreos de entrenamiento), y `ai_search` (rastreo de búsqueda web)

Agent Analytics debe estar conectado primero. Sus tres recuentos admiten filtrado y ordenación para las fechas seleccionadas, sin variantes de cambio. Usa `list_aeo_agent_analytics` para los Total Crawls y los desgloses diarios.

| Parámetro                | Valores                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Filtros**              | Cualquier campo de métrica, url, folder\_name, primary\_keyword, session\_source, session\_medium      |
| **Ordenar**              | Todos los campos de métrica, url, folder\_name                                                         |
| **Filtros inteligentes** | almost\_page\_one, losing\_clicks, rankings\_slipping, losing\_ai\_visibility, citation\_rate\_decline |

**Filtros inteligentes** (úsalo en lugar del filtrado manual):

| Filtro                  | Descripción                                                             |
| ----------------------- | ----------------------------------------------------------------------- |
| `almost_page_one`       | Páginas clasificadas del #11 al 20 (victorias rápidas para la página 1) |
| `losing_clicks`         | Clics en descenso con posición estable                                  |
| `rankings_slipping`     | Posición en descenso con el tiempo                                      |
| `losing_ai_visibility`  | Pérdida de citas AEO                                                    |
| `citation_rate_decline` | Pérdida de autoridad de IA con SEO estable                              |

***

### `create_page`

Añade una página a las páginas AEO de un Brand Kit. AirOps normaliza la URL, verifica que pertenezca al dominio AEO configurado del Brand Kit y exige que sea única dentro de ese Brand Kit.

**Requiere:** `brand_kit_id`, `url`

**Devuelve:** ID de la página, ID del Brand Kit, ID del dominio AEO, URL normalizada, estado rastreado, marca de tiempo de creación y un mensaje de confirmación.

Confirma la URL y el Brand Kit con el usuario antes de crear la página. Verifica el resultado con `list_pages` filtrado por URL. Esto añade la página a AirOps; no publica contenido en un CMS.

***

### `get_page_details`

Obtén métricas detalladas para una página específica.

**Requiere:** `id`

**Devuelve:** URL, carpeta, palabra clave principal, cuota de citas, tasa de citas, recuento único de preguntas citadas, métricas de GSC (clics, impresiones, posición, CTR) y todas las tendencias.

| Parámetro           | Valores                |
| ------------------- | ---------------------- |
| **Rango de fechas** | start\_date, end\_date |

***

### `get_page_prompts`

Obtén prompts de IA que citan una página específica.

**Requiere:** `brand_kit_id`, `web_page_id`

**Devuelve:** ID del prompt, texto, palabra clave, topic\_id, volumen, total\_answers, answers\_with\_citations, citation\_rate, mention\_rate y tendencias.

| Parámetro           | Valores                                    |
| ------------------- | ------------------------------------------ |
| **Filtros**         | providers, countries, personas, topic\_ids |
| **Incluye**         | topic                                      |
| **Rango de fechas** | start\_date, end\_date                     |

***

## Agent Analytics

### `list_aeo_agent_analytics`

Lista las solicitudes diarias de bots a las páginas rastreadas del Brand Kit. [Conectar Agent Analytics](/docs/es/insights/onsite/traffic.md) antes de consultar estos datos.

**Requiere:** `brand_kit_id`

**Devuelve:** Filas que contienen `date`, `platform`, `crawl_type`, y `count`. Los tipos de rastreo son `ai_search`, `ai_training`, `user_browse`, y `otras`. Las filas sin solicitudes se omiten.

| Parámetro           | Valores                                                              |
| ------------------- | -------------------------------------------------------------------- |
| **Rango de fechas** | `start_date`, `end_date`                                             |
| **Filtros**         | `platform`, `crawl_type`, o un solo `web_page_id` desde `list_pages` |
| **Ordenar**         | `date` (predeterminado), `count`, o `-count`                         |
| **Paginación**      | `página`, `por_página` (25 por defecto, 100 máximo)                  |

Lee cada página antes de sumar los recuentos. Agent Analytics **Total de rastreos** resumen cuenta los rastreos de búsqueda y de entrenamiento para los motores de IA rastreados. La **tabla de** tabla Total Crawls cuenta cada plataforma y tipo de rastreo para esa página. Usa la [guía de cálculo de la API](/docs/es/desarrolladores/api.md#agent-analytics) para el conjunto exacto de motores, las recetas de gráficos y el comportamiento de los límites de fecha.

## Analíticas

### `query_analytics`

Consulta analíticas con métricas, dimensiones y filtros flexibles. Interfaz estilo BI para análisis personalizados.

**Requiere:** `brand_kit_id`, `metrics`

**Devuelve:** Resultados de la consulta con las métricas solicitadas agrupadas por dimensiones, más metadatos.

**Métricas:**

| Métrica                                                         | Descripción                                              |
| --------------------------------------------------------------- | -------------------------------------------------------- |
| `mention_rate`                                                  | % de respuestas que mencionan la marca (0-100)           |
| `share_of_voice`                                                | Menciones de la marca frente a competidores (0-100)      |
| `citation_rate`                                                 | % de respuestas que citan el dominio de la marca (0-100) |
| `citation_share`                                                | Citas de la marca frente a todas las citas (0-100)       |
| `citation_count`                                                | Recuento absoluto de citas                               |
| `sentiment_score`                                               | Sentimiento promedio (0-100)                             |
| `Posición media`                                                | Posición media en las listas de respuestas               |
| `Total de respuestas de IA analizadas`                          | Total de respuestas analizadas                           |
| `% de las respuestas en las que se te menciona primero (0-100)` | % en el que la marca se menciona primero (0-100)         |

**Dimensiones** (máx. 3):

| Dimensión         | Descripción                        |
| ----------------- | ---------------------------------- |
| `date`            | Agrupar por período de tiempo      |
| `proveedor`       | Agrupar por proveedor de IA        |
| `topic`           | Agrupar por tema rastreado         |
| `competidor`      | Agrupar por competidor             |
| `country`         | Agrupar por región/país            |
| `persona`         | Agrupar por persona de cliente     |
| `domain`          | Agrupar por dominio citado         |
| `domain_category` | Agrupar por tipo de fuente de cita |

| Parámetro           | Valores                                                   |
| ------------------- | --------------------------------------------------------- |
| **granularidad**    | diario, semanal, mensual, total (predeterminado: total)   |
| **Rango de fechas** | start\_date, end\_date (predeterminado: últimos 7 días)   |
| **Filtros**         | providers, topics, countries, personas, brand\_mentioned  |
| **Límite**          | máx. de filas (predeterminado 100, máximo 1000)           |
| **order\_by**       | ordenación personalizada (p. ej., "citation\_count DESC") |

***

### `get_sentiment_theme_answers`

Obtén las respuestas detrás de un tema de sentimiento para que puedas inspeccionar el texto de respuesta de origen y ejemplos para ese tema.

**Requiere:** `brand_kit_id`, `sentiment_theme_id`

**Campos opcionales:** `start_date`, `end_date`, `providers`, `countries`, `topic_ids`, `persona_ids`, `página`, `por_página`

***

### `analytics_chart`

{% hint style="info" %}
**Aplicación interactiva:** Esta herramienta muestra un gráfico en la conversación. Disponible en **Codex a través del complemento de AirOps, Claude Web y Claude Desktop**.
{% endhint %}

Consulta analíticas y muéstralas como un gráfico interactivo. Devuelve datos con una referencia de interfaz para visualización.

**Requiere:** `brand_kit_id`, `metrics`

**Devuelve:** Datos del gráfico con visualización interactiva renderizada en la conversación.

| Parámetro           | Valores                                                                   |
| ------------------- | ------------------------------------------------------------------------- |
| **chart\_type**     | línea, barra, circular, área (predeterminado: línea)                      |
| **metrics**         | Igual que query\_analytics                                                |
| **dimensions**      | Igual que query\_analytics (máx. 2 para gráficos de línea con agrupación) |
| **granularidad**    | diario, semanal, mensual, total                                           |
| **Rango de fechas** | start\_date, end\_date                                                    |
| **Filtros**         | providers, topics, countries, personas, brand\_mentioned                  |
| **title**           | Título opcional del gráfico                                               |

**Restricciones:**

* Solo se pueden representar juntas métricas de la misma escala (porcentaje, recuento o posición)
* Los gráficos de área y de barras admiten métricas únicas con dimensiones únicas
* Los gráficos de línea admiten hasta 2 dimensiones, pero solo una métrica cuando se usan 2

***

## Informes

### `list_reports`

Lista los informes analíticos guardados.

**Requiere:** `brand_kit_id`

**Devuelve:** ID del informe, nombre, created\_at, updated\_at.

| Parámetro   | Valores                        |
| ----------- | ------------------------------ |
| **Filtros** | nombre                         |
| **Ordenar** | name, created\_at, updated\_at |
| **Incluye** | modules                        |

***

### `get_report`

Obtén un informe específico por ID.

**Requiere:** `brand_kit_id`, `id`

**Devuelve:** ID del informe, nombre, marcas de tiempo. Con `includes: ['modules']`, devuelve las configuraciones completas de los módulos.

***

## Grids

Herramientas para leer, escribir, crear y ejecutar AirOps Grids de forma programática. Úsalas para poblar datos, administrar columnas, activar ejecuciones de workflows y recuperar resultados.

### `create_grid`

Crea un nuevo Grid vacío de uso general con una hoja vacía. Usa `add_grid_column` para añadir columnas y `write_grid` para añadir filas.

**Requiere:** `nombre`

**Campos opcionales:** `workspace_id`

***

### `create_grid_sheet`

Crea una nueva hoja dentro de un Grid existente.

**Requiere:** `grid_id`, `nombre`

***

### `list_grids`

Lista los grids a los que el usuario autenticado tiene acceso. Usa `includes: ["grid_tables.grid_columns"]` para obtener la estructura de tablas y columnas necesaria para otras herramientas de grids.

**Devuelve:** ID del Grid, nombre, ID del espacio de trabajo y, opcionalmente, detalles de la tabla y las columnas (ID, título, tipo de dato, posición).

| Parámetro   | Valores                        |
| ----------- | ------------------------------ |
| **Filtros** | name, workspace\_id            |
| **Ordenar** | name, updated\_at, created\_at |
| **Incluye** | grid\_tables.grid\_columns     |

***

### `read_grid`

Lee filas de una tabla de grid. Devuelve las filas como objetos con los títulos de las columnas como claves.

**Requiere:** `grid_id`, `grid_table_id`

**Devuelve:** Metadatos del Grid, columnas (con indicador de escritura) y datos de filas con información de paginación.

Las columnas de Playbook también incluyen `playbook_id` y `artifacts`, con el `nombre` y `artifact_type`. Usa estos nombres al mapear la salida de una columna de Playbook a otra columna de ejecución.

| Parámetro             | Escribe | Predeterminado | Descripción                                                     |
| --------------------- | ------- | -------------- | --------------------------------------------------------------- |
| `filters`             | arreglo | ninguno        | Filtrar por valores de columna                                  |
| `filters[].column_id` | entero  | ninguno        | ID de columna por la que filtrar                                |
| `filters[].operator`  | cadena  | ninguno        | CONTAINS, NOT\_CONTAINS, EMPTY, NOT\_EMPTY, =, !=, >=, <=, >, < |
| `filters[].value`     | cadena  | ninguno        | Valor de filtro (no requerido para EMPTY/NOT\_EMPTY)            |
| `column_ids`          | arreglo | todos          | IDs de columna a incluir en los resultados                      |
| `limit`               | entero  | 50             | Filas por página (1–100)                                        |
| `offset`              | entero  | 0              | Desplazamiento de filas para la paginación                      |
| `truncate`            | entero  | 0              | Máximo de caracteres por celda (0 = sin truncamiento)           |

***

### `read_grid_cell`

Lee el valor completo de una sola celda del Grid. Úsalo cuando `read_grid` trunque una celda larga, como un artículo completo, un resumen, una carga útil JSON o un campo HTML.

**Requiere:** `grid_id`, `grid_table_id`, `row_id`, `column_id`

**Devuelve:** Título de la columna, valor completo y tipo de valor.

***

### `write_grid`

Crea o actualiza filas en una tabla de grid. Máximo 1000 filas por llamada.

**Requiere:** `grid_id`, `grid_table_id`, `mode`, `rows`

| Parámetro | Escribe | Descripción                                                                                                  |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `mode`    | cadena  | `create` para añadir filas nuevas, `update` para modificar filas existentes                                  |
| `rows`    | arreglo | Objetos de fila con los títulos de columna como claves. Para `update` modo, incluye `__id` con el ID de fila |

**Devuelve:** `rows_created` (modo create) o `rows_updated` y `cells_updated` (modo update).

{% hint style="info" %}
Los valores pueden ser cadenas, números, booleanos, arreglos u objetos. Los arreglos y objetos se almacenan como JSON. Los títulos de columna deben coincidir exactamente con las columnas existentes del grid. Usa `add_grid_column` para crear primero nuevas columnas.
{% endhint %}

***

### `run_grid_rows`

Activa la ejecución de una o más filas del grid. Esto ejecuta todas las columnas de workflow (ejecución de la app) para cada fila especificada, en orden de dependencia. La ejecución es asíncrona — esta herramienta devuelve inmediatamente metadatos de ejecución.

**Requiere:** `grid_id`, `grid_table_id`, `grid_row_ids`

| Parámetro      | Escribe | Descripción                                    |
| -------------- | ------- | ---------------------------------------------- |
| `grid_row_ids` | arreglo | IDs de las filas del grid a ejecutar (máx. 50) |

**Devuelve:** Metadatos de ejecución, incluidos los IDs de ejecución de fila con los que consultar periódicamente `get_grid_row_execution_status`.

{% hint style="info" %}
Máximo 50 filas por llamada. Use `get_grid_row_execution_status` para comprobar el progreso y la finalización.
{% endhint %}

***

### `get_grid_row_execution_status`

Compruebe el estado de las ejecuciones de filas de la cuadrícula. Use esto después de `run_grid_rows` para consultar hasta que se complete.

**Requiere:** `grid_id`, `row_execution_ids`

| Parámetro           | Escribe | Descripción                                           |
| ------------------- | ------- | ----------------------------------------------------- |
| `row_execution_ids` | arreglo | IDs de las ejecuciones de filas a comprobar (máx. 50) |

**Devuelve:** Estado general y detalle por columna de cada ejecución.

***

### `add_grid_column`

Añada una nueva columna a una tabla de cuadrícula. Use esto antes de `write_grid` cuando necesite escribir en una columna que aún no existe.

**Requiere:** `grid_id`, `grid_table_id`, `title`, `data_type`

| Parámetro   | Escribe | Descripción                                                                                                        |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `title`     | cadena  | Título de la columna                                                                                               |
| `data_type` | cadena  | texto, número, fecha y hora, markdown, URL, HTML, image\_from\_url, JSON, single\_select, playbook, app\_execution |
| `position`  | entero  | Posición opcional de la columna (se añade al final si se omite)                                                    |

**Devuelve:** ID, título, tipo de datos y posición de la columna creada.

Para una columna de Playbook, use `data_type: "playbook"` y proporcione `playbook_id`. Para una columna de Workflow, use `data_type: "app_execution"` y proporcione `workflow_id`. Configure `inputs` por nombre de entrada. Cada mapeo requiere `tipo` y `value`.

Al mapear desde una columna de Playbook, `value` es el ID de la columna de origen en la misma hoja, y `artifact_name` es el nombre exacto del artefacto:

```json
{
  "article": {
    "type": "column",
    "value": 123,
    "artifact_name": "Final Article"
  }
}
```

Este ejemplo es un `inputs` objeto. Copie el nombre del artefacto de `read_grid`, o de los `artifacts` metadatos devueltos cuando `add_grid_column` crea la columna de Playbook de origen.

***

### `update_grid_column`

Actualice el título, el tipo de datos o los mapeos de entrada de Playbook/Workflow de una columna de cuadrícula.

**Requiere:** `grid_id`, `grid_table_id`, `grid_column_id`, y al menos uno de `title`, `data_type`, o `inputs`

**Devuelve:** Los ID de la cuadrícula y de la hoja, además del ID, título, tipo de datos y posición de la columna actualizada. Las columnas de Playbook y Workflow también incluyen sus detalles de configuración.

Pasar `inputs` reemplaza todo el mapeo de entrada. Incluya cada entrada que quiera conservar. La herramienta no puede reubicar una columna ni cambiar qué Playbook o Workflow ejecuta.

***

### `delete_grid_column`

Elimine una columna de cuadrícula y sus columnas dependientes de salida de Workflow o de artefacto de Playbook.

**Requiere:** `grid_id`, `grid_table_id`, `grid_column_id`

**Devuelve:** `grid_id`, `grid_table_id`, y `deleted_column_ids` para todas las columnas afectadas.

{% hint style="warning" %}
Revise las columnas dependientes antes de eliminar. La eliminación se bloquea mientras hay ejecuciones de filas en curso para la hoja.
{% endhint %}

***

### Ejemplo: flujo de trabajo de datos de cuadrícula

Un flujo de trabajo programático típico que usa herramientas de cuadrícula:

1. **Descubrir:** Llame a `list_grids` con includes para encontrar la cuadrícula y su estructura de columnas
2. **Preparar:** Llame a `add_grid_column` para crear las columnas que falten
3. **Poblar:** Llame a `write_grid` con el modo `create` para añadir filas
4. **Ejecutar:** Llame a `run_grid_rows` para activar las columnas de workflow de la fila y luego consultar `get_grid_row_execution_status` hasta completarse
5. **Recuperar:** Llame a `read_grid` para obtener los resultados
6. **Actualizar:** Opcionalmente llame a `write_grid` con el modo `update` para escribir los datos de vuelta

***

## Bases de conocimiento

### `list_knowledge_bases`

Enumere todas las bases de conocimiento a las que tiene acceso. Las bases de conocimiento almacenan documentos para búsqueda semántica.

**Devuelve:** ID de la base de conocimiento, nombre, ID del espacio de trabajo, estado y número de documentos. Solo las bases de conocimiento con estado `listo` pueden buscarse.

| Parámetro   | Valores                              |
| ----------- | ------------------------------------ |
| **Filtros** | workspace\_name, name, workspace\_id |
| **Ordenar** | nombre, created\_at                  |

***

### `knowledge_base_manage`

Cree o actualice una base de conocimiento. Omita `knowledge_base_id` para crear una nueva base de conocimiento; proporciónelo para actualizar una existente.

**Campos:** `knowledge_base_id`, `nombre`, `workspace_id`

**Requerido al crear:** `nombre`, además de `workspace_id` cuando el usuario tiene acceso a varios espacios de trabajo.

**Devuelve:** ID de la base de conocimiento, nombre, ID del espacio de trabajo, estado, número de documentos y si fue creada.

***

### `search_knowledge_base`

Busque contenido relevante en una base de conocimiento mediante similitud semántica.

**Requiere:** `knowledge_base_id`, `query`

**Parámetros:** `top_k` (número de resultados, 1-20, valor predeterminado 5)

**Devuelve:** Contenido coincidente ordenado por relevancia.

***

### `knowledge_base_create_direct_upload`

Inicie el flujo de carga de archivos en dos pasos para la ingestión en la base de conocimiento. La herramienta devuelve una URL de carga firmada previamente, los encabezados requeridos y una `signed_id`.

**Requiere:** `knowledge_base_id`, `filename`, `content_type`, `byte_size`, `checksum`

**Devuelve:** `signed_id`, `upload_url`, y `upload_headers`.

***

### `knowledge_base_add_file`

Registre un archivo cargado en una base de conocimiento después de `knowledge_base_create_direct_upload`. El documento se pone en cola para su indexación.

**Requiere:** `knowledge_base_id`, `signed_id`, `nombre`, `document_type`

**Campos opcionales:** `metadata`

**Devuelve:** IDs de documentos creados y estado pendiente.

***

### `knowledge_base_add_urls`

Ingiere en masa una o más páginas web en una base de conocimiento. Cada URL se convierte en un documento separado y se indexa de forma asíncrona.

**Requiere:** `knowledge_base_id`, `urls`

**Campos opcionales:** `metadata`

**Devuelve:** IDs de documentos creados y estado pendiente.

***

### `knowledge_base_get_status`

Obtenga el estado de indexación de la base de conocimiento y el estado de cada documento. Use esto después de añadir archivos o URLs.

**Requiere:** `knowledge_base_id`

**Campos opcionales:** `document_ids`, `cursor`, `items`

***

### `knowledge_base_get_document`

Obtenga un documento de la base de conocimiento por ID, incluidos los metadatos del documento y el contenido extraído cuando esté disponible.

**Requiere:** `knowledge_base_id`, `document_id`

***

### `knowledge_base_update_document_metadata`

Reemplace los metadatos visibles para el usuario de un documento. Los metadatos son un objeto clave/valor de un solo nivel y pueden usarse en los filtros de búsqueda de la base de conocimiento.

**Requiere:** `knowledge_base_id`, `document_id`, `metadata`

***

### `knowledge_base_delete_document`

Elimine permanentemente un único documento de una base de conocimiento.

**Requiere:** `knowledge_base_id`, `document_id`

{% hint style="warning" %}
Esta acción no se puede deshacer. Confirme con el usuario antes de eliminar un documento.
{% endhint %}

***

### `knowledge_base_delete`

Elimine permanentemente una base de conocimiento y todos sus documentos.

**Requiere:** `knowledge_base_id`

{% hint style="warning" %}
Esto elimina la base de conocimiento, todos los documentos y los vectores subyacentes. Confirme con el usuario antes de llamarlo.
{% endhint %}

***

## Opciones de consulta

Todas las herramientas de lista admiten:

| Opción         | Descripción                                                                   |
| -------------- | ----------------------------------------------------------------------------- |
| **Filtros**    | Filtre por valores de campo (EQUALS, CONTAINS, EQ, NEQ, GT, LT, GEQ, LEQ, IN) |
| **Incluye**    | Solicite datos relacionados en una sola llamada                               |
| **Campos**     | Seleccione campos específicos para devolver                                   |
| **Ordenar**    | Ordene por campos admitidos (prefijo `-` para descendente)                    |
| **Paginación** | Controle los resultados con `página` y `por_página` (máx. 100)                |

***

## Proveedores de IA

Valores de proveedor disponibles para filtrar:

* `chat_gpt`
* `gemini`
* `perplexity`
* `google_ai_mode`
* `google_ai_overview`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/docs/es/desarrolladores/tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.