Referencia de herramientas

Cómo se comportan las herramientas

• Los resultados son JSON, devueltos como texto. render_chart devuelve además una imagen. Las fechas son ISO 8601 en UTC.
• Los sitios se llaman projects. Casi todas las herramientas toman projectId, un número que obtienes de list_projects. Los prompts, competidores y análisis también tienen ids numéricos.
• Los asistentes tienen claves: openai (ChatGPT), anthropic (Claude), perplexity, gemini, google_aio (AI Overviews), google_ai_mode (AI Mode).
• Los informes describen el estado actual: la última respuesta por prompt y asistente, como se explica en Métricas y estados. En el JSON, “nombrado” es mentioned, “enlazado” es ownCited, tu posición es brandRank, y visibility es la puntuación de visibilidad.
• Los errores vuelven como un resultado de herramienta marcado como error, con el texto Error: … y el mismo mensaje que mostraría la aplicación.

La etiqueta junto a cada herramienta es el acceso mínimo de clave que puede llamarla:

Espacio de trabajo y sitios

whoami Lectura

Sin parámetros. Devuelve en nombre de quién actúa la clave: kind (token), tokenName, user (la persona que creó la clave), org (el espacio de trabajo: id, name, plan) y role (viewer, member o admin).

list_projects Lectura

Sin parámetros. Devuelve el espacio de trabajo, sus limits (sitios, prompts por sitio, análisis al mes y análisis usados este mes), los connectedAssistants, y una entrada por sitio: id, name, domain, industry, language, location, recuentos de prompts (total, active, draft), el número de competidores, lastAnsweredAt, scanRunning, las stats actuales (respuestas, mentionRate, citationRate, promptCoverage, avgRank, visibility, recuentos de tono), las cuatro marcas principales por shareOfVoice, y nextSteps: lo que aún falta en la configuración del sitio.

list_providers Lectura

Sin parámetros. Devuelve los seis asistentes con key, label, el model en uso, modelOptions, y si el asistente está enabled.

create_project Lectura + análisis

Empieza a seguir un sitio. Se rechaza cuando el número de sitios del espacio de trabajo está agotado, o cuando la dirección no es un dominio.

• name (texto, obligatorio): el nombre de la marca tal como aparece en las respuestas.
• url (texto, obligatorio): el sitio, por ejemplo brightloop.example.
• industry (texto).
• brandTerms (lista de textos, hasta 50): otras grafías que siguen significando la marca.
• competitors (lista, hasta 50): objetos con name y domain opcional.
• language (texto): el idioma en el que se piden las respuestas. Por defecto English.
• location (texto): dónde está el cliente. Por defecto United States.

Devuelve el nuevo sitio.

update_project Lectura + edición

Cambia un sitio. Parámetros: projectId (obligatorio) y cualquiera de name, industry, brandTerms, language, location, scanFrequencyDays (de 1 a 365, el intervalo entre análisis programados).

Devuelve project y reanalysis. Cuando cambian el nombre o los términos de marca, cada respuesta guardada se vuelve a leer al momento y reanalysis dice cuántas respuestas se leyeron y cuántas nombran la marca antes y después. No se llama a ningún asistente para esto.

Informes

get_dashboard Lectura

El informe semanal de un sitio, los datos detrás del Panel.

• projectId (obligatorio).
• week (YYYY-MM-DD): cualquier fecha dentro de la semana que quieras. Si se omite, la última semana.

Las partes principales del resultado:

• now y previous: recuentos y proporciones de la semana y de la anterior (answers, mentioned, mentionRate, ownCited, citationRate, promptCoverage, avgRank, visibility, recuentos de tono).
• verdict: un titular y un resumen de un párrafo de la semana.
• leaderboard: tú y cada competidor seguido con las respuestas en que se le nombra, la cuota de voz y el cambio.
• shareOfVoice, sources (los cinco dominios más citados, citas de tus páginas), assistants (una fila por asistente).
• changes: gained y lost (prompts en los que un asistente empezó o dejó de nombrarte, como máximo 50 de cada), y linkGained y linkLost para los enlaces.
• categories (números por categoría), activity (los análisis de la semana, respuestas recogidas, gasto) y actions (hasta tres pasos siguientes sugeridos).

Antes del primer análisis devuelve un texto breve diciendo que no hay nada que informar.

get_trends Lectura

Semana a semana para un sitio: las últimas diez semanas.

