Tools Reference

This page documents 54 tools of the ThriveStack MCP Server, and its one prompt. They cover your brands and brand kit, AI-search visibility and citations, the AI answers and sources behind each tracked prompt, probe runs, the sources AI answers draw on, your site’s crawl and indexing health, page traffic and Google search performance, traffic attribution, AI crawler visits, AI revenue, the content audit, prompt research, and content recommendations.

53 of the 54 tools are read-only. The only tool that changes anything is save_content_recommendations, which saves recommendations to your brand as suggested items for your team. It cannot approve, dismiss, assign or delete anything, and your AI client asks you to confirm before it runs.

None of these tools take a project_id or similar tenant parameter. Your product and environment are resolved automatically from how you authenticated (OAuth session or Personal Access Token) — see Setup.

Your AI assistant calls these automatically based on your questions. The server also provides one prompt, ai_visibility_analyst, a ready-made content-strategy analysis — see Prompts. It does not expose any MCP resources.

Response format

There is no single universal response envelope — each tool returns the JSON shape natural to its own data. The visibility and recommendation tools return structured report objects, and check_connection returns a small fixed object.

Tools whose description says they return a “clear empty” or “no-data” result are designed to return an empty-but-valid result rather than an error when there’s nothing yet (for example, a domain that hasn’t been probed). Treat that as “nothing here yet”, not a failure. Large results are paged or capped; the tools that page accept page and page_size (or limit and offset).

Brands & Account

get_accessible_brands

Lists the brands (products) the signed-in ThriveStack account can access, with name and domain for each. These are the brands the account can switch between, and the domains the other tools accept. The result is the same whether you connect with OAuth or a personal access token.

No input parameters required.

get_brand_information

Returns the saved brand profile for a domain, as captured during AI Visibility setup and any later edits: description, value offering, industry, HQ country, business model, products and services, brand identity, customer segments, target markets, tracked competitors, tracked topics, language, monitored AI engines, buyer-intent mix, and setup progress (last_completed_step, user_edited).

get_ai_visibility_setup_status

Whether AI Visibility setup is finished for a brand (configured) and whether its trial has expired (trial_expired). Use it to tell a brand that has not been onboarded yet, or whose trial has ended, apart from one that simply has no data.

get_brand_kit

The brand kit saved for a domain, which guides how generated content should sound: voice (tone sliders such as formal to casual, author persona, sounds-like and not-like examples), rules (dos and don’ts) and naming (official brand name and aliases), plus version and updated_at.

Good to know

• If no kit has been saved yet, the tool returns saved=false with an empty kit. That is not an error; it means the brand kit has not been set up for the domain.
• The brand kit holds voice, rules and naming only. It does not include logos, colours or fonts.

Visibility & Citations

get_domain_report

Returns the visibility report for a brand's most recent completed AI-visibility probe run: overall visibility and average position, competitor and mentioned brands, broken down by topic and by tracked question, with per-AI-model detail. Use it to answer how visible a brand is and who appears alongside it.

get_prompt_metrics

A filterable visibility report over a date window: visibility, average rank and share of voice per tracked question, per topic and overall, with totals. Slice by AI engine, country and brand, and choose active or archived questions. Use it for questions like “our visibility on Perplexity in the US over the last 30 days”.

Good to know

• sov (share of voice) for a question is its share of the mentions across all tracked questions, not just its own answers. For the share within one prompt’s answers, use get_prompt_top_brands.
• get_domain_report covers only the latest run, unfiltered. To compare one AI engine or country with the overall figure, make two calls: one with engines or countries set and one without.

get_domain_prompts

Lists the tracked buyer questions (prompts) generated for a brand's domain, grouped by topic. Use it to see or review what is being tracked; it contains no visibility results (get_domain_report has those). The domain must have completed brand setup; otherwise the tool returns an explanatory error message.

list_domain_topics

Lists a brand’s prompt topics: selected topics, which have tracked (active) prompts, with how many prompts each holds, and suggested topics that are not selected yet, with their kind and how many suggested prompts they hold. Use it to answer which topics are tracked and which are only suggested. The prompts inside each topic are listed by get_domain_prompts.

Good to know

