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 guide; setup lives on the connection guide.

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

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

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?

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 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?

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

  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?

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?

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

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