# Account data tools

These tools cover the **account-scoped** surface of the MCP server — your own private data. Every one is **read-only** and gated by your membership: the server checks that your signed-in account can access the property before returning anything.

Almost everything here starts from a **propertyId**, so the first call in any account session is `list_properties`.

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.

| Parameter | Type | Notes |
|---|---|---|
| `organizationId` | string (optional) | Restrict to one of your organizations. |
| `includeProspects` | boolean (optional) | Include bulk-imported prospect properties (default `false`). |

## Projects

Projects are bundled, time-bound tracking efforts (an SEO push, a PR campaign). See the [Projects dashboard](/docs/dashboards/projects) for the concept.

### `list_projects`

Lists a property's projects with each one's type, status, date range, goals, and counts.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `status` | `ACTIVE` \| `COMPLETED` \| `ARCHIVED` (optional) | Filter by status. |

### `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.

| Parameter | Type | Notes |
|---|---|---|
| `projectId` | string | From `list_projects`. |

<Callout>
Project-level deltas and weekly trends come from `get_project_insights`. Property-wide history (not scoped to a project) comes from `get_metrics_history` below.
</Callout>

## Historical trends

### `get_metrics_history`

A property's AI visibility metrics over time — one point per report / nightly run: share of voice, mentions, citations, citation rate, and per-platform breakdowns. Pass a `projectId` to also get the grounding-search **ranking** trend scoped to that project's tracked queries.

Pass a `tag` to get a **theme-scoped** series instead: one point per UTC day, each with per-stage (awareness / consideration / decision) mentions, opportunities and share of voice for that tag, plus the day's consideration + decision **headline**. Pass a `locationPropertyId` to scope the series to one tracked market. The two combine.

<Callout>
Two things to know about tag slices. Prompt tags are **overlapping facets**, not a partition — one prompt can carry several tags, so per-tag numbers do not sum to the property total and can each exceed a large share of it. And an **empty tag slice means no tagged data existed on those days** — not that brand activity was zero. A tag added last week has nothing before then; read that as "no data", never as a drop.
</Callout>

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `projectId` | string (optional) | Also return grounding-search trends scoped to this project. |
| `tag` | string (optional) | Return the tag-scoped daily series instead of the brand-wide one. Tags come from `list_prompt_tags`. |
| `locationPropertyId` | string (optional) | Scope to one LOCATION child of this property. Ids come from `list_locations`; anything else is rejected. |
| `startDate` / `endDate` | string (optional) | ISO date bounds. |
| `limit` | number (optional) | Max points when no date range is given (default 30, max 100). |

### `list_prompt_tags`

The **filter 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 will return an empty series.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |

### `get_answer_drilldown`

The **L3 drill-down** behind the visibility dashboard. For one UTC day it lists the tracked prompts that ran, and for each one every platform execution: which model answered, whether the answer mentioned the brand, the brand's rank inside the answer, 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?".

It returns no answer **text** — use `get_answer_summaries` for wording. 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`.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `date` | string | The UTC day to explain, `YYYY-MM-DD`. |
| `stage` | `awareness` \| `consideration` \| `decision` (optional) | Restrict to one funnel stage (default: all three). |
| `platform` | string (optional) | `all`, `chatgpt`, `gemini`, `perplexity`, `claude`, or `googleAiOverview`. |
| `tag` | string (optional) | Only prompts carrying this tag. |
| `locationPropertyId` | string (optional) | Scope to one LOCATION child. |
| `projectId` | string (optional) | Only prompts assigned to this project. |

### `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.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `startDate` / `endDate` | string (optional) | ISO date bounds. |
| `limit` | number (optional) | Max points (default 30, max 100). |

## 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. For one market's history over time, feed its `id` back into `get_metrics_history` as `locationPropertyId`. A brand with no tracked locations returns an empty list, not an error.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | The **parent** property id, from `list_properties`. |

### `get_competitor_share_of_voice`

The ranked competitor share of voice from a property's latest measurement (nightly run or report, whichever is fresher). Each competitor carries `shareOfVoice`, `totalMentions`, `totalCitations`, `queriesAppeared`, and `gapQueriesCount` — the prompts where the **competitor appeared and the brand did not**, which is the acquisition gap worth acting on.

Two bases come back, and they must not be mixed inside one ranking:

- The top-level `brandShareOfVoice` and per-competitor values are the stored numbers from that **single measurement**, spanning **all** funnel stages.
- `headline` pools the **last 7 days** over the **consideration and decision** stages only — the same definition the brand dashboard's share-of-voice hero uses, and therefore the one to quote when it is present.

`headline` is `null` for properties whose data predates stage scoping; fall back to the all-stage fields in one piece when that happens.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |

## 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.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `queryId` | string (optional) | Restrict to one prompt. |
| `startDate` / `endDate` | string (optional) | ISO date bounds. |
| `limit` | number (optional) | Max rows when no date range is given (default 60, max 200). |