• projectId (obligatorio).
• limit (de 1 a 200, por defecto 25): el máximo de prompts que devolver en cada lista.

Devuelve weeks; weekByWeek (por semana: respuestas, mentionRate, citationRate, promptCoverage y visibility, cada uno con su cambio); wonLost (prompts ganados y perdidos por semana); topics (por categoría, la proporción de sus prompts que te nombran, por semana); topPrompts (los prompts con mayor puntuación de visibilidad: latest es la puntuación, change1w y change4w su cambio en una y cuatro semanas); y stability con tres listas y sus counts:

Prompts

list_prompts Lectura

Los prompts seguidos de un sitio con el veredicto actual de cada asistente.

• projectId (obligatorio).
• q: búsqueda de texto en el prompt.
• category: el nombre de una categoría.
• status: draft, active o paused.
• verdict: named, lost (se nombra a un competidor seguido, y a ti ni te nombran ni te enlazan), cited (enlazado pero no nombrado), missing (ninguna de las dos) o failed. Las reglas exactas son las del filtro Resultado.
• competitor: el nombre de un competidor seguido que nombra una respuesta actual.
• stability: held, volatile o lost, según se define en get_trends.
• scanned: yes o never.
• sort: created (por defecto), text, category, rank o scanned. dir: asc o desc.
• page (desde 1) y perPage (de 5 a 200, por defecto 20).

Devuelve total, page, lastPage, engines (los asistentes que han respondido), facets (las categorías, fuentes y competidores por los que filtrar) y prompts. Cada prompt tiene id, text, category, status, intent, source, bestRank, lastScanAt, stability y verdicts: por asistente, uno de named first, named, linked, not named, not named, failed.

get_prompt Lectura

Un prompt completo, con la respuesta de un asistente palabra por palabra. La respuesta lleva surface (app, api o google: de dónde se leyó, ver De dónde viene una respuesta) y askedFrom (país, idioma, búsqueda web).citedInsteadOfYou lista, sobre las últimas respuestas, los sitios de terceros citados donde se nombra a un competidor y a ti no, con los rivales y asistentes junto a cada uno.

• projectId, promptId (obligatorios).
• engine: el asistente cuya respuesta incluir. Si se omite, el primero que respondió.

Devuelve prompt; verdicts por asistente (mentioned, brandRank, ownCited, sentiment, error, scannedAt); heatmap (por asistente y semana, un nivel de 0 a 3: no visible, solo enlazado, nombrado, nombrado primero); y answer: provider, model, scannedAt, los veredictos, howDescribed (la frase que te describe), el text completo, competitorsNamed, searches (las búsquedas web que realizó el asistente, cuando las revela) y sources. Las fuentes vienen en cuatro grupos: own (tu sitio), opportunity (páginas de terceros), competitor (sitios de competidores) y reference (documentación y sitios oficiales), cada página con su url, kind y citedTimes.

add_prompts Lectura + edición

Añade prompts a un sitio.

• projectId (obligatorio).
• prompts (lista de 1 a 200, obligatoria). Cada elemento: text (de 3 a 500 caracteres, obligatorio), category, intent (informational, commercial, transactional, navigational; por defecto informational), funnel (awareness, consideration, decision; por defecto awareness), status (por defecto active).

Devuelve added (un recuento) y failed: los textos que no se añadieron, cada uno con el motivo. Un texto que ya se sigue en el sitio, y todo lo que supere el límite de prompts del sitio, acaba ahí.

update_prompt Lectura + edición

Edita un prompt. Parámetros: projectId, promptId (obligatorios) y cualquiera de text, category, intent, funnel, status. Las respuestas recogidas se quedan con el prompt; un texto nuevo cambia lo que preguntan los análisis posteriores. category sustituye todas las categorías del prompt por esa. Devuelve el prompt.

bulk_update_prompts Lectura + edición

Cambia muchos prompts a la vez. Parámetros: projectId, ids (de 1 a 5000 ids de prompt, obligatorio) y uno o más de status, category (los clasifica solo en esa categoría), addCategory (añade una categoría a las que ya tiene cada prompt), delete (true elimina los prompts junto con sus respuestas y no se puede deshacer). Devuelve ok.

import_queries Lectura + edición

Importa una lista de prompts o consultas de búsqueda como texto, en el formato descrito en Importar prompts.

• projectId (obligatorio).
• contents (texto, obligatorio): las líneas del archivo.
• status: draft (por defecto) o active.
• dryRun (true o false): solo contar lo que pasaría.