• A topic that has both tracked and suggested prompts is listed once, as selected.
• If the brand has no topics yet, the tool returns has_data=false with a message. That is not an error.

get_citation_probe_data

Returns the raw citation evidence from a brand's most recent completed AI-visibility probe run: every tracked buyer question, one record per question and AI engine.

get_competitor_visibility

Weekly AI-search visibility % (and average rank, where available) for a domain's own brand alongside its tracked competitor brands, side by side — matching the product's AI Visibility > Competitors page. If competitor_domains isn't provided, the domain's saved tracked-competitor list is used automatically.

Good to know

• The latest snapshot ranks every brand by its most recent week’s visibility and gives each brand’s mentions and share_of_voice: its mentions in AI answers as a fraction of all mentions across the returned brands. That is the same measure as get_prompt_metrics and the Competitors page.
• share_of_voice_basis is mentions, or visibility for older weeks recorded before mention counts existed.
• If the domain has no tracked competitors and none are passed, or there is no history yet for the window, the tool returns a clear no-data result rather than an error.

get_competitor_metrics

Latest-snapshot visibility, share of voice and average rank for the competitor brands you name, measured in the brand’s own tracked AI answers.

Good to know

• Competitors with no mentions in the latest snapshot come back as zeros.
• The week-by-week trend is in get_competitor_visibility. The brand’s saved competitor list is in get_brand_information.

get_engine_visibility_trend

Daily AI-search visibility % for a domain's own brand, split by AI engine (ChatGPT, Perplexity, Gemini, ...), with average rank per engine where available. Each point is one day: 'values' maps engine id to visibility %, 'avg_ranks' maps engine id to average position (lower is better). Days appear only when a probe ran, so gaps between dates are normal.

Prompt Drilldown

These tools show the detail behind one tracked prompt: the prompt itself, the AI answers recorded for it, the sources and brands those answers used, and how its visibility moved. Take the prompt_id from get_domain_prompts.

get_domain_prompt

Returns the detail of one tracked prompt (buyer question) for a brand’s domain. It contains no visibility results; get_domain_report has those.

get_prompt_chats

The AI answers recorded for one tracked prompt, newest first: one chat per AI engine, country and run. Each chat has engine, model, country_code, probed_at, visibility, avg_rank, our_citations and total_citations, the full answer_text, the brands named (name, domain, rank, is_customer) and the citations used (title, domain, uri).

Answers are long, so chats come in small pages (default 5, max 10): total, page and next_page say where you are. get_prompt_chat returns one chat by id.

get_prompt_chat

One recorded AI answer: the engine, model and country, the full answer_text, the brands named (name, domain, rank, is_customer) and the citations used (title, domain, uri), with visibility, avg_rank and citation counts.

get_prompt_sources

The sources AI answers used for one tracked prompt, ranked by retrievals: cited domains (default) or individual URLs. Each row has retrievals, and for URLs the uri and title, chats_used and citations. Returns the top rows only (default 25, max 100); total_retrievals is the full count.

get_prompt_top_brands

The brands AI answers name for one tracked prompt, ranked: each with rank, name, domain, visibility, share of voice (sov) and average position, plus total_responses behind them.

Good to know

• sov here is the brand’s share of the mentions in this prompt’s answers only, so it can be much higher than the sov of the same prompt in get_prompt_metrics, which is a share of the mentions across all tracked prompts.

get_prompt_visibility_trend

One tracked prompt’s visibility over time: the percent of its AI answers that name the brand, as a series of points (date, visibility) by day (default), week or month.

Probe Runs

A probe run is the scheduled pass that asks every tracked question across the AI engines. These tools show a run’s status, one engine’s full answer, and when the next run is due.

get_probe_run

Status of one AI-visibility probe run: status, progress, start and finish times, and per-topic results where the run has them. Omit run_id for the brand’s latest run.

Use it to check whether a run is still in progress before reading reports such as get_domain_report.

get_probe_result

One AI engine’s full answer to one tracked question: the answer text, the brands it named with their rank, its citations, and the engine and country.

Use it to read exactly what an engine said, for example to explain why the brand was not mentioned. Get the result_id from get_citation_probe_data.

get_probe_schedule

The brand’s probe and site-audit schedules: cadence, last and next run, and answers remaining.

