Account data tools

These tools cover the property-scoped surface of the MCP server: your own private data, one brand at a time. Every one on this page is read-only except add_pitch_list_publishers, which adds publishers to a pitch list, and all of them are gated by your membership: the server checks that your signed-in account can access the property (or organization) before returning anything.

Almost everything here starts from a propertyId, so the first call in any account session is list_properties. (The account surfaces that aren't property-scoped are bulk placement scoring, which starts from an organizationId and writes, and organization-level pitch lists.)

Many of these tools return numeric series over time. Nothing is charted server-side — the assistant builds any visualization from the returned data. Just ask for "a chart of share of voice over the last 90 days" and it will.

Discover your properties

list_properties

Lists the properties (brands / sites) on your account, each with its organization and your role. Use a returned id as the propertyId for every other tool on this page.

Projects

Projects are bundled, time-bound tracking efforts (an SEO push, a PR campaign). See the Projects dashboard for the concept.

list_projects

Lists a property's projects with each one's type, status, date range, goals, and counts. A returned id is also the projectId argument on get_metrics_history, get_competitor_share_of_voice, get_answer_drilldown and get_answer_summaries, which scopes any of them to that project's prompts.

get_project_insights

A project's deep insights, matching its exported report: metric deltas from start to now (consistency, share of voice, mentions, owned citations, owned citation rate, and cumulative goal citations), a weekly trend series (including weekly goal hits), goals with their first-hit details plus hit counts and influence rates (the share of the project's citations each tracked publisher/article/author/coverage group accounts for), the annotation timeline, key insights, and next steps.

The four shared filters

Four tools take the same slice arguments, and they mean the same thing in each: stage (awareness / consideration / decision), platform, tag (a prompt tag), projectId, plus locationPropertyId for one tracked market. The tools are get_metrics_history (trend), get_competitor_share_of_voice (ranking), get_answer_drilldown (one day's prompts and answers) and get_answer_summaries (one prompt's wording week by week). So "share of answers on Perplexity, decision stage, for the pricing tag" is one question you can follow from the trend line down to the raw answer.

Resolve the values first: tags from list_prompt_tags, project ids from list_projects, location ids from list_locations. An id that belongs to another property is rejected, not silently ignored, because a filter that matches nothing returns an empty slice that reads like "nothing happened".

Historical trends

get_metrics_history

A property's AI visibility metrics over time, one point per report or prompt-tracking run: share of voice, mentions, citations, citation rate, and per-platform breakdowns.

Pass stage and/or platform to add a slice to every point: the stored stage-scoped cell for that combination, or the consideration + decision headline when only a platform is given. A slice of null is a day whose stored row carries no cell for that combination: unknown for the slice, never zero, and never the brand-wide total standing in for it.

Pass a tag to get a theme-scoped series instead: one point per UTC day, each with per-stage mentions, opportunities and share of voice for that tag, plus the day's headline (which narrows to your stage when you pass one). stage and platform combine with it.

Pass a projectId to scope the whole discovery series to that project's prompts (recomputed live from the source answers, the same way the dashboard's project filter does it) and to get the grounding-search ranking trend for the project's tracked queries alongside. That recompute is brand-wide, so projectId and locationPropertyId cannot be combined; ask for one or the other. Project-level deltas and weekly trends come from get_project_insights.

list_prompt_tags

The tag vocabulary for a property: the free-form tags on its tracked prompts, plus their categories and use-cases. Call this before slicing anything by theme: a tag that does not appear here returns an empty slice. The same tags are the tag argument on get_metrics_history, get_competitor_share_of_voice, get_answer_drilldown and get_answer_summaries.

get_answer_drilldown

The L3 drill-down behind the visibility dashboard. For one UTC day it returns the raw prompt text of every tracked prompt that ran in scope, and for each prompt every platform execution: which model answered, the tracked brands that answer named (brandsNamed), the focal brand's mention flag and rank, and its citation counts. Totals reconcile exactly with the same day's point from get_metrics_history for the same scope. This is how you answer "why did share of voice move on this date?".

brandName puts one brand under a lens, not a filter: no prompt is removed, every execution gains namedFocusedBrand (null means that execution produced no answer), and focusedBrand summarizes it, with tracked: false when the name matches none of the property's tracked brands. "Which answers named Roborock" is only answerable beside the ones that did not.