Devuelve rows, created, updated (ya seguidos; sus categorías se sustituyen cuando la fila nombra alguna), skipped y categories (filas por categoría).

rewrite_queries Lectura + análisis

Reescribe consultas de búsqueda importadas (“email automation pricing”) como preguntas completas, usando un modelo de IA. No se cobra, pero necesita un saldo mayor que cero, y puede llamarse hasta 10 veces por hora. Solo se tocan los prompts importados cuyo texto sigue siendo la consulta original; el original queda guardado como palabra clave del prompt. Parámetros: projectId (obligatorio), category (limitar a una categoría), dryRun (mostrar las reescrituras sin guardar). Devuelve pending, written, skipped y pairs: cada original con su reescritura.

Competidores y páginas

list_competitors Lectura

Parámetro: projectId. Devuelve competitors (id, name, domain, aliases); answersCollected; ownNamedIn y namedIn (en cuántas respuestas actuales se os nombra a ti y a cada competidor); board (para ti y cada marca seguida, la proporción de respuestas que la nombran, en total y por asistente); y suggestions: nombres no seguidos que aparecen en al menos tres respuestas de los últimos 28 días.

add_competitor Lectura + edición

Parámetros: projectId, name (obligatorio), domain, aliases (hasta 30 otras grafías). Las respuestas guardadas se vuelven a leer al momento para la nueva marca, sin llamar a ningún asistente. Devuelve competitor y reanalysis.

update_competitor Lectura + edición

Parámetros: projectId, competitorId (ambos obligatorios), name, domain, aliases. Devuelve competitor y reanalysis.

Solo cambia lo que envías. Un valor omitido conserva lo guardado; aliases sustituye toda la lista; domain: null quita el dominio.

remove_competitor Lectura + edición

Parámetros: projectId, competitorId. La marca deja de seguirse y las respuestas guardadas se vuelven a leer sin ella. Las propias respuestas se conservan.

get_competitor_report Lectura

Parámetros: projectId, competitorId. Un competidor frente a ti: números emparejados con sus cambios (tiles), por asistente (assistants), por categoría (topics), los prompts donde solo se le nombra a él, a ambos, o solo a ti (prompts), las páginas de su sitio que citan los asistentes (pages), y los sitios de terceros citados en las respuestas que lo nombran a él y no a ti (sources: dominio, tipo, respuestas, prompts, asistentes). Antes del primer análisis devuelve empty: true.

list_pages Lectura

Las páginas de tu sitio, leídas de su sitemap, y si una respuesta actual enlaza a cada una. El sitemap se lee al añadir el sitio y de nuevo cada semana; import_sitemap lo lee ahora.

• projectId (obligatorio).
• shown: yes para las páginas que enlaza alguna respuesta actual, no para el resto.
• q: búsqueda en la dirección y el título.
• page, perPage (de 5 a 200, por defecto 50).

Devuelve items (id, url, title, path, section, shownBy: los asistentes que la enlazan, prompts: cuántos prompts llevan a ella), total, siteTotal, shown y sections.

get_crawler_access Lectura

Lo que tu robots.txt deja leer a cada rastreador de IA. Parámetros: projectId (obligatorio), check (true vuelve a leer antes robots.txt y llms.txt; necesita una clave de Lectura + edición).

Devuelve checkedAt, robots (status: found, missing o unreachable; url, httpStatus, error), llmsTxt (present, url), crawlers (cada uno con token, operator, purpose, access: allowed, partial, blocked o unknown, la line decisiva y was cuando cambió) e history. Ver Acceso de rastreadores de IA.

list_search_queries Lectura

Las búsquedas web que realizaron los asistentes al responder a los prompts activos del sitio, según la última respuesta por prompt y asistente, las más comunes primero (hasta 500). Parámetro: projectId.

Cada elemento: query, answers (respuestas que la realizaron), named (de esas, las que te nombraron), providers, prompts (id, text) y tracked (existe un prompt con exactamente este texto).

import_sitemap Lectura + edición

Parámetro: projectId. Lee ahora el sitemap del sitio (/sitemap.xml y los sitemaps que nombra robots.txt, siguiendo un índice de sitemaps) y añade cada página de tu propio dominio que aún no esté listada, hasta 5.000 direcciones. Devuelve seen y added. Falla con un mensaje cuando no se encuentran páginas ahí.

Análisis

get_scan_options Lectura