Use it to explain why data looks stale, or when it will next refresh. It returns a not-found error if the brand has no schedule.

Sources & Pages

get_url_report

Per-URL retrieval and citation metrics for every source URL AI answers drew on for a domain’s tracked questions: which specific pages are retrieved and cited, and how often, with each URL’s type, domain type and source class (owned, earned or other cited). It lists source URLs from any site that AI answers cited, not only the brand’s own pages.

Good to know

• Without a date window it covers the most recent completed probe run. Source metrics are computed after a run finishes; until then the tool returns has_run=true, urls_computed=false rather than an empty list. With start_date/end_date it covers every run in the window.
• retrievals is how many answers cited the URL, and retrieved_pct is the percent of all answers that cited it.
• citation_rate is the average number of times the URL was cited per answer that cited it. It is 1.0 or more and is not a percentage.
• Default sort is retrievals, highest first.

get_cited_domains

Per-domain retrieval and citation metrics for every website AI answers drew on for a brand’s tracked questions, with each domain’s type and source class (owned, earned or other cited). It is the domain-level twin of get_url_report and behaves the same way.

Good to know

• Without a date window it covers the latest completed run, and says so if that run’s source metrics are not computed yet (urls_computed=false). With start_date and end_date it covers every run in the window.
• retrievals counts every citation of the domain. retrieved_pct is the percent of all answers that cited it at least once. retrieval_rate is its citations per answer across all answers.
• citation_rate is its average number of citations per answer that cited it. It is 1.0 or more and is not a percentage.

get_source_mix_summary

Where AI answers about a domain's prompts get their information, summarised over a date window — matching the panels above the product's AI Visibility > Domains and URLs tables.

get_source_trend

How often the most-used sources were retrieved by AI answers over time, for a domain's prompts — the product's 'Source retrievals over time' chart on AI Visibility > Domains and URLs. Returns 'labels' (one per day, week or month) and 'series' (one per source, 'values' aligned to labels).

get_competitor_source_mix

For the domain's brand and each competitor, the share of AI-answer source retrievals that come from the brand's own site (owned), from third-party pages mentioning it (earned) and from everything else (other), measured across the domain's tracked prompts. Values are whole-number percentages that sum to 100 per brand (all three 0 means no retrievals).

get_source_run_days

The days on which a brand’s prompts were run and their cited sources recorded: first_run_day, last_run_day, total_runs and every day in run_days. Use it to choose a start_date and end_date that contain data before calling get_source_mix_summary, get_source_trend or get_competitor_source_mix, or to explain why one of them came back empty.

Good to know

• If no run has recorded sources yet, the tool returns has_data=false with a message. That is not an error.

Site & Crawl Health

list_urls

Paged table of the brand's URLs (brand from your token), one row per URL that the brand's Search Console sync knows about: sitemap URLs plus any pages added by hand. Each row combines four sources: Google indexing (indexState, coverageDetail, crawlAllowed, lastCrawlTime), AI-crawler reach (crawlHits and crawlBots), the content audit (contentStatus, seoScore, entityScore, only for audited pages) and AI citations (cited, citedPromptCount, and citedBy, up to 10 of the citing prompts, newest first, each with probed_at). Filters are ANDed; a comma list inside one filter means any of.

Good to know

• crawlHits and crawlBots count requests made by AI crawlers such as GPTBot and ClaudeBot. They are not human visits. Human visits come from get_page_traffic.
• The list is empty until Search Console is connected and has synced. get_search_console_status shows the connection.
• The response includes columns, which says which sources are set up (indexed, crawled, content). When one is false, its fields are absent because the source is not set up. That is different from a value of zero.
• total counts every matching row. Page through them with page and page_size.
• Pages that AI answers cite on any site, not only the brand's own, are covered by get_url_report.

This tool takes no domain parameter. It always reads the brand your token belongs to.

get_url_details

Details for one URL of the brand on your token. Today this is the Google Search Console view: index state, coverage detail, whether crawling is allowed, last Google crawl, plus the raw URL Inspection result under 'raw' (verdict, robots/canonical/mobile details as Google returned them).

get_url_funnel

URL funnel for the brand on your token, as on the AI Visibility > URLs page: sitemap URLs → crawled by Google → indexed by Google, plus an aiReach band (sitemap URLs an AI crawler actually fetched vs. not).