Raw answer text: pass a queryId from this tool's own prompts list and the response gains an answers block: that prompt's answers for the day, one entry per platform, each with the full text (capped at 6,000 characters, with answerTextTruncated saying when it was cut), the brands it named, and up to 25 citations. get_answer_summaries returns one prompt's answers uncapped and week by week instead.

If the day has no completed run (or falls outside the tracked range) the call reports that rather than returning zeros; pick a date that appears in get_metrics_history.

get_site_consultations

How often AI platforms consulted one specific site directly — a site:acme.com … grounding search — instead of searching the open web, split into your own site, tracked competitors, and third parties, for a window and the window immediately before it.

A scoped search means the model had already decided where the answer lives. Consulting your site is an authority signal; competitors consulted while you get none is the absence of one. See the Brand Dashboard for the concept and the in-app drill-down.

consultRate is normalized per execution, not per search: consultedExecutions / totalExecutions, the share of answers that searched at all in which the model consulted your site. One answer can fan out into a dozen searches, so a chatty platform cannot inflate it.

Each domains row carries the bare hostname, its class (own / competitor / third_party), the competitor it belongs to where relevant, the consultation count, the platforms that consulted it, when it was last seen, and residualQuery — the topic searched, with the site: operator stripped (empty for a bare site:acme.com, which reads as "just go read their site").

A third_party row with brandAffine: true is a suspected wrong domain: one that looks like the brand's but isn't. That is the signal the wrong-domain alerts fire on. Treat it as a lead — the domain may be real and holding authority that should be yours, or it may serve nothing at all — never as a settled fact.

The domains list is capped at the 50 most-consulted; domainsTotal gives the full count so a truncated list is never mistaken for the whole inventory.

This tool counts only searches carrying the site: operator. A search that consults a brand by naming it (CompetitorX pricing) is a different thing and does not appear here — it has no scoped domain to attribute. Those searches are still excluded from SERP checks and gap opportunities everywhere else, on the grounds that nothing you publish can rank for a question about a competitor's product; see list_tracked_fanouts.

get_consistency_history

A property's brand-consistency score over time (overall and per platform) — how consistently AI platforms describe the brand vs. its source-of-truth identity.

Locations and competitors

list_locations

Per-market AI share of voice for a brand's tracked locations (its LOCATION child properties). Each entry carries the market's city / region / country and its latest measurement — share of voice, mentions, citations, citation rate, and the measurement date — alongside a rollup.

averageSov is equal-weighted across the markets that have data: a "typical market" number that treats a small market and a large one alike. It deliberately will not match the brand-wide share of voice from get_metrics_history, which pools every answer. Feed a returned id back as locationPropertyId to scope get_metrics_history, get_competitor_share_of_voice, get_answer_drilldown or get_answer_summaries to that one market; an id that is not this property's own location is rejected. A brand with no tracked locations returns an empty list, not an error.

Each market also carries leader — the brand AI named most often there in that same measurement, as a name and a shareOfVoice — or null when the market has no competitor data yet. For a CATEGORY parent, which tracks a market with no focal brand and therefore has no share of voice of its own, leader is the only ranking the row carries.

get_competitor_share_of_voice

The ranked share of answers for the brands AI names, over a window you choose and any slice of it. For a CATEGORY property the same tool ranks the market's tracked brands, which the product calls Brands rather than competitors.

The ranking is pooled over the window: each brand's share is the answers that named it divided by the answers analyzed across every measured day in the window. It is not read off the latest measurement, because a single night is a handful of answers per brand and reorders on noise. The default window is 7 days; pass windowDays: 30 or 90 for a steadier order.

Each brand also carries totalCitations, queriesAppeared and gapQueriesCount, the prompts where the brand appeared and the focal subject did not, which is the acquisition gap worth acting on. Those three are not slice-scoped: they come from the latest whole measurement and ignore every filter, so label them as whole-measurement numbers or leave them out of a filtered answer.

How to read the rest of the payload:

