Riferimento degli strumenti

Come si comportano gli strumenti

• I risultati sono JSON, restituiti come testo. render_chart restituisce anche un’immagine. Le date sono ISO 8601 in UTC.
• I siti si chiamano project. Quasi ogni strumento accetta projectId, un numero che ottieni da list_projects. Anche prompt, concorrenti e scansioni hanno id numerici.
• Gli assistenti hanno chiavi: openai (ChatGPT), anthropic (Claude), perplexity, gemini, google_aio (AI Overviews), google_ai_mode (AI Mode).
• I report descrivono lo stato attuale: l’ultima risposta per prompt per assistente, come spiegato sotto Metriche e stati. Nel JSON, “citato” è mentioned, “linkato” è ownCited, la tua posizione è brandRank, e visibility è il punteggio di visibilità.
• Gli errori tornano come risultato dello strumento contrassegnato come errore, con il testo Error: … e lo stesso messaggio che mostrerebbe l’app.

L’etichetta accanto a ogni strumento è il livello di accesso minimo della chiave che può chiamarlo:

Spazio di lavoro e siti

whoami Lettura

Nessun parametro. Restituisce per conto di chi agisce la chiave: kind (token), tokenName, user (la persona che ha creato la chiave), org (lo spazio di lavoro: id, name, plan) e role (viewer, member o admin).

list_projects Lettura

Nessun parametro. Restituisce lo spazio di lavoro, i suoi limits (siti, prompt per sito, scansioni al mese e scansioni usate questo mese), i connectedAssistants, e una voce per sito: id, name, domain, industry, language, location, i conteggi dei prompt (total, active, draft), il numero di concorrenti, lastAnsweredAt, scanRunning, le stats attuali (risposte, mentionRate, citationRate, promptCoverage, avgRank, visibility, conteggi dei toni), i primi quattro brand per shareOfVoice, e nextSteps: cosa manca ancora nella configurazione del sito.

list_providers Lettura

Nessun parametro. Restituisce i sei assistenti con key, label, il model in uso, modelOptions, e se l’assistente è enabled.

create_project Lettura + scansione

Inizia a tracciare un sito. Rifiutato quando il numero di siti dello spazio di lavoro è esaurito, o quando l’indirizzo non è un dominio.

• name (testo, obbligatorio): il nome del brand come compare nelle risposte.
• url (testo, obbligatorio): il sito, per esempio brightloop.example.
• industry (testo).
• brandTerms (elenco di testi, fino a 50): altre grafie che indicano comunque il brand.
• competitors (elenco, fino a 50): oggetti con name e domain facoltativo.
• language (testo): la lingua per cui vengono chieste le risposte. Predefinito English.
• location (testo): dove si trova il cliente. Predefinito United States.

Restituisce il nuovo sito.

update_project Lettura + modifica

Modifica un sito. Parametri: projectId (obbligatorio) e uno qualsiasi tra name, industry, brandTerms, language, location, scanFrequencyDays (da 1 a 365, l’intervallo tra le scansioni programmate).

Restituisce project e reanalysis. Quando cambiano il nome o i termini del brand, ogni risposta conservata viene riletta subito e reanalysis dice quante risposte sono state lette e quante citano il brand prima e dopo. Nessun assistente viene chiamato per questo.

Report

get_dashboard Lettura

Il report settimanale di un sito, i dati dietro la Dashboard.

• projectId (obbligatorio).
• week (YYYY-MM-DD): una data qualsiasi dentro la settimana che vuoi. Omesso, l’ultima settimana.

Le parti principali del risultato:

• now e previous: conteggi e quote per la settimana e per quella precedente (answers, mentioned, mentionRate, ownCited, citationRate, promptCoverage, avgRank, visibility, conteggi dei toni).
• verdict: un titolo e un riepilogo di un paragrafo della settimana.
• leaderboard: tu e ogni concorrente tracciato con le risposte in cui è citato, la share of voice e la variazione.
• shareOfVoice, sources (i cinque domini più citati, le citazioni delle tue pagine), assistants (una riga per assistente).
• changes: gained e lost (prompt in cui un assistente ha iniziato o smesso di citarti, al massimo 50 ciascuno), e linkGained e linkLost per i link.
• categories (numeri per categoria), activity (le scansioni della settimana, risposte raccolte, spesa) e actions (fino a tre prossimi passi suggeriti).

Prima della prima scansione restituisce un breve testo che dice che non c’è nulla da riportare.

