Skip to main content
Glama

List Your Mentions

list_mentions
Read-onlyIdempotent

Lists saved keyword mentions from Reddit, Hacker News, X, Bluesky, and Facebook with AI relevance scores, status filters, and pagination so you can find and triage leads.

Instructions

List the mentions RedReplier saved for the user's keywords: public posts on Reddit, Hacker News, X, Bluesky, and Facebook, each AI-scored 0-100 with its source, matched keyword, status, content, and any generated relevanceReason and aiReplySuggestion. Two defaults hide rows: REJECTED mentions are excluded unless statuses names them, and mentions below the website's minimum score (30 by default) are hidden unless includeLowRelevance is true, even when scoreBuckets asks for LOW or VERY_LOW. Mentions containing a word on the website's ignore list (ignoredKeywords, changed with update_website) never appear. Returns { mentions, total, limit, offset }; page with offset while offset < total. Sort RELEVANCE for the best leads, RECENT for what is new; from/to filter on ingestion time, not publish time. Reads mentions already saved in the account; it does not search or contact any network. Each mention is a public post with its text, URL and the author's public handle as shown on that network; private Facebook groups are never read. Use count_mentions for the number alone, explain_mention for one mention's reasoning, and update_mention_status to triage.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_mentions"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoOnly mentions RedReplier saved at or before this ISO 8601 datetime (ingestion time, not the post date). Omit for no upper bound
fromNoOnly mentions RedReplier saved at or after this ISO 8601 datetime (ingestion time, not the post date). Omit for no lower bound
sortNoOrder of the rows: RELEVANCE puts the highest score first, RECENT the newest first. Omit for RELEVANCE
limitNoPage size: how many mentions to return in this call
offsetNoHow many matching mentions to skip, for reading the next page: add limit to it after each call and stop once it reaches total. Omit to start at the first mention
sourcesNoWhich networks the conversations come from. Reddit splits into posts and comments, TWITTER is X, FACEBOOK is public pages and profiles, and FACEBOOK_GROUP is posts inside Facebook groups. Omit for every network
keywordsNoKeyword texts whose mentions to include: the value field of a keyword in list_websites or get_website, not its id. Each must match the whole keyword, ignoring case, so "crm" does not match "best crm". Omit for every keyword
minScoreNoRelevance score a mention needs to be included, e.g. 70 for strong leads only. Setting it also drops mentions that have no score yet. It adds to the website's own minimum score rather than replacing it, so pair it with includeLowRelevance to look below that. Omit for no extra cutoff
statusesNoWhich triage states to include. NEW means nobody has reviewed the mention yet, APPROVED means someone marked it a real lead, REJECTED means someone marked it noise. Omit to see new and approved mentions; rejected ones show only when you ask for them
websiteIdNoWebsite whose mentions to read, by its id from list_websites. Omit to cover every website in the workspace
workspaceIdNoWorkspace to act in: an id from list_workspaces. Omit to use the default workspace. Use the same workspaceId for every call about the same workspace, since ids from one workspace do not exist in another
scoreBucketsNoScore bands to include, combined with OR. Each band covers a range of the 0-100 relevance score: VERY_LOW under 10, LOW 10-29, MEDIUM 30-49, HIGH 50-74, VERY_HIGH 75 and up. Omit for every band. The two lowest bands return rows only with includeLowRelevance set
includeLowRelevanceNoAlso include mentions scoring below the website's minimum score (30 by default). Omit or false to hide them

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed23 schema fields changedv1.6.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • changedInput schema / properties / from / description
      Previous value: -"Only mentions ingested at/after this ISO 8601 datetime"New value: +"Only mentions RedReplier saved at or after this ISO 8601 datetime (ingestion time, not the post date). Omit for no lower bound"
    • changedInput schema / properties / includeLowRelevance / description
      Previous value: -"Include mentions below the website minimum score (30 by default), hidden otherwise"New value: +"Also include mentions scoring below the website's minimum score (30 by default). Omit or false to hide them"
    • changedInput schema / properties / keywords / description
      Previous value: -"Filter to mentions matched by these keyword values (case-insensitive exact match, as shown in list_websites)"New value: +"Keyword texts whose mentions to include: the value field of a keyword in list_websites or get_website, not its id. Each must match the whole keyword, ignoring case, so \"crm\" does not match \"best crm\". Omit for every keyword"
    • changedInput schema / properties / limit / description
      Previous value: -"Max results (1-500)"New value: +"Page size: how many mentions to return in this call"
    • addedInput schema / properties / minScore
      Added value: +{
      +  "description": "Relevance score a mention needs to be included, e.g. 70 for strong leads only. Setting it also drops mentions that have no score yet. It adds to the website's own minimum score rather than replacing it, so pair it with includeLowRelevance to look below that. Omit for no extra cutoff",
      +  "maximum": 100,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / offset / description
      Previous value: -"Pagination offset"New value: +"How many matching mentions to skip, for reading the next page: add limit to it after each call and stop once it reaches total. Omit to start at the first mention"
    • changedInput schema / properties / scoreBuckets / description
      Previous value: -"Relevance buckets, OR-combined: VERY_LOW (<10), LOW (10-29), MEDIUM (30-49), HIGH (50-74), VERY_HIGH (75+). LOW and VERY_LOW only show when includeLowRelevance is also true"New value: +"Score bands to include, combined with OR. Each band covers a range of the 0-100 relevance score: VERY_LOW under 10, LOW 10-29, MEDIUM 30-49, HIGH 50-74, VERY_HIGH 75 and up. Omit for every band. The two lowest bands return rows only with includeLowRelevance set"
    • changedInput schema / properties / sort / description
      Previous value: -"RELEVANCE (default, highest score first) or RECENT (newest first)"New value: +"Order of the rows: RELEVANCE puts the highest score first, RECENT the newest first. Omit for RELEVANCE"
    • changedInput schema / properties / sources / description
      Previous value: -"Filter by source: REDDIT_POST, REDDIT_COMMENT, TWITTER (X), BLUESKY, HACKERNEWS"New value: +"Which networks the conversations come from. Reddit splits into posts and comments, TWITTER is X, FACEBOOK is public pages and profiles, and FACEBOOK_GROUP is posts inside Facebook groups. Omit for every network"
    • changedInput schema / properties / sources / items / enum
      Previous value: -[
      -  "REDDIT_POST",
      -  "REDDIT_COMMENT",
      -  "TWITTER",
      -  "BLUESKY",
      -  "HACKERNEWS"
      -]New value: +[
      +  "REDDIT_POST",
      +  "REDDIT_COMMENT",
      +  "TWITTER",
      +  "BLUESKY",
      +  "HACKERNEWS",
      +  "FACEBOOK",
      +  "FACEBOOK_GROUP"
      +]
    • changedInput schema / properties / statuses / description
      Previous value: -"Filter by status (NEW, APPROVED, REJECTED); omit to get everything except REJECTED"New value: +"Which triage states to include. NEW means nobody has reviewed the mention yet, APPROVED means someone marked it a real lead, REJECTED means someone marked it noise. Omit to see new and approved mentions; rejected ones show only when you ask for them"
    • changedInput schema / properties / to / description
      Previous value: -"Only mentions ingested at/before this ISO 8601 datetime"New value: +"Only mentions RedReplier saved at or before this ISO 8601 datetime (ingestion time, not the post date). Omit for no upper bound"
    • changedInput schema / properties / websiteId / description
      Previous value: -"Filter to one website (UUID)"New value: +"Website whose mentions to read, by its id from list_websites. Omit to cover every website in the workspace"
    • addedInput schema / properties / websiteId / format
      Added value: +"uuid"
    • addedInput schema / properties / workspaceId
      Added value: +{
      +  "description": "Workspace to act in: an id from list_workspaces. Omit to use the default workspace. Use the same workspaceId for every call about the same workspace, since ids from one workspace do not exist in another",
      +  "type": "string"
      +}
    • removedOutput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedOutput schema / properties / result / additionalProperties
      Added value: +true
    • removedOutput schema / properties / result / description
      Removed value: -"{ mentions, total, limit, offset }: each mention has id, source, keyword, title, contentText, url, author, subreddit (Reddit only), status, relevanceScore, relevanceReason, aiReplySuggestion, tags, publishedAt, ingestedAt, reviewedAt."
    • addedOutput schema / properties / result / properties
      Added value: +{
      +  "limit": {
      +    "type": "integer"
      +  },
      +  "mentions": {
      +    "items": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "aiReplySuggestion": {
      +          "description": "Draft reply for a human to review before posting; null until generated",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "author": {
      +          "description": "Author's public handle on that network",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "contentText": {
      +          "description": "Text of the post or comment",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "createdAt": {
      +          "description": "Record creation time, ISO 8601",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "id": {
      +          "description": "Mention ID for update_mention_status and explain_mention",
      +          "type": "string"
      +        },
      +        "ingestedAt": {
      +          "description": "When RedReplier saved it, ISO 8601; the from and to filters use this",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "keyword": {
      +          "description": "The monitored keyword this conversation matched",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "publishedAt": {
      +          "description": "When the author posted it, ISO 8601; null when the network gives no date",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "relevanceReason": {
      +          "description": "Why the scorer chose that score; null until generated",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "relevanceScore": {
      +          "description": "AI score from 0 to 100, higher means more worth a reply; null until scored",
      +          "type": [
      +            "number",
      +            "null"
      +          ]
      +        },
      +        "reviewedAt": {
      +          "description": "When it was last set to APPROVED or REJECTED; null while NEW",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "source": {
      +          "description": "REDDIT_POST, REDDIT_COMMENT, TWITTER, BLUESKY, HACKERNEWS, FACEBOOK or FACEBOOK_GROUP",
      +          "type": "string"
      +        },
      +        "status": {
      +          "description": "Triage status: NEW, APPROVED or REJECTED",
      +          "type": "string"
      +        },
      +        "subreddit": {
      +          "description": "The subreddit on Reddit, the group id on FACEBOOK_GROUP, otherwise null",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "tags": {
      +          "description": "Tags the AI attached when explaining the mention",
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "title": {
      +          "description": "Post title; null when the post has none",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "updatedAt": {
      +          "description": "Record update time, ISO 8601",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "url": {
      +          "description": "Link to the conversation; null when the platform gives no public link",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "websiteId": {
      +          "description": "Website whose keyword matched",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "id",
      +        "websiteId",
      +        "source",
      +        "keyword",
      +        "title",
      +        "contentText",
      +        "url",
      +        "author",
      +        "subreddit",
      +        "status",
      +        "relevanceScore",
      +        "relevanceReason",
      +        "aiReplySuggestion",
      +        "tags",
      +        "publishedAt",
      +        "ingestedAt",
      +        "reviewedAt",
      +        "createdAt",
      +        "updatedAt"
      +      ],
      +      "type": "object"
      +    },
      +    "type": "array"
      +  },
      +  "offset": {
      +    "type": "integer"
      +  },
      +  "total": {
      +    "description": "Mentions matching the filters, before paging",
      +    "type": "integer"
      +  }
      +}
    • addedOutput schema / properties / result / required
      Added value: +[
      +  "mentions",
      +  "total",
      +  "limit",
      +  "offset"
      +]
    • addedOutput schema / properties / result / type
      Added value: +"object"
    • addedOutput schema / required
      Added value: +[
      +  "result"
      +]
  2. Changed5 schema fields changedv0.1.1
    • changedInput schema / properties / includeLowRelevance / description
      Previous value: -"Include mentions scoring below 30 (hidden by default)"New value: +"Include mentions below the website minimum score (30 by default), hidden otherwise"
    • changedInput schema / properties / keywords / description
      Previous value: -"Filter to mentions matched by these keywords"New value: +"Filter to mentions matched by these keyword values (case-insensitive exact match, as shown in list_websites)"
    • changedInput schema / properties / scoreBuckets / description
      Previous value: -"Relevance buckets: VERY_LOW (<10), LOW (10-29), MEDIUM (30-49), HIGH (50-74), VERY_HIGH (75+)"New value: +"Relevance buckets, OR-combined: VERY_LOW (<10), LOW (10-29), MEDIUM (30-49), HIGH (50-74), VERY_HIGH (75+). LOW and VERY_LOW only show when includeLowRelevance is also true"
    • changedInput schema / properties / statuses / description
      Previous value: -"Filter by status (NEW, APPROVED, REJECTED)"New value: +"Filter by status (NEW, APPROVED, REJECTED); omit to get everything except REJECTED"
    • changedOutput schema / properties / result / description
      Previous value: -"Array of mentions, each with its source, matched keyword, relevance score, status, and content."New value: +"{ mentions, total, limit, offset }: each mention has id, source, keyword, title, contentText, url, author, subreddit (Reddit only), status, relevanceScore, relevanceReason, aiReplySuggestion, tags, publishedAt, ingestedAt, reviewedAt."
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/openWorld annotations, it discloses concrete non-obvious behavior: REJECTED rows are hidden by default, sub-minimum scores are hidden even when scoreBuckets requests LOW, ignore-listed words never surface, and private Facebook groups are never read. It also confirms this reads saved data rather than contacting any network, which reinforces rather than contradicts the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then defaults, return shape, paging, and sibling routing, so an agent can stop reading early. It is dense and long, and the ingestion-time caveat is stated twice (once in prose, once implicitly via the schema), which is minor redundancy rather than waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter read tool this covers what matters: which rows are silently hidden, how paging terminates against total, what the response shape is, and where to go for counts, explanations, or triage. Nothing an agent needs to call it correctly is missing, and the output schema handles field-level detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3; the description earns above that by explaining cross-parameter interactions the schema documents only in isolation, notably that minScore stacks on top of the website minimum and must be paired with includeLowRelevance, and that includeLowRelevance overrides scoreBuckets. It adds less on the simple parameters, which the schema already covers fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("List the mentions RedReplier saved for the user's keywords") and enumerates the fields each row carries and the networks covered. It is unmistakably distinct from count_mentions, explain_mention, and update_mention_status, which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing guidance: count_mentions for the number alone, explain_mention for one mention's reasoning, update_mention_status to triage. It also states when to pick each sort order (RELEVANCE for best leads, RECENT for what is new) and clarifies that from/to filter on ingestion time, not publish time.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.