--- 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`), engagement the platform reported (`minLikes`, `minReposts`, `minReplies`, `minQuotes`, `minViews`, `minBookmarks`; a post without the count never passes), review stars (`ratings`, `notRatings`), author tags (`tags`, any of), the hosts a post links to (`linkHosts`, any of, a host or any subdomain of it), Reddit subreddits (`subreddits`, `notSubreddits`), posts, comments or GitHub repository events (`kind`), replies against top-level posts (`isReply`), languages (`languages`, `notLanguages`), where the author is (`countries`, `notCountries`, lowercase ISO 3166-1 alpha-2 codes; an unknown country passes `notCountries`), companies against people (`organization`), 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`. A cross-post (the same author posting the same text again within three days) is listed once, with the copies in `duplicates`; `includeDuplicates: true` lists them separately. 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. | | `list_mention_comments` | read | The comments under a mention's post, newest first, for keywords with comments on: author, text, time, a light sentiment and intent read, and `mentionId` when a comment names one of your keywords. | | `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, this month, your verdicts), poll health, matching rules, context, and its mention cap (`per` day, week or month, `used` this period, `resumesAt`) with `pausedForCap` when it is at it. | | `get_keyword_health` | read | Is a keyword worth what it costs, and what would fix it, over `range` (7d, 30d by default, 90d): a status (healthy, noisy, quiet, capped, paused, new) with reasons, numbers by platform and week, cost, the words and authors its noise is made of, and suggestions whose `patch` goes to `update_keyword` as is, each with the effect it would have had. `ai: true` adds a context rewritten by a language model. See [Keyword health](/guides/keyword-health). | | `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`, `exactPhrase`, `subreddits` for Reddit, `repositories` for which GitHub repository events it takes): a post the rules reject is never stored or billed. `context` is one sentence the classifier reads for this keyword only. `cap` (`{ mentions: N, per }` with `per` one of `day`, `week` or `month`, month by default) is a ceiling on its matched mentions per UTC day, week (from Monday) or month: at the cap it stops matching until the next period starts or until the cap is raised, while its daily keyword charge continues. A daily cap keeps mentions coming every day with a fixed ceiling on spend. `comments` (`{ enabled, maxPerPost }`, off by default) reads the thread under each relevant mention, $0.008 a comment. `display` (`{ languages: { only, excluded }, countries: { only, excluded } }`) hides its mentions in other languages or from other countries: still matched and billed, kept out of search, exports, alerts and digests; a post nobody could place is always shown. 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`, its `matching` rules (each field optional, an empty list clears one), or its mention `cap` (`{ mentions, per }`; `null` removes it; a cap above the current period's count resumes a capped keyword at once), or its `comments` (`enabled`, `maxPerPost`), or which languages and countries it shows (`display`, each list replaced when sent, applied to older mentions too). 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. | | `get_usage_breakdown` | read | What the workspace consumed and was charged over a window (`range` 7d/30d/90d, or a calendar `month`), grouped `by` keyword, platform or day, in USD cents, with the window's totals; paged. Where "what did keyword X cost" is answered. | | `list_ledger` | read | Every movement of the prepaid balance, newest first: the welcome credit, top-ups, refunds, the daily keyword-day and mention debits, adjustments. A debit row carries the UTC day it settled and the cumulative units behind it. Cursor paged (`limit` up to 100). Adding funds is a checkout on the billing page or `POST /v1/billing/top-ups` on the REST API. | | `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, language or subreddit (Reddit only). 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 an hourly, 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; `hourly` sends one digest every UTC hour, five minutes past (no schedule, no email channel, nothing for an empty hour); `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, countries (`countries`, `notCountries`), companies (`organization`), 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 Every tool in this section and the next takes an optional `groupId`: the same call inside one keyword group, over the people who mentioned that group's keywords, with the group's own tags, notes, merges, activities and segments. Without it the call covers the whole workspace. See [People and segments by group](/guides/groups#people-and-segments-by-group). | 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`), one person by an account (`handle`: a handle such as `@jane`, or a profile or post link; exact, add `platform` to pick one), 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, linked accounts) where the platform lists it. The person's email address is never returned over MCP: `profile.email` is always `null`. | | `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. With `groupId` the mute is that keyword group's own: it hides them from the mentions of that group's keywords only. | | `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. | | `list_views` | read | Saved views (named filters over mentions such as "Negative about us" or "Needs a reply"). Pass a view id as `viewId` to `search_mentions` to read exactly what it selects. | | `create_view` | write | Save a view: a name plus a filter in the vocabulary of `search_mentions` (keywords or keyword kinds, platforms, status, relevant, sentiments, intents, languages, author countries, author tags, follower range, replies, posts, comments or GitHub repository events (`kind`), link hosts, automated, organization, free text). Lists any-of, `not` lists none-of, every condition ANDed. Nothing is materialized. | | `update_view` | write | Rename, describe or refilter a saved view. The filter replaces the whole filter. | | `delete_view` | write | Delete a saved view. No mention is affected. |