• empty: true: the slice was measured and held no answers. Report the empty slice.
• thin: true: fewer than 20 answers landed in it, so the order is unstable. Widen the window before ranking anything on it.
• basis: "latest_row": the window carries no stage-scoped history, so no filter could be honored. The figures are the latest single measurement as stored, answersAnalyzed is 0 and series is empty. Say that rather than presenting them as a filtered answer.
• daysWithDimension below daysMeasured under a platform or tag filter: the remaining days never recorded that detail. Quote dimensionStartDate ("platform and tag detail starts on that date") instead of a share that silently undercounts them.
• brandShareOfAnswers / brandAnswersNamedIn / brandShareOfAnswersDelta are the focal subject's side of the same slice. Top-level brandShareOfVoice is the unsliced latest-measurement figure, so the two are not comparable.
• headline pools the consideration and decision stages of the same window (narrowed to your stage when you pass one), which is the definition the brand dashboard's share-of-voice hero uses. It is null for properties whose data predates stage scoping; never mix it with the top-level figures inside one ranking.

includeSeries: true adds series, the per-day line for the slice's top 6 brands, in table order, for charting. A point with hasDimension: false is a day that recorded no platform or tag detail: break the line there, never plot it as 0. The series is omitted by default to keep an ordinary call small.

get_recommendation_categories

How AI recommends your brand and every other brand it names, read from your daily tracking answers only. AI Visibility reports are not included. For each answer to a discovery prompt, Spyglasses classifies every brand the answer names, tracked or not, into one of four categories:

• Top choice: the answer singles the brand out as its pick or its explicit top recommendation.
• One of many: the answer recommends the brand alongside others, often with a note on who it is best for.
• Generic mention: the answer names the brand without evaluating or recommending it.
• Cautioned against: the answer steers this buyer away from the brand, usually for a stated reason such as price or complexity.

Each brand in each answer also comes with the caveats the answer gives (a reason type, a short reason and the audience it applies to) and a short quote from the answer.

How to read the rest of the payload:

• hasAssessedAnswers: false: daily tracking has not produced classified answers yet. Say it is not set up, not that the brand scored zero.
• An answer count of 0 is an empty slice. isEarlyRead: true means fewer than 30 answers, so treat the rates as directional.
• summary.previous and overview.previous hold the window of the same length just before this one. Each is null when your history does not reach back a full window. When history reaches back but nothing ran in that window (a new project, for example), previous reports 0 answers. In both cases the deltas (deltaPoints) are null, never 0, so there is no change to report.
• reasons lists why AI steers buyers away (cautioned-against answers only), grouped by reason type, with the audience each reason applies to. isNew marks a reason that did not appear in the previous window.
• bestFor lists who AI says you are best for when it recommends you.
• citedNotRecommended counts answers that cite one of your own pages but leave you out of the recommendations.
• unclassified counts answers where a tracked brand was named but not rated. It is rare and is not a verdict.
• isTracked is worked out when you ask, so a brand you start tracking today shows its full history right away.

Personas

Every discovery prompt on a project with personas also runs daily as each persona: the same question, with the persona's one-line description in front ("I'm the CFO at a 120-person B2B SaaS company in the US; we run NetSuite and HubSpot…"). Persona answers run on your AI platforms except Google AI Overviews, which is a search query with no asker. They never change your headline metrics: every other tool reads the baseline answers, asked with no persona.

list_personas

A property's buyer personas. Each comes with a role-first label (for example "CFO, early-stage startup"), its fields (role group, seniority, decision role, segment, company size, industry, region, tech stack, priorities and constraints), contextText (the exact description sent in front of each question), its version (it goes up when that text changes) and the projects it is on. Only personas on an active project run.

get_persona_lens

How AI answers each buyer compared with the baseline: the same prompts and platforms asked with no persona, over the same window. Each row is one persona, or a group of personas that share a role group, segment, company size or seniority. For each row and each lens brand (your brand, your tracked competitors and the most-named untracked brands) you get:

• the persona's rates in percent (mention, top choice, recommended, cautioned against) and the baseline's;
• deltaPoints, the difference, with deltaIntervalPoints (its 90% interval) and clear, true when the difference is larger than its interval;
• inBuyerStack, true for a brand the persona says it already uses.

Each row also has whoAiRecommends: each brand's share of the recommendations AI gave this buyer (untracked brands included, adding up to 100 with Other), next to the same brand's baseline share.