No input parameters required.

get_search_console_status

Google Search Console connection and sync state for the brand on your token: whether it's connected, the selected property, the brand's configured domain and whether the property matches it, the connected Google account, last poll time, the sync schedule (last/next run, cadence, tier) and any in-flight sync run (queued | running | paused, with resumesAt when paused).

No input parameters required.

get_technical_recommendations

Technical AI-crawlability and on-page/entity-signal recommendations for a domain's most recent completed audit — matching the product's AI Visibility > Technical group (Crawl Insights, Content & SEO, Entity Signals tabs). Distinct from get_owned_content_recommendations/get_earned_content_recommendations, which are citation-gap content ideas, not technical checks.

Traffic & Search Performance

These tools show how much real traffic each page gets and how it performs in Google, next to the AI-crawler and citation data above. Together with list_urls they give a page-by-page view of a site, which is what a content calendar needs.

Matching pages across tools. get_page_traffic and get_search_performance identify a page by its normalised path: host, query string and trailing slash removed, lower-case. A page therefore has the same key in both, and you can join them on it.

No data is not zero. Each tool says in meta whether its source is connected. If it is not, the tool has no data to report, which is different from a page with zero visits or zero clicks.

get_page_traffic

Human visits per page from the connected Google Analytics, across every channel, not only AI-referred ones. For each landing page it returns:

• sessions in the window, split into organic search, direct, AI referral and other (paid and email visits are included in these);
• key events (conversions);
• the last day with sessions in the window;
• first_seen, the oldest day Google Analytics shows sessions for the page. This is a lower bound on when the page went live, because history starts when the connection first synced.

A session counts on the page it started on, so this is not a page-view count. Defaults to the last 28 days. Results are sorted and paged on the server, with totals over the whole filtered set.

Good to know

• Totals can sit a few percent below get_traffic_attribution_overview. That report reads Google Analytics by channel and day, while this one reads it by landing page, so the two do not match exactly.
• meta says whether Google Analytics is connected (configured=false means there is no data to report, not zero visits), whether it is still syncing, and how many sessions had no landing page or were grouped into Google's “(other)” row. When that happens, the page list is incomplete.
• Crawler hits from Cloudflare, Vercel or WordPress are AI-bot requests and are not part of these visits.

get_search_performance

Google Search Console clicks and impressions per page for the brand on your token. For each page it returns clicks, impressions, CTR (a decimal, so 0.0123 means 1.23%) and average position (1 is the top of the results, weighted by impressions), summed over the window, plus totals over the whole filtered set. example_url shows one full URL for the page.

Defaults to the last 28 days ending two days ago, because Search Console runs about two days behind. Results are sorted and paged on the server.

Good to know

• The data comes from a daily sync. meta says whether Search Console is connected (configured=false means there is no data, not zero clicks), whether the first sync is still running (syncing), the oldest and newest day held (data_from, data_through), and warns when your window reaches outside them.
• Only pages that Google showed in its results have a row. A page with no row was not shown in the window.
• get_search_console_status shows the connection and sync state.

This tool takes no domain parameter. It always reads the brand your token belongs to.

get_attribution_health

A plain-language health check of the data behind the attribution dashboards, in one call. Read-only.

• Sources. For Google Analytics, Cloudflare, Vercel, WordPress and revenue, it reports whether the source is connected, still syncing, working or needs attention, with when it last synced and a short reason.
• AI crawler tracking. It reports whether the add-on is on, how much of it is used, and whether a crawler visit has been confirmed.
• Overall. overall is one of working, setting_up, needs_attention, not_connected or unknown (when the sources could not be read). attention lists what needs a look, as plain sentences.
• Coverage. coverage says what each source can tell you. Google Analytics is the only source of human visits. Cloudflare, Vercel and WordPress report AI bot requests only, so a connected crawler source never means visit data. Coverage is explanation only; it does not change attention or overall.

If one part cannot be read, its entry carries an error message and the others still report.

get_traffic_attribution_overview

Traffic Attribution over time: visits from direct, organic, AI referral links (ai_utm) and AI citations (ai_citation), AI crawler hits, revenue and all other channels, per day, week or month, with totals for the window and for the equal-length window before it.

