# MCP concepts: listeners, mentions, Fit Score (https://snitchfeed.com/docs/mcp/concepts)

These are the terms the SnitchFeed MCP tools use in their parameters and results. The same explanation is available to your AI client through the `snitchfeed_get_concepts` tool.

## Listener [#listener]

A **listener** is the top-level monitoring unit. It groups keyword queries, tracked LinkedIn or X profiles, or both, under one topic, with a name, a color and an intent signal that tunes AI scoring.

Examples: "Brand mentions", "Competitor: Acme", "Pain points in our category".

| Field | Description |
|-------|-------------|
| `name` | Display label shown in the dashboard and returned by tools |
| `status` | `active` (running) or `paused` (no new mentions collected) |
| `color` | Color for visual organization. Assigned at random when omitted |
| `intent` | The intent signal: a plain-language description of the ideal post or person. **Required**, 200 to 500 characters. Drives the Fit Score |
| `negative_intent` | Noisy signals: what irrelevant posts look like. Optional, up to 500 characters. Pushes Fit Scores down for noise |
| `linkedin_interval`, `twitter_interval`, `hackernews_interval`, `reddit_interval` | Scan interval in minutes for that platform: 60, 120, 240, 360, 720 or 1440. Defaults: LinkedIn 720 (12 hours), X 240 (4 hours), Hacker News 360 (6 hours), Reddit 720 (12 hours). Bluesky has no scan interval |
| `included_subreddits` | Reddit: only scan these subreddits. Names are not case sensitive. Each adds 2 credits per scan, once for the whole listener. Applies to every Reddit query on the listener |
| `excluded_subreddits` | Reddit: skip these subreddits. Names are not case sensitive. Applies to every Reddit query on the listener |
| `reddit_search_posts` | Reddit: include posts (default true). Applies to every Reddit query on the listener |
| `reddit_search_comments` | Reddit: include comments. Reddit comment scans are currently off, so listeners scan posts only and this setting has no effect for now |
| `included_users` | Only include posts and comments from these authors. Applies to every query on the listener. Exact match; case-insensitive except Reddit usernames |
| `excluded_users` | Exclude posts and comments from these authors. Applies to every query on the listener. Exact match; case-insensitive except Reddit usernames |

A listener must always have at least one source: an active keyword query, a tracked profile, or both. To remove the last source, delete the listener.

Each scan of a keyword uses credits (2 for X, 4 for LinkedIn, 2 for Hacker News, and 2 for Reddit, which scans posts only, plus 2 per included subreddit per scan, once for the whole listener), so shorter intervals mean fresher mentions and proportionally more credits. See [scan intervals](/docs/listeners/scan-intervals) and [credits](/docs/credits).

## Query (listener query) [#query-listener-query]

A **query** is a keyword rule inside a listener. One listener can hold several queries, so you can watch keyword variations or platform-specific rules under the same topic. Each query belongs to exactly one listener.