Brand & comparison prompts

Prompts typed brand_identity ("What is [brand]?") or brand_comparison ("[brand] vs [competitor]") always mention the brand, so they are excluded from share of voice and measured by these two tools instead.

get_brand_prompt_health

Per-prompt health metrics for brand/comparison prompts, one row per prompt per day: expected-message coverage (% of the prompt's "should appear" messages found in answers), unwanted-message incidence (% of answers containing a "should not appear" message — lower is better), and theme drift.

Drift is 0–1 against the prompt's trailing 28-day theme pool: 0 means today's answers cover the same themes as the recent past; 1 means an entirely new story. Each row includes the day's themes, the novelThemes driving the drift (themes with no close match in the pool), and a messageBreakdown showing each expected message's per-day match count and a sample matched sentence — so you can say which messages appeared and what shifted, not just the aggregate numbers.

get_comparison_verdicts

Aggregated head-to-head outcomes from brand_comparison prompts: per compared brand and day, how often answers favor it, what they favor it for (topFavoredFor — "agencies", "multi-language teams"), the verdict shapes (clear_winner, segmented_winners, no_verdict, list_only), the latest framing summary from an answer that compared that brand, and frequency-ranked strengths/weaknesses the answers attribute to it. isOurBrand marks the property's own brand.

Each row also carries a derived favoredRate (0–100, one decimal) — favoredCount / totalComparisons for that row.

Read both counts carefully. Favored counts are not zero-sum: a segmented answer ("X for agencies, Y for in-house teams") favors several brands at once, so per-brand favored counts can each exceed half the total and the rates across brands can sum past 100. And totalComparisons is the day's count of comparison answers, shared by every brand row for that day — it is not that brand's own sample size.

brand is alias-aware: pass a tracked competitor's name and rows recorded under any of its aliases are included too, because stored rows key on whatever name the answer used. A name that matches no tracked competitor is still accepted as a raw compared-brand name.

Message tracking and drift

These two pair together: one shows how often your key messages get pulled through, the other shows how the wording changes.

get_message_tracking

How often each tracked key message is pulled through into AI answers over time — a mention rate per message, plus first/latest values and the change. Good for a per-message trend chart.

Filter by tags and/or sentiment. Tags plus sentiment: NEGATIVE is the crisis-monitoring cut: the messages you never want AI to repeat, and whether it is repeating them — a rising rate there is bad news, the inverse of every other metric on this page.

get_answer_summaries

The full answer text AI platforms gave for one tracked query, bucketed by week (one representative answer per week per platform). Compare weeks to narrate how the AI's description of the brand shifts. Omit query to first list the property's tracked queries, then call again with the one you want.

tag, stage, projectId and locationPropertyId narrow the candidate prompts before anything is read, so the list you pick from is already the slice and the filters are never applied to a truncated result. stage maps each prompt's type to its funnel stage the same way every other tool does, which puts brand_identity prompts in awareness and brand_comparison prompts in decision.

Answer text is returned in full here, with no cap. get_answer_drilldown returns a capped version of the same day's answers alongside the prompts that produced them.

See the Key Messages dashboard for the concept behind both.

Citation intelligence

get_citation_intelligence

A property's citation intelligence: the mix of sources AI cites, broken down by media type, authority type, content format, and page type; per-platform stats; a historical trend (citation mix over time); and the top citation sources by owner (brand / competitor / third-party). Use the historicalData series to chart how the mix shifts.

The summary also includes the cited-vs-evaluated split (citationTypeBreakdown — sources referenced in the answer text vs merely fetched while composing it) and earned-media rollups (earnedMedia — third-party sources whose fetched page content mentions the brand, including hidden earned media that never surfaces in answer-text attribution). Each top source carries contentMentions: brands found in its pages' content, distinct from answer-text brandMentions.

For "what would this filter give me?" questions, facetCounts holds per-dimension value counts computed with that dimension's own filter lifted (so media type, authority type, content format and platform compose instead of zeroing each other out), and facetTotals holds the same tallies with all four lifted.

facetPublisherCounts holds the same facet-excluded tallies counted in distinct publishers instead of citations, and facetPublisherDistinct gives the distinct publisher total for each dimension (one publisher can appear under several values, so the values can add up to more). Each top source also carries platformCitations, its citations split by platform, and summary.answerCount is the number of distinct AI answers behind totalCitations.

For a category property (a tracked market with no focal brand) nothing is "our brand": earnedMedia is always zero, no source has mentionsOurBrand, and contentMentions only lists the tracked brands.

See the Citation Intelligence dashboard for how these breakdowns are defined.

get_coverage_citations

For a coverage group (a list of earned-media placement URLs), the AI citations its URLs earned from the property's tracked prompts and reports. Answers "which prompt and platform cited my placement, and in what context?"

Returns a funnel (coverage URLs → cited by AI → cited inline), a cited-vs-uncited comparison (average AIPQS, word count, content age, byline share, top authors), per-URL rollups, and the individual citation hits — each with the prompt text, platform, model, date, citation type (cited_inline = referenced in the answer text, a true citation; evaluated_source = fetched but not referenced), and, for inline citations, the answer-text context around the reference.

Call without groupId to first list the property's coverage groups, then call again with the one you want.

Counts here are scoped to your property's own tracked prompts and reports — the same numbers as the coverage group's citations page in the dashboard.

get_project_goal_citations

For a project goal, the citations behind its hit count — with each citation classified by brand relevance. Publisher (and author / page-group) goals match on the source, so their counts include citations unrelated to the brand; this tool separates them:

• attributed — the answer credited the brand for this source by name, or (on Google AI Overviews) the overview mentions the brand while this source is in its list. AIO doesn't credit sources individually, so those hits carry attributedViaAio: true — treat them as strong-but-circumstantial
• content_mention — the cited page's fetched content mentions the brand, but the answer never credited it (hidden earned media; includes the mention context from the page)
• answer_mention — the answer mentions the brand somewhere, just not attached to this citation
• unrelated — the source matched on its own authority, and the answer never mentions the brand

Hits are scoped to the project window, so totals match the project page's goal counts exactly. Returns a breakdown (total / attributed / content mentions / hidden earned media / answer mentions / cited inline / unrelated) plus per-citation prompt, platform, model, date, citation type, and answer context. Call without goalId to list the project's goals with their citation counts, then call again with the one you want.

Pitch lists

A pitch list is a named list of publishers a PR team plans to pitch. A property list belongs to one brand; an organization list spans many, and each of its rows can name a brand or none. These three tools read pitch lists and add to them. add_pitch_list_publishers is the one tool on this page that writes.

list_pitch_lists

Lists the pitch lists on a property, or the organization-level lists on an organization. Pass one of the two ids. Use a returned id as the listId for the other two tools.

get_pitch_list

One pitch list with its rows. Each row carries the publisher's domain and name, Est. Traffic, Domain Rank, status, note and, on organization lists, its brand; the AI citation counts for the window, split by platform; and a Placed suggestion when a scored placement for the brand exists on a publisher whose row is still Target or Pitched. The suggestion is only a suggestion: the status changes only when someone changes it.

Citation counts come from tracked brands' prompts and reports. On an organization list, a row with a tracked brand counts that brand's citations, a row with no brand counts citations across every tracked brand in the organization, and a row with a scoring-only brand has no count (it reads Not tracked in the app). Domain Rank is DataForSEO's third-party authority score and is not an input to AIPVS.

add_pitch_list_publishers

Writes. Adds publisher domains to a pitch list in your account. Name the list one of two ways:

• listId adds to an existing list.
• propertyId or organizationId plus name adds to the list with that name in that scope, and creates the list first if there isn't one.

Each domain (or URL, trimmed to its domain) becomes a row with the status Target. Domains already on the list are skipped, and values that aren't a domain are reported back rather than failing the call. A domain Spyglasses hasn't seen before gets a publisher record and is queued for enrichment, so its traffic and logo fill in shortly afterward and its Domain Rank within a few hours. Rows added to an organization list this way carry no brand. The call spends no credits.

A typical flow

Or run the Analyze a project, Who does AI name here?, Track message drift, or Citation mix over time prompts.

Related

• Projects dashboard · Key Messages dashboard · Citation Intelligence dashboard · Pitch Lists
• Scoring tools — evaluate publishers and placements for a property