Good to know

• Defaults to the last 180 days. Give start_date and end_date together, for at most 400 days. The bucket width follows the window length unless you set granularity.
• A null value means it could not be measured, which is different from zero. Each series reports its status, source and first data date.
• meta carries configured, no_data, data_stale, history, the revenue currency and the connected Google Analytics properties. property_id narrows the Google Analytics series to one property; without it they are summed.
• Rows are whole buckets counted back from end_date, so a partial first bucket is counted in the totals but not in the rows. rows_note says when this happens and which days.
• The direct, organic and AI referral visit series come from Google Analytics. Crawler hits are requests made by AI bots, not visits.

get_traffic_attribution_sources

Connection state of every data source behind Traffic Attribution: Google Analytics, Cloudflare, Vercel, WordPress and revenue.

Good to know

• Each source returns a state (not_connected, syncing, connected or needs_attention), what it is connected to, the last sync time, how many days of history it holds, and a short reason while it is syncing or needs attention.
• A source can also carry an issue: error (the latest delivery failed), quiet (still connected, but nothing has arrived for two days or more, which a site with no visitors also causes), stale (the newest data is older than expected) or disconnected (the connection was removed on the provider’s side, so nothing is arriving).
• needs_attention covers stale data, a delivery error, a disconnected source, a missing base currency, or a source that could not be read. A source that is not connected is not an error; it simply has no data in the traffic overview.
• Cloudflare, Vercel and WordPress feed the AI crawler hits only. Human visits come from Google Analytics. For a one-call summary see get_attribution_health.

AI Crawlers

These tools report requests made by AI bots and agents, such as GPTBot and ClaudeBot. They are not human visits; human visits come from Google Analytics (see get_page_traffic and get_traffic_attribution_overview).

They need the AI crawler add-on and crawler tracking. While the add-on is off, the data tools answer addon_required.

get_agent_visit_addon

Whether the AI crawler add-on is switched on for the brand and how much of it has been used.

Good to know

• Returns enabled (the AI crawler dashboard is unlocked), the billing frequency, trial and period dates, usage for the current period (events used, allowed and included, overage blocks, estimated overage cost in cents, and whether the period is a free trial) and the plan terms (platform fee, events included and block price, in cents).
• Read-only: it does not switch the add-on on or off, and it does not return a payment link.

get_agent_visit_recommendations

Crawl-health fixes found from the brand’s AI crawler visits, such as pages that AI bots reach with errors.

Good to know

• Each recommendation has a title, rationale, ordered steps, a priority, an effort estimate and a suggested owner role, how many bot hits and URLs it affects over the analysed window, and its status (suggested, todo, done or dismissed).
• Filter by status, or omit it for all. Needs the AI crawler add-on and crawler tracking; the response is addon_required while the add-on is off.

get_ai_crawl_summary

AI crawler and agent visits to the brand’s site: total hits, active bots, failure rate, the top bot, top folders and pages, visits per day, and splits by platform (the AI company, such as OpenAI), bot type and response status code.

Good to know

• Defaults to the last 30 days. Filter by platform, bot type or bot.
• The daily series covers only the five busiest bots. top_bots lists every bot, so the daily series can add up to less than total_hits.
• platforms takes the AI company (OpenAI, Anthropic, Perplexity, Google), not the connector (Cloudflare, Vercel) that reports the visits.

get_ai_crawl_urls

The pages AI crawlers fetch: per URL, the hits, folder, status group (for example 2xx or 4xx) and the platform split, most-hit first. It uses the same window and filters as the crawler summary.

Good to know

• Returns the first limit rows (default 100, at most 500) and says how many exist in total, so a long list does not arrive all at once.
• The Vercel middleware connector cannot see the real response status and records every request as 200, so status groups are not meaningful for it.

AI Revenue

Sessions, conversions and revenue that come from AI sources, from the brand’s connected Google Analytics. A null value means it could not be measured, which is different from zero. property_id narrows a result to one Google Analytics property; otherwise they are summed.

get_ai_revenue_summary

The headline numbers of AI revenue attribution over a window: sessions from AI sources, conversions and revenue, and revenue per session for AI traffic against organic search, each with its change against the previous period of the same length.

Good to know