get_trends Lettura

Settimana per settimana per un sito: le ultime dieci settimane.

• projectId (obbligatorio).
• limit (da 1 a 200, predefinito 25): il massimo di prompt da restituire in ogni elenco.

Restituisce weeks; weekByWeek (per settimana: risposte, mentionRate, citationRate, promptCoverage e visibility, ciascuno con la sua variazione); wonLost (prompt vinti e persi per settimana); topics (per categoria, la quota dei suoi prompt che ti citano, per settimana); topPrompts (i prompt con il punteggio di visibilità più alto: latest è il punteggio, change1w e change4w la sua variazione su una e quattro settimane); e stability con tre elenchi e i loro counts:

Prompt

list_prompts Lettura

I prompt tracciati di un sito con il verdetto attuale di ogni assistente.

• projectId (obbligatorio).
• q: ricerca testuale nel prompt.
• category: il nome di una categoria.
• status: draft, active o paused.
• verdict: named, lost (un concorrente tracciato è citato, e tu non sei né citato né linkato), cited (linkato ma non citato), missing (nessuno dei due) o failed. Le regole esatte sono quelle del filtro Risultato.
• competitor: il nome di un concorrente tracciato che una risposta attuale cita.
• stability: held, volatile o lost, come definiti sotto get_trends.
• scanned: yes o never.
• sort: created (predefinito), text, category, rank o scanned. dir: asc o desc.
• page (da 1) e perPage (da 5 a 200, predefinito 20).

Restituisce total, page, lastPage, engines (gli assistenti che hanno risposto), facets (le categorie, le fonti e i concorrenti per cui filtrare) e prompts. Ogni prompt ha id, text, category, status, intent, source, bestRank, lastScanAt, stability e verdicts: per assistente, uno tra named first, named, linked, not named, not named, failed.

get_prompt Lettura

Un prompt per intero, con la risposta di un assistente parola per parola. La risposta porta surface (app, api o google: da dove è stata letta, vedi Da dove arriva una risposta) e askedFrom (paese, lingua, ricerca web).citedInsteadOfYou elenca, sulle ultime risposte, i siti di terzi citati dove un concorrente è citato e tu no, con i rivali e gli assistenti accanto a ciascuno.

• projectId, promptId (obbligatori).
• engine: l’assistente la cui risposta includere. Omesso, il primo che ha risposto.

Restituisce prompt; verdicts per assistente (mentioned, brandRank, ownCited, sentiment, error, scannedAt); heatmap (per assistente e settimana, un livello da 0 a 3: non visibile, solo linkato, citato, citato per primo); e answer: provider, model, scannedAt, i verdetti, howDescribed (la frase che ti descrive), il text completo, competitorsNamed, searches (le ricerche web eseguite dall’assistente, quando le rivela) e sources. Le fonti arrivano in quattro gruppi: own (il tuo sito), opportunity (pagine di terzi), competitor (siti dei concorrenti) e reference (documentazione e siti ufficiali), ogni pagina con il suo url, kind e citedTimes.

add_prompts Lettura + modifica

Aggiunge prompt a un sito.

• projectId (obbligatorio).
• prompts (elenco da 1 a 200, obbligatorio). Ogni elemento: text (da 3 a 500 caratteri, obbligatorio), category, intent (informational, commercial, transactional, navigational; predefinito informational), funnel (awareness, consideration, decision; predefinito awareness), status (predefinito active).

Restituisce added (un conteggio) e failed: i testi che non sono stati aggiunti, ciascuno con il motivo. Un testo già tracciato sul sito, e tutto ciò che supera il limite di prompt del sito, finisce lì.

update_prompt Lettura + modifica

Modifica un prompt. Parametri: projectId, promptId (obbligatori) e uno qualsiasi tra text, category, intent, funnel, status. Le risposte raccolte restano con il prompt; un nuovo testo cambia ciò che chiedono le scansioni successive. category sostituisce tutte le categorie del prompt con quella sola. Restituisce il prompt.

bulk_update_prompts Lettura + modifica

Modifica molti prompt in una volta. Parametri: projectId, ids (da 1 a 5000 id di prompt, obbligatorio) e uno o più tra status, category (li classifica solo sotto questa categoria), addCategory (aggiunge una categoria a quelle che ogni prompt già ha), delete (true elimina i prompt insieme alle loro risposte e non può essere annullato). Restituisce ok.

import_queries Lettura + modifica

