--- title: "Tools" description: "Every tool the MCP server exposes, by area." canonical: https://docs.mentio.dev/mcp/tools markdown: https://docs.mentio.dev/mcp/tools.mdx --- # Tools Every tool the MCP server exposes, by area. Each tool maps to one operation of the REST API and takes the same inputs, validated with the same schemas. Responses are the same JSON shapes the API returns (see [Conventions](/conventions)), so an agent that has read the API reference already knows what comes back. A `read` API key lists the read tools only; calling a write tool with one fails with `read_only_key`. ## Mentions | Tool | Scope | What it does | | ------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_mentions` | read | Search tracked mentions. Filter by keyword, platform, status (`open`, `ignored`, `done`), relevant, minimum relevance, sentiment, intent, free text (`q`, the text or the author's name), time range, one person (`personId`), assignee (`assigneeId`), author reach (`minFollowers`, `maxFollowers`), author tags (`tags`, any of), the hosts a post links to (`linkHosts`, any of, a host or any subdomain of it), replies against top-level posts (`isReply`), languages (`languages`, `notLanguages`), whether the post reads as machine-made (`automated`), or an alert rule's whole filter (`alertId`). Snoozed mentions are hidden unless `snoozed` is true. Sort by `newest` (default) or `priority`, which ranks the last 30 days of matches. Returns 10 mentions by default (`limit`, up to 100). Each mention nests `post`, `author`, `classification` and `triage`. Returns `{ data, hasMore }`: there is no cursor, an agent narrows the filters instead of paging. | | `get_mention` | read | Fetch one mention by id, including its classification (relevance, sentiment, intents, automated, language, note) and any verdict you gave on it. | | `update_mention` | write | Work a mention like an inbox item: set its status (`ignored`, `done`, or back to `open`), assign it to a workspace member (`assigneeId`), snooze it until an instant (`snoozedUntil`), or leave an internal note (`note`). Or overrule the classifier: `relevant` true or false (relevance becomes 100 or 0 and every list, digest and report follows), `sentiment` to correct the label; `null` withdraws a verdict. Omitted fields are untouched; `null` clears. Ignored and done mentions are excluded from delivery. | | `get_mention_stats` | read | Mention counts for the last N days (default 7), grouped by platform and by sentiment, optionally filtered to one platform or keyword. | ## Keywords | Tool | Scope | What it does | | ---------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_keywords` | read | Every tracked keyword, newest first, with its stats, poll health, matching rules and context. | | `get_keyword` | read | One keyword by id, with its stats (matches, relevant, last 7 days, your verdicts), poll health, matching rules and context. | | `add_keyword` | write | Start tracking a keyword. `kind` is `brand` (default), `competitor` or `topic`; `platforms` optionally restricts it to some platforms. For a common word, `matching` narrows it (`requiredTerms` with `requiredMode` any or all, `excludedTerms` with a `*` wildcard at an end, `excludedAuthors`, `caseSensitive`): a post the rules reject is never stored or billed. `context` is one sentence the classifier reads for this keyword only. New mentions containing the term are matched, classified and delivered. | | `update_keyword` | write | Change which platforms a keyword is tracked on (`platforms`: a list, or `null` for every platform), mute it, reclassify it (`kind`), set its classifier `context`, or its `matching` rules (each field optional, an empty list clears one). Rules apply to new mentions only. Returns the updated keyword with its stats. | | `delete_keyword` | write | Stop tracking a keyword and delete its mentions. Alert rules that named it stop naming it; a rule that named only this keyword is disabled rather than widened. | | `get_filters` | read | The workspace filters: noise rules applied to every keyword before a mention is stored (excluded terms and authors, excluded GitHub repositories, subreddit allow and deny lists). | | `update_filters` | write | Change the workspace filters. Each list optional; an omitted list is untouched, an empty one clears it. Takes effect on new mentions within a minute. | ## Company | Tool | Scope | What it does | | ---------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_company` | read | Read what the classifier knows about the company: name, description, use cases, competitors, guidelines, website, own accounts, and the composed `context` it reads to judge relevance. | | `update_company` | write | Update the profile (`name`, `description`, `useCases`, `competitors`, `guidelines`, `website`, `accounts`) or set `context` directly. Profile edits recompose the context; an explicit context wins until the next profile edit. It is the single biggest lever on relevance scoring, so keep it accurate and specific. Omitted fields are untouched. | ## Workspace | Tool | Scope | What it does | | -------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `whoami` | read | The workspace this credential acts on, how it authenticated (an API key or an OAuth sign-in), whether it may write, and the person behind it when there is one. | | `get_usage` | read | The prepaid balance (ledger, pending mention charges, effective), the daily burn and the days it buys, the keywords running and paused, the matches recorded today and over 30 days, and whether tracking is stopped or the balance is low. | | `list_members` | read | The people in the workspace with their role, email and user id (what `assigneeId` and `ownerId` take). | ## Analytics Four reports over one window: `range` (`7d`, `30d`, `90d`, `365d`) or `from`/`to`, `keywordIds`, `platforms`, `timezone` (IANA, UTC by default) and `compare` for the period right before. | Tool | Scope | What it does | | ------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_analytics_summary` | read | Headline counts: matched and relevant, distinct posts and people, sentiment split, buying intent and questions, estimated reach, and triage (open, ignored, done, waiting, handled rate, median time to done). `previous` when comparing. | | `get_analytics_series` | read | Mentions over time, one point per hour, day, week or month (`bucket`) with matched, relevant and sentiment counts. One total series, or split with `by` into platforms, keywords (top 20, the rest as "other") or sentiments. The previous period aligned by index when comparing. | | `get_analytics_breakdown` | read | One table grouped by `by`: platform, keyword, sentiment, intent, status, hour (weekday and hour of day), person or language. Each row has matched, relevant, its share of the window and a sentiment split. | | `get_share_of_voice` | read | Brand against competitors: every keyword matched in the window with its counts and its share of brand plus competitor matches; topics are counted but stay out of the split. | ## Alerts | Tool | Scope | What it does | | --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_alerts` | read | Every alert rule: what it watches (filter), whether it fires instantly or as a daily or weekly digest, and which channels it sends to. | | `get_alert` | read | One alert rule by id: its filter, mode and schedule, channels and delivery stats. | | `create_alert` | write | Create a rule. `instant` sends each matching mention as it happens; `daily` sends one digest at `schedule.hour` in `schedule.timezone`; `weekly` one a week on `schedule.weekday`. The filter narrows by keywords, platforms, minimum relevance, sentiments, intents, languages, excluded authors, minimum followers, author tags, bots (`automated`) or the hosts a post links to (`linkHosts`). `event` names the payload for webhooks. `channelIds` come from `list_channels`. | | `update_alert` | write | Change a rule: name, enabled, mode, schedule, filter (replaces the whole filter), event or channels (replaces the whole list). | | `delete_alert` | write | Delete a rule. Its channels stay and can serve other rules. | | `list_channels` | read | The channels alerts can send to: Slack channels, Telegram chats, email lists and webhooks. | Alerts and channels are explained in [Alerts](/alerts); the webhook payloads in [Webhooks](/webhooks). ## People | Tool | Scope | What it does | | ----------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_people` | read | The people who wrote matching mentions: name, profile, platform, how many posts matched and how many scored relevant, sentiment split, first and last seen, and where your outreach stands (owner, stage, last contacted). Filter by platform(s), name or handle (`q`), tag(s), muted, first seen since an instant, follower range, minimum mentions or negatives, intents seen, keyword kinds mentioned or never mentioned, first seen within N days, the hosts they have linked to (`linkHosts`), outreach `stages`, owner (`ownerIds`, `none` for nobody), `automated` (bot accounts, whose matched posts are mostly machine-made), or a saved segment (`segmentId`). Sort by `mentions`, `recent`, `reach` or `new`; page with `offset`. | | `get_person` | read | One person with their counts, tags, notes, mute and outreach for your workspace, plus their public profile (bio, company, location, website, email, linked accounts) where the platform lists it. | | `update_person` | write | Annotate a person: replace their tags, set notes, mute and unmute them, or set the outreach owner (`ownerId`, a member user id; `null` clears) and `stage` (`not_contacted`, `contacted`, `replied`, `in_talks`, `customer`, `not_a_fit`). Muting hides their posts from the feed and from every channel; ingest and billing are unchanged. | | `merge_people` | write | Declare that two accounts are the same person, for your workspace only: fold account `id` into person `into`. Their mentions, tags, notes and outreach activities combine; the person keeps its owner and stage unless it had none. | | `split_person` | write | Undo a merge: the account becomes its own person again. | | `list_activities` | read | The outreach log on one person, newest first: who reached out, the channel (`email`, `x`, `linkedin`, `bluesky`, `reddit`, `github`, `call`, `meeting`, `other`), when, and a short note. Check it before reaching out so two teammates never contact the same person without knowing. | | `log_activity` | write | Record that someone reached out to a person. The first contact claims an unowned person for whoever reached out and moves `not_contacted` to `contacted`; an existing owner and a later stage are kept. `memberId` defaults to the signed-in user; an API key without it logs an unattributed activity. | | `delete_activity` | write | Delete an activity logged by mistake. The owner and the stage stay as they are. | ## Segments | Tool | Scope | What it does | | ---------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_segments` | read | Saved segments (named audience filters such as "Influencers" or "Switch prospects"), each with its current size, plus presets you can save. Pass a segment id to `list_people` to see its members. | | `create_segment` | write | Save a segment: a name plus a filter over platforms, tags, follower range, minimum mentions or negatives, intents seen, keyword kinds mentioned or never mentioned, first seen within N days, the hosts they have shared a link to. Evaluated on every read, never materialized. | | `update_segment` | write | Rename, describe or refilter a saved segment. The filter replaces the whole filter. | | `delete_segment` | write | Delete a saved segment. Nobody in it is affected. |