Skip to main content
Glama

Explain Mention and Draft Reply

explain_mention
Idempotent

Fetches a mention's AI relevance reasoning, tags, and drafted reply, generating missing fields once and caching them for instant reads. Use it to verify borderline scores before updating status.

Instructions

Get the AI relevance reasoning (relevanceReason), tags, and a drafted reply (aiReplySuggestion) for one mention, generating whatever is missing on first call and storing it, so later calls are instant reads. The website must have a description; without one the mention comes back unchanged. Use it when a score looks wrong or before update_mention_status on a borderline lead, not across every row of list_mentions, since generation is slow. Returns the full mention object. Returns 404 when the ID does not exist or belongs to another account.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "mentionId": "<mentionId>"
    },
    "name": "explain_mention"
  }
}

Input Schema

NameRequiredDescriptionDefault
mentionIdYesMention to explain, by its id from list_mentions
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

Output Schema

NameRequiredDescriptionDefault
resultYesThe mention with relevanceReason, tags and aiReplySuggestion filled in

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv1.6.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • changedInput schema / properties / mentionId / description
      Previous value: -"Mention ID (UUID) from list_mentions"New value: +"Mention to explain, by its id from list_mentions"
    • addedInput schema / properties / mentionId / 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
    • changedOutput schema / properties / result / description
      Previous value: -"The full mention with relevanceReason, tags, and aiReplySuggestion filled in; null when the mention is not found."New value: +"The mention with relevanceReason, tags and aiReplySuggestion filled in"
    • addedOutput schema / properties / result / properties
      Added value: +{
      +  "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"
      +  }
      +}
    • addedOutput schema / properties / result / required
      Added value: +[
      +  "id",
      +  "websiteId",
      +  "source",
      +  "keyword",
      +  "title",
      +  "contentText",
      +  "url",
      +  "author",
      +  "subreddit",
      +  "status",
      +  "relevanceScore",
      +  "relevanceReason",
      +  "aiReplySuggestion",
      +  "tags",
      +  "publishedAt",
      +  "ingestedAt",
      +  "reviewedAt",
      +  "createdAt",
      +  "updatedAt"
      +]
    • addedOutput schema / properties / result / type
      Added value: +"object"
    • addedOutput schema / required
      Added value: +[
      +  "result"
      +]
  2. Changed2 schema fields changedv0.1.1
    • changedInput schema / properties / mentionId / description
      Previous value: -"Mention ID (UUID)"New value: +"Mention ID (UUID) from list_mentions"
    • changedOutput schema / properties / result / description
      Previous value: -"The AI relevance reasoning and tags for the mention."New value: +"The full mention with relevanceReason, tags, and aiReplySuggestion filled in; null when the mention is not found."
  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?

Annotations declare readOnlyHint=false and idempotentHint=true, and the description explains exactly why: missing fields are generated on the first call and stored, so later calls are instant reads. It goes beyond the annotations with a cost warning (generation is slow), a silently-degraded path (no website description means an unchanged result), and a 404 failure mode for unknown or foreign-account IDs.

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?

The purpose is front-loaded and there is no filler, but the first sentence is long and packs generation, storage, and caching into one clause chain. The prerequisite, usage, cost, return, and error facts each earn their place.

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?

An output schema exists, so the description does not need to enumerate return fields, yet it still notes the full mention object is returned. Combined with the prerequisite, the slow-generation warning, and the 404 condition, nothing an agent needs to call this correctly is missing.

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 100%, so both parameters are already documented, and the description mostly restates them. It does add one piece of meaning not in the schema: that an ID belonging to another account yields a 404, which is a validity constraint an agent needs in order to interpret failures.

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?

The description names the exact outputs (relevanceReason, tags, aiReplySuggestion) for a single mention and states that missing pieces are generated and stored. That is a specific verb+resource that an agent can immediately distinguish from list_mentions (bulk listing) and update_mention_status (mutation) without opening a schema.

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?

It gives explicit when-to-use triggers ('when a score looks wrong', 'before update_mention_status on a borderline lead') and an explicit when-not ('not across every row of list_mentions, since generation is slow'). It also states a hard prerequisite: the website must have a description or the mention returns unchanged.

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