# All Ears MCP — Monitor use cases

A **monitor** is a saved query whose matching mentions are continuously
collected and **enriched** — sentiment, reach and PR value that a raw keyword
match does not carry. Every analytics tool below runs against a saved monitor
by UUID.

> **Entitlement:** every monitor tool is available to every organization.
>
> - The monitor **CRUD/read** tools (`list_monitors`, `get_monitor`,
>   `create_monitor`, `update_monitor`, `archive_monitor`, `get_mentions`,
>   `get_metrics`) need the `monitor:read` scope, and `monitor:write` for
>   create / update / archive.
> - The monitor **analytics operators** (`monitor_*`) need `monitor:read`.
>
> A tool returns a permission error if the token lacks the scope, or if you
> are a read-only user.

> Example numbers below are illustrative. Tool names, arguments, and response
> shape are the contract; the specific values are not.

## Contents

- [How monitors work (read first)](#how-monitors-work)
- [Monitor basics (CRUD/read)](#monitor-basics)
- [Monitor analytics operators](#monitor-analytics-operators)
- [Volume: how much coverage did this monitor get?](#volume)
- [Headline totals: one number for reach / PR value](#headline-totals)
- [Unique channels: how many outlets mentioned this?](#unique-channels)
- [Trend: how is it moving over time?](#trend)
- [Spikes: when did it blow up?](#spikes)
- [Growth: up or down vs the previous period?](#growth)
- [Top channels: where does this live?](#top-channels)
- [Share of voice: how is a monitor's coverage split across channel types?](#share-of-voice)
- [Sentiment: how do they feel?](#sentiment)
- [Conversation terms: what are they saying around this?](#conversation-terms)
- [Evidence & export: show me the actual mentions](#evidence)
- [Compare several monitors at once](#compare-several-monitors)

## How monitors work (read first) {#how-monitors-work}

- **Creating a monitor is a background job.** `create_monitor` returns
  immediately, but historical mentions are backfilled asynchronously and
  sentiment is computed by separate workers *after* mentions land. For large
  datasets this takes minutes to hours. `get_monitor` / `create_monitor` /
  `update_monitor` return `backfill_in_progress`: true while the historical
  pass is still running, false once it finishes. It does not track sentiment
  scoring, which is a separate queue —
  sentiment-dependent analysis may be incomplete even after
  `backfill_in_progress` turns false, and might need to be revisited later —
  by re-querying and watching sentiment fill in from `null`.
- **Mentions are enriched.** Each mention carries sentiment, reach and PR
  value. Every analytics operator accepts the same dashboard filters:
  `channel_type`, `channel_name`, `medium`, `language`, `sentiment`,
  `min_reach`, `freetext` and `insight_types` (`positive_impact`,
  `negative_impact`, `toplist_mentions`). Organizations without insights have
  no tagged mentions, so `insight_types` returns an empty set.
- **Mentions vs episodes.** A monitor distinguishes distinct *episodes* (one
  content item — a podcast episode, video, article, post) from individual
  *mention passages* inside them (one episode can yield many). Both counts come
  from `monitor_episode_count` (it returns `episode_count` and
  `mention_count`), and most metrics can be measured either way.
- **Resolve the UUID first.** When the user names a monitor, call
  `list_monitors` and match on `title` before calling any analytics operator.

## Monitor basics (CRUD/read) {#monitor-basics}

| Tool | What it does |
|---|---|
| `list_monitors` | List your monitors. Call this first to resolve a monitor's UUID. |
| `get_monitor` | Inspect one monitor's configured keywords/queries by UUID. |
| `create_monitor` | Create a new keyword monitor (kicks off the async backfill). |
| `update_monitor` | Edit an existing monitor's title or query blocks in place. |
| `archive_monitor` | Soft-delete a monitor. |
| `get_mentions` | Page-based enriched mention rows (interactive "show me a few"). |
| `get_metrics` | Aggregated daily metrics: mentions, reach, net sentiment, PR value. |

**Creating a monitor** — each query block needs non-empty `keywords`, `sources`
(media types; use `news` for online news, and the individual platforms for
social — there is no `online_news` or `social_media` value), and `languages`.
Pass optional `start_date` (`YYYY-MM-DD`) to set how far back the historical
backfill collects; omit it and the monitor starts from the creation date:

```json
{
  "tool": "create_monitor",
  "arguments": {
    "title": "Climate Change",
    "start_date": "2025-01-01",
    "queries": [
      {"keywords": ["climate change", "global warming"],
       "sources": ["podcast", "news"],
       "languages": ["en"]}
    ]
  }
}
```

If you belong to more than one organization, add an `organization` argument (an
org `uuid` from `list_organizations`) naming the org to create the monitor in —
otherwise the call returns a `400` listing your orgs. A single-org user can omit
it. The query blocks' `sources` / `languages` are validated against that org, so
pick one whose entitlements cover them. `update_monitor` needs no `organization`:
an update always stays on the monitor's existing org.

## Monitor analytics operators {#monitor-analytics-operators}

Each operator runs against a monitor UUID (with `mode: "monitor"` echoed in the
response) and accepts the dashboard filters (`channel_type`, `channel_name`,
`medium`, `language`, `sentiment`, `min_reach`, `freetext`, `insight_types`) plus an optional
`start_date` / `end_date` window.

| Operator | Use case | Metrics / extras |
|---|---|---|
| `monitor_episode_count` | [Volume](#volume) (episodes **and** per-passage mentions) | returns both `episode_count` and `mention_count` |
| `monitor_totals` | [Headline number](#headline-totals) | `metric: "reach"` / `"pr_value"` / `"episode_count"` / `"mention_count"` |
| `monitor_channel_count` | [Unique channels](#unique-channels) | distinct channel count |
| `monitor_time_series` | [Trend](#trend) | `metric: "episode_count"` / `"mention_count"` / `"reach"` / `"pr_value"` / `"sentiment"`; `split_by: "channel_type"` |
| `monitor_detect_peaks` | [Spikes](#spikes) | `metric: "episode_count"` / `"mention_count"` / `"reach"` / `"pr_value"` |
| `monitor_growth_rate` | [Growth](#growth) | `metric: "episode_count"` / `"mention_count"` / `"reach"` / `"pr_value"` / `"sentiment"` |
| `monitor_top_sources` | [Top channels](#top-channels) | `metric: "episodes"` / `"mentions"` / `"reach"` / `"pr_value"`; `details: true` adds `episode_count` + `sentiment` per channel |
| `monitor_distribution` | [Share of voice by channel type](#share-of-voice) | `metric: "episode_count"` / `"mention_count"` / `"reach"` / `"pr_value"` |
| `monitor_sentiment_distribution` | [Sentiment](#sentiment) | counts, shares, net sentiment |
| `monitor_top_terms` | [Conversation terms](#conversation-terms) | scored vs general language |
| `monitor_get_mentions` | [Evidence / **full export**](#evidence) | enriched rows (each with `reach_at_creation` + `pr_value`), cursor-paginated |

**Medium.** The `medium` filter narrows to `audio` (transcribed speech in
podcasts, video and broadcast) or `text` (episode titles & descriptions, online
news articles, social posts). The default `all` covers both — you do **not**
need to run a tool twice to get the whole monitor.

**Reach & PR value.** Every operator above that takes a `metric` also accepts
`reach` (summed audience of the distinct matched episodes) and `pr_value`
(advertising-equivalent value derived from that reach), plus the headline
`monitor_totals`. `pr_value` is returned as `null` (not `0`) when your plan
doesn't include PR value or no matched episode falls in a PR-value-enabled
market — show the user "—" rather than a misleading zero. Pass an optional
`currency` to select the PR-value currency — one of `"SEK"` (base, default),
`"USD"`, `"EUR"` or `"NOK"` (the tool schema lists exactly these, so don't
invent other codes).

**Window date basis.** Every *analytic* windows on the mention's
`published_date` (when the content was published) — the same basis as the
dashboard, so the numbers are comparable across tools. The one exception is
`monitor_get_mentions`, the export/streaming primitive, which takes an optional
`date_filter_field` and **defaults to `"created"`** (when the monitor *detected*
the mention) — the right basis for incremental export ("give me everything
ingested since my last sync"), which also catches back-catalogue episodes
published long before they were found. Pass `"published_date"` when you instead
want the list to reconcile with the analytics. The aggregation tools
intentionally don't offer this switch.

---

## Volume: how much coverage did this monitor get? {#volume}

- **Question:** How many episodes and how many mention passages did the monitor
  collect in a window?
- **Who:** Analyst / comms / agent sizing a tracked topic.
- **Tool:** `monitor_episode_count`.

**Example call**

```json
{
  "tool": "monitor_episode_count",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "episode_count",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "episode_count": 412,
  "mention_count": 988,
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T00:00:00"
}
```

- **A good answer:** both numbers, labelled — `episode_count` is distinct
  content items, `mention_count` is passages inside them (one episode can
  contribute many). Say which one you are quoting.
- **Limitations:** counts only what the monitor's query matched; a keyword the
  monitor doesn't track is invisible here (edit it with `update_monitor`).
- **Won't tell you:** how it moved over time (Trend), who said it, or the
  audience behind it (Headline totals).

---

## Headline totals: one number for reach / PR value {#headline-totals}

- **Question:** What's the *total* reach or PR value of a monitor's coverage in a
  window (the big number above the graph)? How many episodes or mentions in all?
- **Who:** Comms / analyst / agent reporting headline impact.
- **Tool:** `monitor_totals`. Pick one `metric`: `reach`, `pr_value`,
  `episode_count` or `mention_count`. For the same number *over time*, use
  `monitor_time_series` with the matching metric.

**Example call**

```json
{
  "tool": "monitor_totals",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "metric": "pr_value",
    "currency": "USD",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "totals",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "metric": "pr_value",
  "value": 128400,
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T00:00:00"
}
```

- **A good answer:** the single `value` for the requested `metric`, stated with
  its window (and currency for `pr_value`). Reach is summed **once per distinct
  episode**, so an episode mentioned many times counts its audience once.
- **Limitations:** `value` is `null` for `metric: "pr_value"` when your plan
  lacks PR value or no matched episode is in a PR-value-enabled market — render
  "—", not `0`.
- **Won't tell you:** the breakdown behind the number — use `monitor_top_sources`
  (by channel) or `monitor_distribution` (by channel type) for that, or
  `monitor_time_series` for the trend.

---

## Unique channels: how many outlets mentioned this? {#unique-channels}

- **Question:** How many *distinct* shows / outlets / channels have mentions on
  this monitor in a window?
- **Who:** Comms / analyst / agent reporting breadth of coverage.
- **Tool:** `monitor_channel_count`. Returns `channel_count`: unique channel
  ids with at least one matching mention (irrelevant mentions are excluded).
  For *which* channels, use `monitor_top_sources`; for episode / mention volume
  use `monitor_episode_count`.

**Example call**

```json
{
  "tool": "monitor_channel_count",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31",
    "channel_type": ["podcast"]
  }
}
```

**Example response**

```json
{
  "operator": "channel_count",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "channel_count": 47,
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T00:00:00"
}
```

- **A good answer:** the single `channel_count` for the requested window (and
  filters). Several mentions on the same show still count as one channel.
- **Limitations:** same dashboard filters as the other monitor analytics
  (`channel_type`, `channel_name`, `medium`, `language`, `sentiment`,
  `min_reach`, `freetext`, `insight_types`).
- **Won't tell you:** the ranked list of those channels — use
  `monitor_top_sources` for that.

---

## Trend: how is it moving over time? {#trend}

- **Question:** What does the volume (or reach / PR value / sentiment) curve look
  like over a window?
- **Who:** Comms / analyst / agent building a trend line.
- **Tool:** `monitor_time_series`. `granularity` is `hour`, `day` (default),
  `week` or `month`.

**Example call**

```json
{
  "tool": "monitor_time_series",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "metric": "episode_count",
    "granularity": "week",
    "start_date": "2026-01-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "time_series",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "granularity": "week",
  "metric": "episode_count",
  "split_by": null,
  "start_date": "2026-01-01T00:00:00",
  "end_date": "2026-05-31T00:00:00",
  "points": [
    {"date": "2026-01-05", "value": 71},
    {"date": "2026-01-12", "value": 88}
  ]
}
```

- **A good answer:** the bucketed series; its `points` sum to the Volume count
  for the same monitor/window/metric. Optionally `split_by: "channel_type"` for
  one series per channel type (the response then adds a `series` list of
  `{key, points}` next to the overall `points`; not available together with
  `reach` / `pr_value` / `sentiment`).
- **Sentiment over time:** `metric: "sentiment"` makes each point
  `{date, value, positive, neutral, negative, unknown}` — `value` is the mean
  scored sentiment in −1…+1 (same scale as
  `monitor_sentiment_distribution.net_sentiment`), the counts are mentions per
  label (`very_positive` folds into `positive`, `very_negative` into
  `negative`, `unknown` is not scored yet and excluded from `value`). Empty
  buckets fill as `0`.
- **Limitations:** the most recent bucket can be partial (ingest lag) — flag or
  drop it. Prefer recent windows; very old windows are less reliable.
- **Won't tell you:** *why* it moved — read the mentions (Evidence) or the
  Conversation terms.

---

## Spikes: when did it blow up? {#spikes}

- **Question:** Which buckets exceeded the monitor's normal baseline?
- **Who:** Comms / agent investigating a surge.
- **Tool:** `monitor_detect_peaks`.

**Example call**

```json
{
  "tool": "monitor_detect_peaks",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "granularity": "day",
    "threshold": 2.5,
    "min_value": 5,
    "start_date": "2026-04-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "detect_peaks",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "metric": "episode_count",
  "granularity": "day",
  "threshold": 2.5,
  "min_value": 5,
  "period": 7,
  "window": 28,
  "points": [
    {"date": "2026-04-01", "value": 4},
    {"date": "2026-05-14", "value": 63}
  ],
  "peaks": [
    {"date": "2026-05-14", "value": 63, "score": 4.1, "expected": 7.2}
  ],
  "baseline": {"method": "causal-seasonal-rolling", "period": 7, "window": 28},
  "start_date": "2026-04-01T00:00:00",
  "end_date": "2026-05-31T00:00:00"
}
```

- **A good answer:** peak buckets (already sorted largest-`score` first), each
  with the bucket value, its `score`, and the `expected` baseline rate so the
  reader can judge significance. `points` equals `monitor_time_series` over the
  same window.
- **Limitations:** daily data gets weekly seasonality by default (`period: 7`),
  so a regular weekly cycle is not flagged. Raise `min_value` to suppress "2
  instead of 1" noise. A freshly created monitor has no history to build a
  baseline from, so its first busy day is reported as a peak. Works on `reach`
  / `pr_value` too, but `min_value` is then an absolute reach / PR-value floor.
- **Won't tell you:** what caused the spike (read the mentions — see Evidence).

---

## Growth: up or down vs the previous period? {#growth}

- **Question:** What's the period-over-period change (WoW / MoM / YoY)?
- **Who:** Analyst / agent producing a headline delta.
- **Tool:** `monitor_growth_rate`.

**Example call**

```json
{
  "tool": "monitor_growth_rate",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "metric": "episode_count",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "growth_rate",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "metric": "episode_count",
  "value": 412,
  "previous_value": 350,
  "delta": 62,
  "change_pct": 17.7,
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T00:00:00",
  "compare_start_date": "2026-03-31T00:00:00",
  "compare_end_date": "2026-04-30T00:00:00"
}
```

- **A good answer:** current vs previous with the delta and percent. The default
  comparison window is the immediately preceding window of equal length
  (override with `compare_start_date` / `compare_end_date`, passed together).
- **Sentiment growth:** `metric: "sentiment"` returns the mean scored sentiment
  in −1…+1 per window (`null` when a window has no scored mentions);
  `change_pct` is then movement as a percent of that −1…+1 range, not a ratio
  of the prior mean. The same response also carries `positive` / `neutral` /
  `negative` mention-count deltas, each `{value, previous_value, delta,
  change_pct}` (`very_positive` folds into `positive`, `very_negative` into
  `negative`; a bucket's `change_pct` is `null` when its previous count is 0).
- **Limitations:** `change_pct` is `null` when the previous window was 0.
- **Won't tell you:** what drove the change.

---

## Top channels: where does this live? {#top-channels}

- **Question:** Which shows/feeds/outlets carry the most coverage on a monitor?
- **Who:** Comms / analyst / agent mapping where to listen or pitch.
- **Tool:** `monitor_top_sources`.

**Example call**

```json
{
  "tool": "monitor_top_sources",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "metric": "episodes",
    "size": 10,
    "details": true,
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "top_sources",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "size": 10,
  "metric": "episodes",
  "sources": [
    {"channel_id": 3141, "channel_name": "The EV Show", "channel_type": "podcast",
     "channel_artwork_url": "https://...", "value": 28,
     "episode_count": 28,
     "sentiment": {"very_positive": 2, "positive": 11, "neutral": 20,
                   "negative": 6, "very_negative": 0, "unknown": 1}},
    {"channel_id": 9020, "channel_name": "Auto Weekly", "channel_type": "youtube",
     "channel_artwork_url": null, "value": 19,
     "episode_count": 19,
     "sentiment": {"very_positive": 0, "positive": 7, "neutral": 15,
                   "negative": 3, "very_negative": 1, "unknown": 0}}
  ],
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T00:00:00"
}
```

- **A good answer:** a ranked, human-readable channel list (names + types, not
  opaque ids), each with its `value` in the requested `metric` — distinct
  episodes (`episodes`, default), passages (`mentions`), summed audience
  (`reach`) or summed PR value (`pr_value`; `reach` / `pr_value` count each
  episode once). With `details: true` every row also carries `episode_count`
  and a `sentiment` split (same six labels as
  `monitor_sentiment_distribution`).
- **Limitations:** ranks **channels**, not individual people (hosts, guests,
  creators).
- **Won't tell you:** which host/guest is talking.

---

## Share of voice: how is a monitor's coverage split across channel types? {#share-of-voice}

- **Question:** What share of a monitor's coverage is podcast vs YouTube vs TV vs
  radio vs news?
- **Who:** Comms / analyst / agent profiling *where* a tracked topic lives.
- **Tool:** `monitor_distribution`.

**Example call**

```json
{
  "tool": "monitor_distribution",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "dimension": "channel_type",
    "metric": "episode_count",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "distribution",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "dimension": "channel_type",
  "metric": "episode_count",
  "counts": {"podcast": 240, "youtube": 96, "tv": 41, "radio": 23, "news": 12},
  "shares": {"podcast": 0.581, "youtube": 0.233, "tv": 0.099, "radio": 0.056, "news": 0.031},
  "total": 412,
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T00:00:00"
}
```

- **A good answer:** per-channel-type `counts` + `shares` (sum ~1) + `total`.
  The `total` equals the Volume count for the same monitor/window/metric — this
  is one monitor's volume split by channel type. Split by
  `metric: "mention_count"` (per-passage), `"reach"` or `"pr_value"` as well as
  the default `episode_count`.
- **Limitations:** `channel_type` is the only dimension. This is *share of voice
  by channel type for one monitor*, **not** cross-monitor/brand share of voice —
  for that, run it per monitor (or use the multi-monitor compare, below) and
  combine client-side.
- **Won't tell you:** how several monitors split a shared market in one call;
  sentiment per channel type. For sentiment **per channel**, call
  `monitor_top_sources` with `details: true`.

---

## Sentiment: how do they feel? {#sentiment}

- **Question:** What's the positive/negative/neutral split and net sentiment?
- **Who:** Comms / analyst / agent reporting tone.
- **Tool:** `monitor_sentiment_distribution`. Requires a saved monitor; if none
  exists, create one (`create_monitor`) and warn that sentiment backfills
  asynchronously.

**Example call**

```json
{
  "tool": "monitor_sentiment_distribution",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "sentiment_distribution",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "counts": {
    "very_positive": 12, "positive": 88, "neutral": 140,
    "negative": 53, "very_negative": 9, "unknown": 21
  },
  "shares": {
    "very_positive": 0.04, "positive": 0.29, "neutral": 0.46,
    "negative": 0.18, "very_negative": 0.03, "unknown": null
  },
  "scored": 302,
  "total": 323,
  "net_sentiment": 0.11,
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T00:00:00"
}
```

- **A good answer:** counts + shares (shares exclude `unknown` from the
  denominator) + net sentiment in −1…+1. State how many were `scored` vs
  `total`.
- **Limitations:** on a freshly created monitor, sentiment is `unknown` until
  backfill finishes. For **net sentiment over time** use
  `monitor_time_series` with `metric: "sentiment"`; for the period-over-period
  change use `monitor_growth_rate` with `metric: "sentiment"` (both described
  under Trend and Growth above).
- **Won't tell you:** discrete emotions (joy/anger/…), or *why* the sentiment is
  what it is. Sentiment per channel is on `monitor_top_sources` with
  `details: true`.

---

## Conversation terms: what are they saying around this? {#conversation-terms}

- **Question:** Which terms are statistically over-represented in the monitor's
  mentions?
- **Who:** Analyst / journalist / agent wanting the shape of the conversation
  (word cloud).
- **Tool:** `monitor_top_terms`.

**Example call**

```json
{
  "tool": "monitor_top_terms",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "size": 25,
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "top_terms",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "size": 25,
  "terms": [
    {"term": "rate cut", "doc_count": 140, "score": 0.81, "bg_count": null},
    {"term": "inflation", "doc_count": 95, "score": 0.64, "bg_count": null}
  ],
  "start_date": "2026-05-01T00:00:00",
  "end_date": "2026-05-31T00:00:00"
}
```

- **A good answer:** terms over-represented versus everyday language (not
  generic stopwords, not the monitor's own keywords), ranked by `score`
  (significance). `doc_count` is how many distinct mentions contained the term
  — a frequency, not the ranking key. `bg_count` is always `null` on a monitor
  (the baseline is a general-language model, not a countable corpus).
- **Limitations:** these are lexical co-occurring terms, **not** semantic topics
  or named entities. A low-volume monitor legitimately returns few terms —
  significance can't be established from a handful of mentions.
- **Won't tell you:** topic clusters, entities, or meaning-based grouping.

---

## Evidence & export: show me the actual mentions {#evidence}

- **Question:** What are the real passages behind the numbers? / Give me every
  mention since my last sync.
- **Who:** Journalist / agent needing quotes; integrations exporting a
  monitor's dataset.
- **Tool:** `monitor_get_mentions` (cursor-paginated). For an interactive
  "show me a few", the page-based `get_mentions` (with `page` / `page_size`)
  is also fine.

**Example call**

```json
{
  "tool": "monitor_get_mentions",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "page_size": 50,
    "include_related": true,
    "date_filter_field": "published_date",
    "start_date": "2026-05-10",
    "end_date": "2026-05-17"
  }
}
```

**Example response**

```json
{
  "operator": "get_mentions",
  "mode": "monitor",
  "monitor_uuid": "8f3c0a21-...-e21",
  "results": [
    {
      "uuid": "1c9d3e70-...-4a2",
      "text": "...we switched to our brand last year and never looked back...",
      "context": "...the whole segment on rebranding...",
      "timing": 1843,
      "language": "en",
      "url_with_timing": "https://allears.ai/...#t=1843",
      "reach_at_creation": 18400,
      "pr_value": 2100,
      "created": "2026-05-12T09:14:03",
      "episode": {"uuid": "e7b1...", "title": "Rebranding in 2026",
                  "published_date": "2026-05-12T06:00:00"},
      "channel": {"uuid": "c0a4...", "name": "Marketing Today", "channel_type": "podcast"}
    }
  ],
  "next_cursor": "eyJ0cyI6...",
  "has_more": true
}
```

- **A good answer:** the matched `text` with its `channel` / `episode` context
  and a link (`url_with_timing`). Use `include_related: false` to drop the
  `episode` / `channel` / `transcript` sub-objects (and `pr_value`) for a
  smaller payload.
- **Paging:** omit `after` on the first call. Take `next_cursor` from the
  response and pass it as the `after` argument of the next call; stop when
  `has_more` is false. `next_cursor` is a response field, not an argument —
  the tool has no `next_cursor` or `cursor` parameter. For the example above
  the second page is:

```json
{
  "tool": "monitor_get_mentions",
  "arguments": {
    "uuid": "8f3c0a21-...-e21",
    "after": "eyJ0cyI6...",
    "page_size": 50,
    "include_related": true,
    "date_filter_field": "published_date",
    "start_date": "2026-05-10",
    "end_date": "2026-05-17"
  }
}
```

- **Streaming a monitor incrementally:** leave `date_filter_field` at its
  default (`"created"`, the detection date), set `start_date` to your last
  watermark (leave `end_date` unset → now), page with `after` as above until
  `has_more` is false, then store the newest row's `created` as the next
  watermark. This reliably picks up everything ingested since your last run,
  regardless of when the content was originally published.
- **Limitations:** `pr_value` is `null` when unavailable for your plan / market.
  Rows carry reach and PR value but **not** a per-mention sentiment label — for
  that, use the page-based `get_mentions`, or aggregate with
  `monitor_sentiment_distribution`.
- **Won't tell you:** a summary or explanation — the tool returns the passages;
  reading them is the agent's job.

---

## Compare several monitors at once {#compare-several-monitors}

- **Question:** Same metric across N saved monitors (e.g. us vs 5 competitors).
- **Who:** Analyst benchmarking saved trackers.
- **Tool:** any `monitor_*` analytics operator except `monitor_get_mentions`,
  with a comma-separated UUID list (max 20). The response switches to a
  `results` list, one row per monitor.

**Example call**

```json
{
  "tool": "monitor_episode_count",
  "arguments": {
    "uuid": "8f3c0a21-...-e21,a0127f3b-...-77b,c4d90011-...-100",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}
```

**Example response**

```json
{
  "operator": "episode_count",
  "mode": "monitor",
  "results": [
    {"monitor_uuid": "8f3c0a21-...-e21", "episode_count": 412, "mention_count": 988,
     "start_date": "2026-05-01T00:00:00", "end_date": "2026-05-31T00:00:00"},
    {"monitor_uuid": "a0127f3b-...-77b", "episode_count": 220, "mention_count": 471,
     "start_date": "2026-05-01T00:00:00", "end_date": "2026-05-31T00:00:00"}
  ]
}
```

- **A good answer:** one row per monitor, same window, ready to rank.
- **Limitations:** capped at 20 monitors per call. With a single UUID the
  per-monitor fields are returned flattened at the top level instead of inside
  `results`. Each monitor must already exist — to compare topics nobody tracks
  yet, create the monitors first and wait for the backfill (`get_monitor`'s
  `backfill_in_progress` turns false when it's done).
- **Won't tell you:** a cross-monitor *share* — divide the rows client-side if
  you need "us vs the market".
