# All Ears MCP — semantics & caveats

The agent-readable entry point for the All Ears MCP tools: load it once to
understand what the tools are, what the numbers actually mean, and what you may
not claim. The concrete example use cases live in the
[Monitors](https://mcp.allears.ai/docs/monitors) guide; setup lives on the
[connection guide](https://mcp.allears.ai/docs).

> Example numbers in these docs are illustrative. The tool **names**, their
> **arguments**, and the **response shape** are the contract; the specific
> counts and dates are not.

## Contents

- [Products & entitlements](#products)
- [What is a monitor?](#monitors)
- [What is a medium (audio vs text)?](#medium)
- [What do the answers actually mean?](#limits)
- [A typical workflow](#workflow)
- [Can I use this for finance?](#finance)
- [What's not available yet?](#not-yet)
- [Glossary: key terms](#glossary)

## Products & entitlements {#products}

All Ears exposes its MCP tools in two tiers. Both are available to every
organization. A tool returns a clear permission error if your token lacks the
required scope — it does not silently return empty data.

| Tier (scope) | What it is | Tools | Read |
|---|---|---|---|
| **Monitors — manage & read** (`monitor:read`, `monitor:write` to change) | Create/manage saved queries and read their enriched mention feed and daily metrics. | `list_monitors`, `get_monitor`, `create_monitor`, `update_monitor`, `archive_monitor`, `get_mentions`, `get_metrics` | [Monitor use cases](https://mcp.allears.ai/docs/monitors) |
| **Monitors — analytics** (`monitor:read`) | Aggregations over a saved monitor: volume, unique channels, trend, spikes, growth, top sources/terms, share of voice, and sentiment. | `monitor_*` | [Monitor use cases](https://mcp.allears.ai/docs/monitors) |

Two orientation tools are available to every authenticated connection:
`get_documentation` (these docs, filtered to your entitlements) and
`list_organizations` (the organizations you can act on, with their entitled
sources and languages).

## What is a monitor? {#monitors}

A **monitor** is a saved query — keywords, sources (media types) and languages —
whose matching mentions are continuously collected and *enriched* with
sentiment, reach and PR value. Everything the tools measure is measured over a
monitor's collected mentions:

- Creating one (`create_monitor`) starts a background backfill. Historical
  mentions and sentiment fill in over minutes to hours. `get_monitor` /
  `create_monitor` / `update_monitor` return `backfill_in_progress`: true
  while historical mentions are still being collected, false once that pass
  finishes. Sentiment scoring is separate — it can still be
  `unknown` after `backfill_in_progress` turns false.
- A keyword the monitor doesn't track is invisible to every tool. If the user
  asks about something no monitor covers, the answer is to create or edit a
  monitor, not to guess.
- Every analytic accepts the same filters as the dashboard: `channel_type`,
  `channel_name`, `medium`, `language`, `sentiment`, `min_reach`, `freetext`,
  `insight_types` (`positive_impact`, `negative_impact`, `toplist_mentions`;
  empty when the organization has no tagged insights),
  plus a `start_date` / `end_date` window.

## What is a medium (audio vs text)? {#medium}

`medium` is an optional filter on every monitor analytics tool:

- **`audio`** — **transcribed speech**: what people *say* in podcast, video,
  and broadcast (radio / TV) transcripts.
- **`text`** — **written content**: episode titles & descriptions, online news
  articles, and social posts.
- **`all`** (default) — both. A monitor's totals already cover both media; you
  only pass `medium` to narrow, never to complete a count.

## What do the answers actually mean? {#limits}

These are properties of the numbers the tools return.

1. **Episodes are not mentions.** `episode_count` is distinct content items;
   `mention_count` is passages inside them (one episode can yield many). Name
   the one you are quoting.
2. **No "which person."** The tools rank *channels* (shows, feeds, outlets),
   not individual creators, hosts or guests.
3. **Sentiment is per mention and may be incomplete.** `unknown` / `null`
   means "not scored yet", not "neutral". Report `scored` vs `total`.
4. **Share of voice is by channel type, for one monitor.** `monitor_distribution`
   splits a single monitor's volume across podcast / YouTube / TV / …; it is
   not a brand-vs-brand share. Compare monitors with the multi-UUID call and
   divide client-side.
5. **No generated answers.** The tools do not explain, summarise, or draft —
   they return counts, series, terms, sources, and raw matched passages.
6. **Historical depth is bounded.** A monitor only has data from its
   `start_date` onward, and the most recent bucket can be partial (ingest lag).
   Prefer recent windows.

## A typical workflow {#workflow}

1. **Find the monitor.** `list_monitors` returns pages of summaries. Match
   on `title` and keep the `id` (UUID). `get_monitor` returns the full
   query plus `backfill_in_progress`. A new monitor from `create_monitor`
   fills in over a background backfill; sentiment stays `unknown` until
   scoring finishes, which can outlast `backfill_in_progress`.
2. **Size it.** `monitor_episode_count` (volume) and `monitor_totals`
   (reach / PR value) for the window.
3. **Explain the shape.** `monitor_time_series` for the trend,
   `monitor_detect_peaks` for spikes, `monitor_growth_rate` for the
   period-over-period delta.
4. **Explain the who and the what.** `monitor_top_sources` (with
   `details: true` for episodes + sentiment per channel), `monitor_distribution`
   for channel-type split, `monitor_top_terms` for the conversation.
5. **Explain the tone.** `monitor_sentiment_distribution` for the overall
   split; `monitor_time_series` with `metric: "sentiment"` for tone over time.
6. **Show the evidence.** `monitor_get_mentions` (or `get_mentions`) for the
   actual passages behind any number you quote.

`monitor_top_sources` with `details: true` includes `episode_count` and
sentiment counts on each channel row.

---

## Can I use this for finance? {#finance}

This is a **media-monitoring** product. For finance users it is a coarse
attention proxy. It is not model-ready alternative data.

**What it *can* do for finance**

- **Attention / demand proxy:** volume, trend, spikes, and growth on a monitor
  tracking an entity's keywords (`monitor_episode_count`,
  `monitor_time_series`, `monitor_detect_peaks`, `monitor_growth_rate`) as a
  leading *attention* indicator.
- **Policy-attention tracking:** a monitor trend filtered to parliamentary
  channels (e.g. `channel_name` set to Riksdagen / Stortinget / Europarl) — a
  source set few competitors ingest.
- **Share-of-attention:** `monitor_distribution` splits a *single* monitor's
  volume across channel types. To compare *entities* against each other, run
  the volume call with several monitor UUIDs and compare client-side — there
  is no *cross-entity* normalized share-of-voice operator.

**What it does not provide**

- **No point-in-time guarantee.** There is no look-ahead-safe "as of" contract
  for backtests on this surface.
- **No entity→ticker resolution.** "Apple" / "AAPL" / "Tim Cook" are just
  keyword strings; disambiguation is the caller's problem.
- **No bulk / panel delivery.** There is no "500 entities × 5 years" dataframe
  export; multi-monitor compare caps at 20.
- **No creator grain** (the tools rank channels, not people).

In one line: point-in-time correctness, entity resolution, and bulk delivery
are not on this surface. The numbers are an attention signal.

---

## What's not available yet? {#not-yet}

These capabilities are not on this surface.

| Capability | Status |
|---|---|
| Ad-hoc keyword search without a saved monitor | Not on this surface — create a monitor |
| Who (which person) is talking | No creator-grain operator |
| Cross-entity normalized share of voice | Not built — `monitor_distribution` splits one monitor by channel type; compare monitors manually |
| Controversy / polarization | Not built |
| "What changed" in one call | No composition/diff operator |
| Air-time / depth / placement | Not built |
| Alerts (query → webhook) | Not built |
| Semantic search ("more like this") | Needs embedding enrichment |
| Topic / entity analytics | Needs topic/entity enrichment |
| Explain / summarise / draft a reply | No generated-text operators |
| Answer-mode (RAG with citations) | Not built |
| Finance panel / point-in-time / entity→ticker | Infrastructure, not an operator |

---

## Glossary: key terms {#glossary}

- **Monitor** — a saved query (keywords + sources + languages) whose matching
  mentions are continuously collected and enriched.
- **Episode vs mention** — Episode = a distinct content item (podcast episode,
  video, article, post). Mention = an enriched passage inside one.
- **Medium** — `audio` (transcribed speech) vs `text` (written content); a
  filter, default `all`.
- **Reach / PR value** — audience of the distinct matched episodes (counted
  once per episode) and the advertising-equivalent value derived from it.
  `pr_value` is `null` when unavailable.
- **Net sentiment** — mean sentiment of scored mentions, in the range −1…+1.
- **Significant terms** — terms over-represented in the matched material versus
  everyday language, not merely the most frequent terms.
- **Distribution / share of voice** — `monitor_distribution` splits one
  monitor's volume across channel types (`counts` plus `shares` that sum to
  ~1). Channel-type only; this is not a cross-entity (brand-vs-brand)
  share-of-voice.
