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
- What is a monitor?
- What is a medium (audio vs text)?
- What do the answers actually mean?
- A typical workflow
- Can I use this for finance?
- What's not available yet?
- Glossary: key terms
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_monitorreturnbackfill_in_progress: true while historical mentions are still being collected, false once that pass finishes. Sentiment scoring is separate — it can still beunknownafterbackfill_in_progressturns 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 astart_date/end_datewindow.
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 passmediumto narrow, never to complete a count.
What do the answers actually mean?
These are properties of the numbers the tools return.
- Episodes are not mentions.
episode_countis distinct content items;mention_countis passages inside them (one episode can yield many). Name the one you are quoting. - No "which person." The tools rank channels (shows, feeds, outlets), not individual creators, hosts or guests.
- Sentiment is per mention and may be incomplete.
unknown/nullmeans "not scored yet", not "neutral". Reportscoredvstotal. - Share of voice is by channel type, for one monitor.
monitor_distributionsplits 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. - No generated answers. The tools do not explain, summarise, or draft — they return counts, series, terms, sources, and raw matched passages.
- Historical depth is bounded. A monitor only has data from its
start_dateonward, and the most recent bucket can be partial (ingest lag). Prefer recent windows.
A typical workflow
- Find the monitor.
list_monitorsreturns pages of summaries. Match ontitleand keep theid(UUID).get_monitorreturns the full query plusbackfill_in_progress. A new monitor fromcreate_monitorfills in over a background backfill; sentiment staysunknownuntil scoring finishes, which can outlastbackfill_in_progress. - Size it.
monitor_episode_count(volume) andmonitor_totals(reach / PR value) for the window. - Explain the shape.
monitor_time_seriesfor the trend,monitor_detect_peaksfor spikes,monitor_growth_ratefor the period-over-period delta. - Explain the who and the what.
monitor_top_sources(withdetails: truefor episodes + sentiment per channel),monitor_distributionfor channel-type split,monitor_top_termsfor the conversation. - Explain the tone.
monitor_sentiment_distributionfor the overall split;monitor_time_serieswithmetric: "sentiment"for tone over time. - Show the evidence.
monitor_get_mentions(orget_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_nameset to Riksdagen / Stortinget / Europarl) — a source set few competitors ingest. - Share-of-attention:
monitor_distributionsplits 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) vstext(written content); a filter, defaultall. - Reach / PR value — audience of the distinct matched episodes (counted
once per episode) and the advertising-equivalent value derived from it.
pr_valueisnullwhen 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_distributionsplits one monitor's volume across channel types (countsplussharesthat sum to ~1). Channel-type only; this is not a cross-entity (brand-vs-brand) share-of-voice.