• Defaults to the last 30 days.
• meta says whether revenue is derived from conversions and a deal value, whether the sample is too small to trust, whether the window has no data, the newest data day and whether the sync is behind, and whether revenue attribution is set up at all.

get_ai_revenue_trend

AI revenue attribution over time: sessions, conversions or revenue per bucket for AI sources, organic search and direct, plus a breakdown of the AI sources.

Good to know

• metric picks what is plotted, and granularity is week (starting Monday) or day. Defaults to the last 30 days by week.
• The three series are always present and zero-filled. A null total means it could not be measured.

get_ai_revenue_pages

The landing pages that receive AI-referred traffic: per page, AI sessions, conversions, conversion rate, revenue, revenue per session and how often AI answers cite the page, with the AI vendors behind it.

Good to know

• Paged and sorted on the server. Filter by page type or AI vendor. Totals cover the whole filtered set, not only the page returned.
• Each row says whether its revenue is native, modeled or absent, and citations can be null when the citation data is unavailable.
• Only pages that received AI-referred sessions are listed, and the session counts are AI sessions, not total visits to the page. Sessions with no landing page are left out (meta.pages_excluded_unattributed), so totals can be lower than get_ai_revenue_summary.
• Days follow meta.time_zone, which can differ from the UTC days of the traffic tools.

Content Audit

These tools show which pages are tracked for the content audit, how many page audits your plan allows and how many are used, and which sitemap pages you could add.

get_content_audit_summary

Content audit status for a brand’s domain: how many pages are audited, queued and active, the plan’s page-audit limit (page_audits_purchased), how many are used (page_audits_consumed) and pages_remaining (limit minus used). Each page row has its SEO and AEO scores, pending actions by priority, last audit time and whether AI answers cite it. It also returns sitemap_status and coverage_warnings when present.

Good to know

• pages_remaining is absent when the plan figures are unavailable.
• Page rows come in pages: total, returned and next_page say where you are.
• Set include_sitemap to also list sitemap and AI-cited pages that are not in the report (in_report=false). Those pages are not counted in any total.

list_content_audit_pages

The pages tracked for a brand’s content audit: url, label and source (auto = picked by the system, user = added by the team). Pages come in batches: total, returned and next_page say where you are. Scores and action counts are in get_content_audit_summary.

list_content_audit_sitemap_urls

Sitemap URLs found for a brand’s domain that can be added to the content audit: has_sitemap, the sitemap url, url_count and the urls themselves. urls_capped is true when the stored list was cut short. URLs come in pages: total, returned and next_page say where you are.

Prompt Research

list_prompt_research

Lists a brand's prompt research sessions: each is a run that discovers the questions buyers ask AI about the brand's category, from which the user picks prompts to track.

get_prompt_research

Returns one prompt research session's researched prompts and personas. Each prompt has prompt_text, topic, persona, branding (branded or non-branded), intent (informational, commercial or transactional), country, language, recommended and tracked. Prompts are grouped either by topic or by persona. Get the id from list_prompt_research.

Recommendations

get_owned_content_recommendations

Lists content recommendations for the brand's own site (channel_type onsite): content to publish on your blog or site to close the AI-citation gaps found in probing. Each item includes severity_tier, gap_score, our_citations and total_citations, and competitors_winning as evidence.

get_earned_content_recommendations

Lists content recommendations for earned, third-party media (channel_type earned): ideas for getting cited on sites such as Reddit, G2 or other reference and editorial domains.

Drafting & Saving

generate_content_outline

Generates a content outline (structure only, not finished copy) for one owned-media content recommendation: headings, an answer-first opening summary, FAQ questions, and suggested schema markup types. The outline is generated on request and nothing is saved; calling it again produces a new one.

save_content_recommendations

Saves content recommendations (owned and/or earned) to the brand's recommendations list as 'suggested' items for the team to act on. This is the only tool that writes data, and it is deliberately narrow: it creates new 'suggested' items or refreshes ones still 'suggested'.

Diagnostics

check_connection

Confirms the ThriveStack connection is working and your sign-in was accepted. Returns the server time.

No input parameters required.

Changes over time

New tools are added from time to time, and we update this page when they go live. See the Changelog for every tool added or changed since v1, with dates.