Parámetro: projectId. Con qué se puede configurar un análisis: engines (los asistentes conectados), models (por asistente: el modelo por defecto y las demás opciones, cada una con un label, un costPerAnswer estimado, una note y, cuando no se puede elegir, el motivo en unavailable; para ChatGPT y Gemini las opciones incluyen las respuestas de la aplicación chatgpt-app / gemini-app (rápida, al momento) y chatgpt-app-queue / gemini-app-queue (lenta y más barata, unos minutos): la respuesta tal como la muestra la aplicación), activePrompts, categories (prompts activos por categoría), scansThisMonth y scansPerMonth (el límite del espacio de trabajo), y spentThisMonth (el coste de los análisis del sitio en este mes natural).

estimate_scan Lectura

Lo que costaría un análisis, antes de ejecutarlo. Toma las mismas opciones que start_scan:

• projectId (obligatorio).
• providers (lista de claves de asistente): a qué asistentes preguntar. Si se omite, a todos los conectados.
• promptIds (lista de ids): un conjunto elegido a mano. Si se omite, todos los prompts activos. Los prompts que no están activos se omiten.
• category: analizar solo una categoría.
• sample (número): analizar solo ese número de prompts, elegidos al azar. repeats (1–5): hacer cada pregunta ese número de veces a cada asistente; las respuestas, y el precio, van en consecuencia (ver Varias respuestas a una pregunta).
• models (objeto): clave de asistente a modelo, por ejemplo {"openai": "gpt-5.4-mini"}. El modelo debe ser una de las opciones de ese asistente en get_scan_options.

Devuelve prompts, answers, cost (dólares estadounidenses) y formatted. Qué incluye la cifra: Estimación del coste de un análisis.

start_scan Lectura + análisis

Ejecuta un análisis. Parámetros: todo lo de estimate_scan, más budgetUsd (detener el análisis cuando haya costado esta cantidad; 0 u omitido significa el doble de su estimación) y label (hasta 60 caracteres). Devuelve el análisis: id, status, providers, total, completed, failed, costUsd, budgetUsd, startedAt.

La llamada vuelve en cuanto el análisis está en cola; síguelo con get_live_scan. Un análisis se rechaza, con el motivo como error, cuando otro análisis del sitio está en curso, ningún prompt activo coincide, un nombre de modelo es desconocido, el saldo no cubre el análisis, el sitio ha alcanzado su tope mensual, o los análisis del mes del espacio de trabajo están agotados.

get_live_scan Lectura

Parámetro: projectId. Devuelve run: null cuando no hay nada en curso; si no, el análisis con progress (elapsed, lastAnswer, segundos perAnswer, eta) y stalled (true cuando hay respuestas en cola y ninguna ha llegado tras 20 segundos).

cancel_scan Lectura + análisis

Parámetros: projectId, runId. Detiene un análisis en curso. Las respuestas aún en cola se descartan; una que ya está en camino puede llegar igualmente. Devuelve cancelled: false cuando el análisis ya había terminado.

list_scans Lectura

Parámetro: projectId. Los últimos 30 análisis del sitio, el más reciente primero, cada uno con estado, asistentes, modelos, recuentos de respuestas y costUsd. Estados: queued, running, cancelling, cancelled, done, failed.

Gráficos

render_chart Lectura

Dibuja un gráfico y lo devuelve como imagen, seguido de los valores dibujados como texto.

Pide uno de los gráficos propios del sitio con projectId y chart:

O dibuja tus propios datos con custom:

{
  "custom": {
    "type": "bar",
    "labels": ["Brightloop", "Mailora", "Quillsend"],
    "series": [{ "label": "Named in", "points": [12, 20, 16] }],
    "suffix": " answers",
    "horizontal": true
  },
  "title": "Answers naming each brand"
}

• custom.type: line o bar. labels y series son obligatorios; suffix, horizontal y stacked son opcionales.
• week (YYYY-MM-DD): para los gráficos report.*, una semana pasada.
• title (hasta 120 caracteres), width (de 300 a 2000, por defecto 900), height (de 200 a 1500), dark (true para fondo oscuro).

Recurso y plantillas de prompt

Los clientes que admiten recursos y prompts MCP también ven:

Las plantillas solo entregan a tu IA una instrucción ya hecha. Las propuestas y el repaso los escribe tu IA, no Teddit.

Todas las herramientas excepto render_chart tienen endpoints REST que devuelven los mismos datos; ver Endpoints.