### `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`), a sample framing summary, 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.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `brand` | string (optional) | Restrict to one compared brand (case-insensitive; matches a tracked competitor's name or any alias, or a raw compared-brand name). |
| `projectId` | string (optional) | Re-aggregate over this project's comparison prompts only, instead of all of the property's. |
| `startDate` / `endDate` | string (optional) | ISO date bounds. |
| `limit` | number (optional) | Max rows returned (default 100, max 400) — applied to date-ranged reads too. |

## 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.

<Callout>
Key-message tags are a **separate namespace** from prompt tags. They live on the messages, not on the prompts, and teams usually mirror the names by convention — but a tag from `list_prompt_tags` may not exist here, and vice versa.
</Callout>

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `tags` | string[] (optional) | Only messages carrying at least one of these key-message tags (e.g. `["crisis"]`). |
| `sentiment` | `POSITIVE` \| `NEGATIVE` \| `NEUTRAL` (optional) | Only messages with this polarity. `NEGATIVE` = "should not appear" messages. |
| `startDate` / `endDate` | string (optional) | ISO date bounds. |

### `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.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `query` | string (optional) | A tracked query (exact or substring). Omit to list available queries. |
| `platform` | string (optional) | `openai`, `claude`, `gemini`, `perplexity`, or `google_ai_overview`. |
| `maxWeeks` | number (optional) | Most-recent weeks to return (default 12, max 52). |
| `startDate` / `endDate` | string (optional) | ISO date bounds. |

See the [Key Messages dashboard](/docs/dashboards/key-messages) 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.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `platform` | string (optional) | Filter by platform, or `all`. |
| `contentFormat` | string (optional) | |
| `mediaType` | string (optional) | |
| `authorityType` | string (optional) | |
| `brandAttributed` | string (optional) | A brand name, `_any_brand`, or `_unattributed` — matches **answer-text attribution**. |
| `citationType` | string (optional) | `cited_inline`, `evaluated_source`, `search_result`, or `unclassified`. |
| `mentionedBrand` | string (optional) | A brand name, `_our_brand`, or `_any_competitor` — matches **fetched page content**, catching earned media the answer never attributes. |
| `startDate` / `endDate` | string (optional) | ISO date bounds. |

See the [Citation Intelligence dashboard](/docs/dashboards/citation-intelligence) 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.

| Parameter | Type | Notes |
|---|---|---|
| `propertyId` | string | From `list_properties`. |
| `groupId` | string (optional) | A coverage group id. Omit to list available groups. |
| `url` | string (optional) | Filter hits to one coverage URL (any variant — normalized). |
| `citationType` | string (optional) | `cited_inline` (referenced in the answer — a true citation), `evaluated_source` (the AI read the page but didn't reference it), `search_result` (appeared in the AI's web search but wasn't picked up), `unclassified`, or `all`. |
| `platform` | string (optional) | `openai`, `claude`, `gemini`, `perplexity`, or `google_ai_overview`. |
| `startDate` / `endDate` | string (optional) | ISO date bounds on the citing answer's date. |
| `limit` | number (optional) | Max citation hits to return (default 50, max 200). |

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.

| Parameter | Type | Notes |
|---|---|---|
| `projectId` | string | From `list_projects`. |
| `goalId` | string (optional) | A goal id. Omit to list the project's goals. |
| `relevance` | string (optional) | `attributed`, `content_mention`, `answer_mention`, `unrelated`, `brand` (attributed or content mention), `hidden` (content mention but not cited inline), or `all`. |
| `citationType` | string (optional) | `cited_inline`, `evaluated_source`, `search_result`, `unclassified`, or `all`. |
| `platform` | string (optional) | `openai`, `claude`, `gemini`, `perplexity`, or `google_ai_overview`. |
| `startDate` / `endDate` | string (optional) | ISO date bounds on the citing answer's date. |
| `limit` | number (optional) | Max citation hits to return (default 50, max 200). |

## A typical flow

<Steps>

<Step>
`list_properties` → copy the `propertyId` you want to work with.
</Step>

<Step>
For trends: `get_metrics_history` / `get_consistency_history`, then ask for charts.
</Step>

<Step>
For messaging: `get_message_tracking`, then `get_answer_summaries` on the most strategic query.
</Step>

<Step>
For a specific effort: `list_projects` → `get_project_insights`.
</Step>

</Steps>

Or run the **Analyze a project**, **Track message drift**, or **Citation mix over time** [prompts](/docs/mcp/prompts).

## Related

- [Projects dashboard](/docs/dashboards/projects) · [Key Messages dashboard](/docs/dashboards/key-messages) · [Citation Intelligence dashboard](/docs/dashboards/citation-intelligence)
- [Scoring tools](/docs/mcp/scoring) — evaluate publishers and placements for a property