Importa un elenco di prompt o query di ricerca come testo, nel formato descritto sotto Importare i prompt.

• projectId (obbligatorio).
• contents (testo, obbligatorio): le righe del file.
• status: draft (predefinito) o active.
• dryRun (true o false): conta soltanto cosa succederebbe.

Restituisce rows, created, updated (già tracciati; le loro categorie vengono sostituite quando la riga ne indica), skipped e categories (righe per categoria).

rewrite_queries Lettura + scansione

Riscrive le query di ricerca importate (“email automation pricing”) come domande complete, usando un modello IA. Non viene addebitato, ma richiede un credito superiore a zero, e può essere chiamato fino a 10 volte all’ora. Vengono toccati solo i prompt importati il cui testo è ancora la query originale; l’originale resta salvato come parola chiave del prompt. Parametri: projectId (obbligatorio), category (limita a una categoria), dryRun (mostra le riscritture senza salvare). Restituisce pending, written, skipped e pairs: ogni originale con la sua riscrittura.

Concorrenti e pagine

list_competitors Lettura

Parametro: projectId. Restituisce competitors (id, name, domain, aliases); answersCollected; ownNamedIn e namedIn (in quante risposte attuali siete citati tu e ogni concorrente); board (per te e ogni brand tracciato, la quota di risposte che lo cita, complessiva e per assistente); e suggestions: nomi non tracciati che compaiono in almeno tre risposte degli ultimi 28 giorni.

add_competitor Lettura + modifica

Parametri: projectId, name (obbligatorio), domain, aliases (fino a 30 altre grafie). Le risposte conservate vengono rilette subito per il nuovo brand, senza chiamare alcun assistente. Restituisce competitor e reanalysis.

update_competitor Lettura + modifica

Parametri: projectId, competitorId (entrambi obbligatori), name, domain, aliases. Restituisce competitor e reanalysis.

Cambia solo ciò che invii. Un valore omesso conserva ciò che è salvato; aliases sostituisce l’intero elenco; domain: null rimuove il dominio.

remove_competitor Lettura + modifica

Parametri: projectId, competitorId. Il brand smette di essere tracciato e le risposte conservate vengono rilette senza di esso. Le risposte stesse vengono conservate.

get_competitor_report Lettura

Parametri: projectId, competitorId. Un concorrente contro di te: numeri appaiati con le loro variazioni (tiles), per assistente (assistants), per categoria (topics), i prompt in cui è citato solo lui, entrambi, o solo tu (prompts), le pagine del suo sito citate dagli assistenti (pages), e i siti di terzi citati nelle risposte che citano lui e non te (sources: dominio, tipo, risposte, prompt, assistenti). Prima della prima scansione restituisce empty: true.

list_pages Lettura

Le pagine del tuo sito, lette dalla sua sitemap, e se una risposta attuale linka ciascuna. La sitemap viene letta quando il sito viene aggiunto e poi ogni settimana; import_sitemap la legge adesso.

• projectId (obbligatorio).
• shown: yes per le pagine che qualche risposta attuale linka, no per le altre.
• q: ricerca nell’indirizzo e nel titolo.
• page, perPage (da 5 a 200, predefinito 50).

Restituisce items (id, url, title, path, section, shownBy: gli assistenti che la linkano, prompts: quanti prompt portano a essa), total, siteTotal, shown e sections.

get_crawler_access Lettura

Cosa il tuo robots.txt lascia leggere a ogni crawler IA. Parametri: projectId (obbligatorio), check (true rilegge prima robots.txt e llms.txt; richiede una chiave Lettura + modifica).

Restituisce checkedAt, robots (status: found, missing o unreachable; url, httpStatus, error), llmsTxt (present, url), crawlers (ciascuno con token, operator, purpose, access: allowed, partial, blocked o unknown, la line decisiva e was quando è cambiato) e history. Vedi Accesso dei crawler IA.

list_search_queries Lettura

Le ricerche web eseguite dagli assistenti mentre rispondevano ai prompt attivi del sito, secondo l’ultima risposta per prompt e assistente, le più comuni per prime (fino a 500). Parametro: projectId.

Ogni elemento: query, answers (risposte che l’hanno eseguita), named (di quelle, quante ti hanno citato), providers, prompts (id, text) e tracked (esiste un prompt con esattamente questo testo).

import_sitemap Lettura + modifica

