Tools reference

How tools behave

• Results are JSON, returned as text. render_chart returns an image as well. Dates are ISO 8601 in UTC.
• Sites are called projects. Almost every tool takes projectId, a number you get from list_projects. Prompts, competitors and scans have numeric ids too.
• Assistants have keys: openai (ChatGPT), anthropic (Claude), perplexity, gemini, google_aio (AI Overviews), google_ai_mode (AI Mode).
• Reports describe the current state: the latest answer per prompt per assistant, as explained under Metrics and statuses. In the JSON, “named” is mentioned, “linked” is ownCited, your place is brandRank, and visibility is the visibility score.
• Errors come back as a tool result marked as an error, with the text Error: … and the same message the app would show.

The label next to each tool is the lowest key access that may call it:

Workspace and sites

whoami Read

No parameters. Returns who the key acts as: kind (token), tokenName, user (the person who created the key), org (the workspace: id, name, plan) and role (viewer, member or admin).

list_projects Read

No parameters. Returns the workspace, its limits (sites, prompts per site, scans per month and scans used this month), the connectedAssistants, and one entry per site: id, name, domain, industry, language, location, prompt counts (total, active, draft), the number of competitors, lastAnsweredAt, scanRunning, the current stats (answers, mentionRate, citationRate, promptCoverage, avgRank, visibility, tone counts), the top four brands by shareOfVoice, and nextSteps: what is still missing in the site’s setup.

list_providers Read

No parameters. Returns the six assistants with key, label, the model in use, modelOptions, whether the assistant is enabled and whether it supports batch pricing.

create_project Read + scan

Starts tracking a site. Refused when the workspace’s number of sites is used up, or when the address is not a domain.

• name (text, required): the brand name as it appears in answers.
• url (text, required): the site, for example brightloop.example.
• industry (text).
• brandTerms (list of text, up to 50): other spellings that still mean the brand.
• competitors (list, up to 50): objects with name and optional domain.
• language (text): the language answers are asked for. Default English.
• location (text): where the customer is. Default United States.

Returns the new site.

update_project Read + edit

Changes a site. Parameters: projectId (required) and any of name, industry, brandTerms, language, location, scanFrequencyDays (1 to 365, the gap between scheduled scans).

Returns project and reanalysis. When the name or the brand terms change, every stored answer is re-read at once and reanalysis says how many answers were read and how many name the brand before and after. No assistant is called for this.

Reports

get_dashboard Read

The weekly report of a site, the data behind the Dashboard.

• projectId (required).
• week (YYYY-MM-DD): any date inside the week you want. Left out, the latest week.

The main parts of the result:

• now and previous: counts and shares for the week and the week before (answers, mentioned, mentionRate, ownCited, citationRate, promptCoverage, avgRank, visibility, tone counts).
• verdict: a headline and a one-paragraph summary of the week.
• leaderboard: you and every tracked competitor with answers named in, share of voice and the change.
• shareOfVoice, sources (the five most cited domains, citations of your pages), assistants (one row per assistant).
• changes: gained and lost (prompts where an assistant started or stopped naming you, at most 50 each), and linkGained and linkLost for links.
• categories (numbers per category), activity (the scans of the week, answers collected, spend) and actions (up to three suggested next steps).

Before the first scan it returns a short text saying there is nothing to report.

get_trends Read

Week by week for a site: the last ten weeks.

• projectId (required).
• limit (1 to 200, default 25): the most prompts to return in each list.

Returns weeks; weekByWeek (per week: answers, mentionRate, citationRate, promptCoverage and visibility, each with its change); wonLost (prompts won and lost per week); topics (per category, the share of its prompts that name you, per week); topPrompts (the prompts with the highest visibility score: latest is the score, change1w and change4w its change over one and four weeks); and stability with three lists and their counts:

Prompts

list_prompts Read

The tracked prompts of a site with each assistant’s current verdict.

• projectId (required).
• q: text search in the prompt.
• category: one category name.
• status: draft, active or paused.
• verdict: named, lost (a tracked competitor is named, and you are neither named nor linked), cited (linked but not named), missing (neither) or failed. The exact rules are the ones of the Result filter.
• competitor: the name of a tracked competitor that a current answer names.
• stability: held, volatile or lost, as defined under get_trends.
• scanned: yes or never.
• sort: created (default), text, category, rank or scanned. dir: asc or desc.
• page (from 1) and perPage (5 to 200, default 20).