| Field | Description |
|-------|-------------|
| `query_text` | Boolean keyword expression. See [query grammar](#query-grammar) |
| `platforms` | Platforms this query runs on: `reddit`, `twitter`, `linkedin`, `bluesky`, `hackernews`. Omit for all |
| `whole_word` | Match whole words only (default false) |
| `case_sensitive` | Case-sensitive matching (default false) |
| `linkedin_author_job_title` | LinkedIn: filter by author job title. Comma-separated titles run one search per title (max 3), and each title is billed on every scan |
| `linkedin_author_company` | LinkedIn: filter by author company |
| `linkedin_author_industry` | LinkedIn: industry IDs to filter by author industry (max 5) |
| `linkedin_post_type` | LinkedIn: `any`, `person`, or `company` |
| `twitter_minimum_likes` | X: only include posts with at least this many likes |
| `twitter_lang` | X: language filter as an ISO 639-1 code (default English) |
| `hackernews_min_points` | Hacker News: only include stories with at least this many points |

## Tracked profile (tracked author) [#tracked-profile-tracked-author]

A **tracked profile** is a specific LinkedIn or X account, a person or a company page, that a listener follows directly. SnitchFeed ingests what that account posts without needing a keyword match. MCP tools call these **tracked authors** in their parameters. Use them for a known account (a competitor page, an analyst, a founder) rather than a topic.

Tracked profiles can sit on a listener next to its queries, or alone on a profile-only listener:

1. Resolve the profile URL with `snitchfeed_resolve_tracked_author_profile`.
2. Confirm the resolved account with the user.
3. Pass the tool output unchanged into `snitchfeed_create_listener` or `snitchfeed_update_listener` as `tracked_authors`.

To stop following an account, pass its `platform` and `profile_url` (from `snitchfeed_list_listeners`) in `remove_tracked_authors`. Tracked authors are never referenced by an internal ID.

Product walkthrough: [Track LinkedIn and X profiles](/docs/listeners/tracked-profiles).

## Query grammar [#query-grammar]

Query text uses a boolean expression language:

| Operator | Example | Meaning |
|----------|---------|---------|
| `AND` | `pricing AND saas` | Both terms must match |
| `OR` | `SnitchFeed OR snitchfeed.com` | Either term must match |
| `NOT` | `saas NOT enterprise` | Excludes matches |
| Parentheses | `(saas OR b2b) AND churn` | Grouping |

- Bare words match case-insensitively: `react`
- Quoted strings match exactly: `"React Native"`
- Each query needs at least one positive (non-NOT) term
- LinkedIn queries cannot use `{ }` brace expansion, `*` wildcards, `+` as AND, or `-` as NOT

The `snitchfeed_get_query_grammar` tool returns the full reference, including term limits. The product guide is [Boolean search queries](/docs/listeners/boolean-search).

## Mention [#mention]

A **mention** is a post or comment that matched one of your active listener queries, or that a [tracked profile](#tracked-profile-tracked-author) on the listener published.

Each mention returned by `snitchfeed_list_mentions` includes:

- **platform**: where it was found (`reddit`, `twitter`, `linkedin`, `bluesky`, `hackernews`)
- **datePublished**: when the post was published on the platform
- **content**: a normalized object with `url`, `text`, `author`, `authorUrl`, `title`, `subreddit`, `parentPost` (Reddit comments) and engagement metrics
- **matched keywords**: the query terms that triggered the match
- **AI analysis**: `aiSentiment`, `aiFitScore`, `aiIntentTags`, `aiLanguage`, `aiIntentSummary`
- **snitchfeed_url**: a link that opens the mention in SnitchFeed

### Mention state [#mention-state]

Each mention has a state shared by everyone in the workspace:

| State | Meaning |
|-------|---------|
| Seen | Someone in the workspace has seen it, like read and unread in an inbox |
| Engaged | Someone acted on it, for example generated a reply, or an API caller marked it engaged. Engaging also marks it seen |
| Archived | Removed from the feed |

`snitchfeed_list_mentions` returns unarchived mentions only and can filter on seen or unseen. The [REST API](/docs/api/introduction) can also filter on engaged and set seen and engaged.

## Fit Score [#fit-score]

**Fit Score** is an AI-assigned relevance score that reflects how closely a mention matches the listener's intent signal. MCP tools return it as a number from 0 to 1 and filter on three buckets:

| Bucket | Score range |
|--------|-------------|
| `high` | 0.7 and above |
| `medium` | 0.5 to below 0.7 |
| `low` | Below 0.5 |

The listener's `intent` and `negative_intent` calibrate it. A specific intent signal, such as "SaaS founders evaluating social listening tools for their GTM stack", produces more useful scores than a vague one. For what drives the score and how to tune it, see [How Fit Score, intent tags and sentiment work](/docs/fit-score).

## Intent tags [#intent-tags]

**Intent tags** are AI labels on each mention that describe its commercial or contextual signal. A mention can carry several. Tools accept them as filters (`include_intents`, `exclude_intents`) and analytics can break results down by them.

The 13 slugs are `buying_intent`, `recommendation_request`, `comparison`, `seeking_alternative`, `content_opportunity`, `pain_point`, `competitor_complaint`, `competitor_mention`, `feature_request`, `praise`, `hiring`, `brand_mention` and `promotional`. What each one means is on the [Fit Score page](/docs/fit-score).

Intent tags are different from the listener's **intent signal** (the `intent` field), which describes what you want to find.

## Sentiment [#sentiment]

**Sentiment** is the AI-detected tone of a mention: `positive` (score 0.6 and above), `neutral` (0.4 to below 0.6) or `negative` (below 0.4). It reflects tone, not relevance: a high-fit mention can be negative (a competitor complaint) or positive (praise for your product).

## Platform [#platform]

SnitchFeed monitors five platforms:

| Platform | What is monitored |
|----------|-------------------|
| `reddit` | Posts across public subreddits |
| `twitter` | Public posts on X (Twitter) |
| `linkedin` | Public LinkedIn posts |
| `bluesky` | Public Bluesky posts |
| `hackernews` | Hacker News stories and comments |

Each query can run on any combination of platforms. Platform-specific filters (subreddit lists, LinkedIn author filters, X minimum likes, Hacker News minimum points) apply only to their platform.

## Analytics [#analytics]

**Analytics** are aggregated metrics over your mentions. A query has:

- **Metric**: `mentions` (count), `unique_authors`, `avg_sentiment` or `avg_fit_score`
- **Group by**: `day`, `platform`, `sentiment`, `fitScore`, `keyword`, `subreddit`, `language` or `listener`. Defaults to `day`
- **Breakdown** (optional second axis, must differ from group by): `platform`, `sentiment`, `fitScore`, `language`, `listener` or `intent`. Intent tags are available as a breakdown only, not as a group by
- **Filters**: date range (default past 14 days), platforms, sentiment, Fit Score bucket, listeners, intent tags, keywords, subreddits, languages, seen status

Analytics answer questions like "How many high-fit mentions did we get last month?" or "Which platform brings the most buying intent mentions?" (group by platform, filter on `buying_intent`).

## Analytics report [#analytics-report]

An **analytics report** is a saved, named analytics query that appears in the SnitchFeed dashboard. It runs when created and caches its results for 15 minutes, refreshing after that. Use `snitchfeed_list_analytics_reports` to find existing reports by ID.

## Integrations [#integrations]

Workspace integrations live under **Integrations** in the dashboard:

| Integration | App path | What it does |
|-------------|----------|--------------|
| Slack | `/integrations/slack` | Connect the Slack workspace with OAuth. Each feed then picks its channels in its notification settings. If a private channel is missing, reconnect Slack and invite SnitchFeed to that channel |
| Webhooks | `/integrations/webhooks` | HTTPS endpoints that receive new mentions. You can also manage them with the [webhook tools](/docs/mcp/tools#webhooks) |
| MCP | `/integrations/mcp` | Connected AI clients and MCP request logs |
| API | `/integrations/api` | API keys and API request history for the REST API |

Slack connection, MCP clients and API keys are managed in the dashboard, not through MCP tools.

## Related [#related]

- [MCP tools reference](/docs/mcp/tools): the tools that use these concepts
- [How Fit Score, intent tags and sentiment work](/docs/fit-score): full tag and scoring reference
- [What is a listener?](/docs/listeners/create#what-is-a-listener): listeners from the product side
- [MCP use cases](/docs/mcp/use-cases): prompts that put these concepts to work