Parametro: projectId. Legge adesso la sitemap del sito (/sitemap.xml e le sitemap indicate dal robots.txt, seguendo un indice di sitemap) e aggiunge ogni pagina del tuo dominio non ancora elencata, fino a 5.000 indirizzi. Restituisce seen e added. Fallisce con un messaggio quando lì non si trovano pagine.

Scansioni

get_scan_options Lettura

Parametro: projectId. Con cosa può essere impostata una scansione: engines (gli assistenti collegati), models (per assistente: il modello predefinito e le altre opzioni, ciascuna con un label, un costPerAnswer stimato, una note e, quando non può essere scelta, il motivo in unavailable; per ChatGPT e Gemini le opzioni includono le risposte dell’app chatgpt-app / gemini-app (veloci, subito) e chatgpt-app-queue / gemini-app-queue (lente e più economiche, qualche minuto): la risposta come la mostra l’app), activePrompts, categories (prompt attivi per categoria), scansThisMonth e scansPerMonth (il limite dello spazio di lavoro), e spentThisMonth (il costo delle scansioni del sito in questo mese di calendario).

estimate_scan Lettura

Quanto costerebbe una scansione, prima che parta. Accetta le stesse scelte di start_scan:

• projectId (obbligatorio).
• providers (elenco di chiavi di assistenti): quali assistenti interrogare. Omesso, tutti quelli collegati.
• promptIds (elenco di id): un insieme scelto a mano. Omesso, ogni prompt attivo. I prompt non attivi vengono saltati.
• category: scansiona solo una categoria.
• sample (numero): scansiona solo quel numero di prompt, estratti a caso. repeats (1–5): poni ogni domanda quel numero di volte a ogni assistente; le risposte, e il prezzo, seguono (vedi Più risposte a una domanda).
• models (oggetto): da chiave dell’assistente a modello, per esempio {"openai": "gpt-5.4-mini"}. Il modello deve essere una delle opzioni di quell’assistente in get_scan_options.

Restituisce prompts, answers, cost (dollari USA) e formatted. Cosa include il numero: Stima del costo di una scansione.

start_scan Lettura + scansione

Avvia una scansione. Parametri: tutto ciò di estimate_scan, più budgetUsd (ferma la scansione quando ha raggiunto questo costo; 0 oppure omesso significa il doppio della sua stima) e label (fino a 60 caratteri). Restituisce la scansione: id, status, providers, total, completed, failed, costUsd, budgetUsd, startedAt.

La chiamata ritorna non appena la scansione è in coda; seguila con get_live_scan. Una scansione viene rifiutata, con il motivo come errore, quando un’altra scansione del sito è in corso, nessun prompt attivo corrisponde, il nome di un modello è sconosciuto, il credito non copre la scansione, il sito ha raggiunto il suo tetto mensile, o le scansioni del mese dello spazio di lavoro sono esaurite.

get_live_scan Lettura

Parametro: projectId. Restituisce run: null quando nulla è in corso, altrimenti la scansione con progress (elapsed, lastAnswer, secondi perAnswer, eta) e stalled (true quando ci sono risposte in coda e nessuna è arrivata dopo 20 secondi).

cancel_scan Lettura + scansione

Parametri: projectId, runId. Ferma una scansione in corso. Le risposte ancora in coda vengono scartate; una già in arrivo può ancora arrivare. Restituisce cancelled: false quando la scansione era già terminata.

list_scans Lettura

Parametro: projectId. Le ultime 30 scansioni del sito, le più recenti per prime, ciascuna con stato, assistenti, modelli, conteggi delle risposte e costUsd. Stati: queued, running, cancelling, cancelled, done, failed.

Grafici

render_chart Lettura

Disegna un grafico e lo restituisce come immagine, seguita dai valori tracciati come testo.

Chiedi uno dei grafici del sito con projectId e chart:

Oppure disegna i tuoi dati 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 e series sono obbligatori; suffix, horizontal e stacked sono facoltativi.
• week (YYYY-MM-DD): per i grafici report.*, una settimana passata.
• title (fino a 120 caratteri), width (da 300 a 2000, predefinito 900), height (da 200 a 1500), dark (true per uno sfondo scuro).

Risorsa e modelli di prompt

I client che supportano risorse e prompt MCP vedono anche:

I modelli consegnano soltanto un’istruzione pronta alla tua IA. Le proposte e la revisione sono scritte dalla tua IA, non da Teddit.

Ogni strumento tranne render_chart ha endpoint REST che restituiscono gli stessi dati; vedi Endpoint.