Returns total, page, lastPage, engines (the assistants that have answered), facets (the categories, sources and competitors to filter by) and prompts. Each prompt has id, text, category, status, intent, source, bestRank, lastScanAt, stability and verdicts: per assistant, one of named first, named, linked, not named, not named, failed.

get_prompt Read

One prompt in full, with one assistant’s answer word for word.

• projectId, promptId (required).
• engine: the assistant whose answer to include. Left out, the first one that answered.

Returns prompt; verdicts per assistant (mentioned, brandRank, ownCited, sentiment, error, scannedAt); heatmap (per assistant and week, a level from 0 to 3: not visible, linked only, named, named first); and answer: provider, model, scannedAt, the verdicts, howDescribed (the sentence that describes you), the full text, competitorsNamed, searches (the web searches the assistant ran, when it discloses them) and sources. Sources come in four groups: own (your site), opportunity (other people’s pages), competitor (competitors’ sites) and reference (documentation and official sites), each page with its url, kind and citedTimes.

add_prompts Read + edit

Adds prompts to a site.

• projectId (required).
• prompts (list of 1 to 200, required). Each item: text (3 to 500 characters, required), category, intent (informational, commercial, transactional, navigational; default informational), funnel (awareness, consideration, decision; default awareness), status (default active).

Returns added (a count) and failed: the texts that were not added, each with the reason. A text already tracked on the site, and anything beyond the site’s prompt limit, ends up there.

update_prompt Read + edit

Edits one prompt. Parameters: projectId, promptId (required) and any of text, category, intent, funnel, status. Collected answers stay with the prompt; a new text changes what later scans ask. category replaces all the prompt’s categories with that one. Returns the prompt.

bulk_update_prompts Read + edit

Changes many prompts at once. Parameters: projectId, ids (1 to 5000 prompt ids, required) and one or more of status, category (files them under this one category only), addCategory (adds a category to the ones each prompt already has), delete (true deletes the prompts together with their answers and cannot be undone). Returns ok.

import_queries Read + edit

Imports a list of prompts or search queries as text, in the format described under Importing prompts.

• projectId (required).
• contents (text, required): the lines of the file.
• status: draft (default) or active.
• dryRun (true or false): only count what would happen.

Returns rows, created, updated (already tracked; their categories are replaced when the row names any), skipped and categories (rows per category).

rewrite_queries Read + scan

Rewrites imported search queries (“email automation pricing”) as full questions, using an AI model. It is not charged, but needs a balance above zero, and can be called up to 10 times an hour. Only imported prompts whose text is still the original query are touched; the original stays stored as the prompt’s keyword. Parameters: projectId (required), category (limit to one category), dryRun (show the rewrites without saving). Returns pending, written, skipped and pairs: each original with its rewrite.

Competitors and pages

list_competitors Read

Parameter: projectId. Returns competitors (id, name, domain, aliases); answersCollected; ownNamedIn and namedIn (in how many current answers you and each competitor are named); board (for you and every tracked brand, the share of answers naming it, overall and per assistant); and suggestions: untracked names that appear in at least three answers of the last 28 days.

add_competitor Read + edit

Parameters: projectId, name (required), domain, aliases (up to 30 other spellings). Stored answers are re-read for the new brand at once, without calling any assistant. Returns competitor and reanalysis.

update_competitor Read + edit

Parameters: projectId, competitorId (both required), name, domain, aliases. Returns competitor and reanalysis.

Only what you send changes. A value left out keeps what is stored; aliases replaces the whole list; domain: null removes the domain.

remove_competitor Read + edit

Parameters: projectId, competitorId. The brand stops being tracked and stored answers are re-read without it. The answers themselves are kept.

get_competitor_report Read

Parameters: projectId, competitorId. One competitor against you: paired numbers with their changes (tiles), per assistant (assistants), per category (topics), the prompts where only they are named, both, or only you (prompts), and the pages of their site the assistants cite (pages). Before the first scan it returns empty: true.

list_pages Read

The pages of your site, read from its sitemap, and whether a current answer links to each. The sitemap is read when the site is added and again every week; import_sitemap reads it now.

• projectId (required).
• shown: yes for pages some current answer links to, no for the rest.
• q: search in the address and the title.
• page, perPage (5 to 200, default 50).

Returns items (id, url, title, path, section, shownBy: the assistants linking to it, prompts: how many prompts lead to it), total, siteTotal, shown and sections.

get_crawler_access Read

What your robots.txt lets each AI crawler read. Parameters: projectId (required), check (true reads robots.txt and llms.txt again first; needs a Read + edit key).

Returns checkedAt, robots (status: found, missing or unreachable; url, httpStatus, error), llmsTxt (present, url), crawlers (each with token, operator, purpose, access: allowed, partial, blocked or unknown, the deciding line and was when it changed) and history. See AI crawler access.

list_search_queries Read

The web searches the assistants ran while answering the site’s active prompts, as of the latest answer per prompt and assistant, most common first (up to 500). Parameter: projectId.

Each item: query, answers (answers that ran it), named (of those, the ones that named you), providers, prompts (id, text) and tracked (a prompt with this exact text exists).

import_sitemap Read + edit

Parameter: projectId. Reads the site’s sitemap now (/sitemap.xml and the sitemaps robots.txt names, following a sitemap index) and adds every page of your own domain that is not listed yet, up to 5,000 addresses. Returns seen and added. Fails with a message when no pages are found there.

Scans

get_scan_options Read

Parameter: projectId. What a scan can be set up with: engines (the connected assistants, and whether each supports batch), models (per assistant: the default model and the other options, each with a label, an estimated costPerAnswer, a note and, when it cannot be chosen, the reason in unavailable; for ChatGPT and Gemini the options include the app answers chatgpt-app / gemini-app (fast, at once) and chatgpt-app-queue / gemini-app-queue (slow and cheaper, a few minutes): the answer as the app shows it), activePrompts, categories (active prompts per category), scansThisMonth and scansPerMonth (the workspace’s limit), and spentThisMonth (the site’s scan cost this calendar month).

estimate_scan Read

What a scan would cost, before it runs. Takes the same choices as start_scan:

• projectId (required).
• providers (list of assistant keys): which assistants to ask. Left out, every connected one.
• promptIds (list of ids): a hand-picked set. Left out, every active prompt. Prompts that are not active are skipped.
• category: scan one category only.
• sample (number): scan only that many prompts, drawn at random.
• models (object): assistant key to model, for example {"openai": "gpt-5.4-mini"}. The model must be one of that assistant’s options in get_scan_options.
• batch (true or false): batch pricing. ChatGPT, Claude and Gemini answer for a lower price within hours, up to a day; the other assistants, and the app answers, answer at once at the normal price.

Returns prompts, answers, cost (US dollars) and formatted. What the figure includes: Scan cost estimate.

start_scan Read + scan

Runs a scan. Parameters: everything from estimate_scan, plus budgetUsd (stop the scan once it has cost this much; 0 or left out means twice its estimate) and label (up to 60 characters). Returns the scan: id, status, mode (live or batch), providers, total, completed, failed, costUsd, budgetUsd, startedAt.

The call returns as soon as the scan is queued; follow it with get_live_scan. A scan is refused, with the reason as the error, when another scan of the site is running, no active prompt matches, a model name is unknown, the balance does not cover the scan, the site has reached its monthly cap, or the workspace’s scans for the month are used up.

get_live_scan Read

Parameter: projectId. Returns run: null when nothing is running, otherwise the scan with progress (elapsed, lastAnswer, seconds perAnswer, eta) and stalled (true when answers are queued and none has arrived after 20 seconds).

cancel_scan Read + scan

Parameters: projectId, runId. Stops a running scan. Answers still queued are dropped; one already on its way may still arrive. Returns cancelled: false when the scan had already ended.

list_scans Read

Parameter: projectId. The last 30 scans of the site, newest first, each with status, assistants, models, answer counts and costUsd. Statuses: queued, running, cancelling, cancelled, done, failed.

Charts

render_chart Read

Draws a chart and returns it as an image, followed by the plotted values as text.

Ask for one of the site’s own charts with projectId and chart:

Or draw your own data with 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 or bar. labels and series are required; suffix, horizontal and stacked are optional.
• week (YYYY-MM-DD): for the report.* charts, a past week.
• title (up to 120 characters), width (300 to 2000, default 900), height (200 to 1500), dark (true for a dark background).

Resource and prompt templates

Clients that support MCP resources and prompts also see:

The templates only hand a ready-made instruction to your AI. The proposals and the review are written by your AI, not by Teddit.

Every tool except render_chart has REST endpoints that return the same data; see Endpoints.