Nephia

List a keyword's mentions

get_keyword_results

The same mentions as list_mentions, scoped to one keyword and carrying the bucket each was sorted into. Use it for "what has my monitor caught?" and, with bucket=, for "show me the pricing complaints". Free in the default text mode — these are your own rows. mode="semantic" asks the embedding index and charges 1 credit per question, then answers the same question free for 10 minutes, paging included. Do not set it to filter by keyword: that is what q= in text mode already does, for nothing. Cursor-paged: pass nextCursor back unchanged.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	Search text, matched per mode= (default: free substring search)
`id`	Yes	Keyword id, from list_keywords. Another account's id is a 404, never a 403.
`mode`	No	How q= is matched. "text" (the default) scans the window for the substring and is free. "semantic" asks the embedding index — it finds "this thing keeps crashing" for q="reliability complaints" — and charges. Never set it to do a keyword filter.
`limit`	No	How many mentions to return, 1-100. Defaults to 25 here, a page a model can actually read. Never page to count: mentions_stats counts the whole window in one free call.
`since`	No	ISO 8601 instant. Only mentions after it; defaults to the last 24 hours.
`until`	No	ISO 8601 instant, inclusive. Only mentions before it. Use with since= to ask about a closed interval — a single day, or the week of a launch — instead of everything since a date. Absent means up to now.
`bucket`	No	A bucket id from list_keyword_buckets, or the literal "uncategorised", which is a real destination (nothing matched), not a missing value.
`cursor`	No	The previous response's nextCursor, passed back unchanged, for the next page. Its absence from a response means that was the last page.
`intent`	No	Only mentions read as one of these intents. Several are OR'd, so ["purchase_intent", "comparison"] is the leads view for this keyword. "unread" is what nothing has classified yet.
`source`	No	Only these Sources. Several are OR'd, so ["reddit", "hackernews"] is both in one call. Absent means every Source this keyword polls.
`sentiment`	No	Only mentions read as one of these sentiments. Several are OR'd, so ["negative", "question"] is "what needs an answer" for this keyword. "unread" is what nothing has classified yet.
`engagement`	No	A per-Source rule, repeatable: "<source\|>:<metric><operator><number>" — ["x:likes>=100", "reddit:score>50"] is "what landed, judged by what landing means where it was posted". Metrics are likes, replies, reposts, comments, score, views, plus total for the same interaction sum engagement_min reads. Operators are >=, >, =, <, <=; the number is whole and may be negative (Reddit and Lemmy net downvotes out). A Source no rule names PASSES — ["x:likes>=100"] narrows X and leaves Hacker News alone — a named rule overrides for its own Source, and several rules on one Source are ANDed; use source to ask for one Source. A metric that was never counted satisfies NOTHING, < included: YouTube reports no likes, RSS and AI answers report no audience, and mentions recorded before 2026-09-04 predate the field, so ["youtube:likes<10"] returns none of them rather than all of them. Send this or engagement_min, never both.
`opportunity`	No	true keeps only opportunities: mentions of a topic or competitor keyword that are highly relevant to it and whose author is someone to answer (the keyword's agent step says problem_fit true, or, without that field, the intent is purchase_intent, comparison or question). Use it for "who should I answer today?". An own keyword has none. Free.
`engagement_min`	No	Only mentions with at least this many interactions — likes, replies, reposts, comments or score, depending on the Source. Never counts views. Mentions with no counters at all (RSS, AI answers, anything recorded before 2026-09-04) are left out rather than treated as zero. Counters are captured when the item is collected and never refreshed, so a threshold reads against recent mentions. For a threshold on one metric on one Source, use engagement instead.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 26, 2026

addedInput schema / properties / opportunity

Added value: +{
+  "description": "true keeps only opportunities: mentions of a topic or competitor keyword that are highly relevant to it and whose author is someone to answer (the keyword's agent step says problem_fit true, or, without that field, the intent is purchase_intent, comparison or question). Use it for \"who should I answer today?\". An own keyword has none. Free.",
+  "type": "boolean"
+}

AddedSep 21, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Beyond the sparse annotations, the description discloses important behavioral traits: the default text mode is free, semantic mode charges 1 credit per question with a 10-minute free repeat, results are cursor-paged with nextCursor, and q= already handles keyword filtering in text mode. It does not mention auth or rate limits, but the pricing, paging, and misuse warning add considerable value beyond 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?

The description is five sentences, front-loading the core relationship to list_mentions and the purpose. Each sentence contributes distinct information: scope, use cases, cost model, a warning, and paging. It is slightly longer than minimal but every sentence earns its place; no filler.

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

Completeness4/5

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

Given the 14-parameter schema with full coverage and no output schema, the description provides essential context: scope, cost, paging, and a key pitfall. It anchors to list_mentions to convey the response shape and mentions the bucket enrichment. It could explicitly describe the response structure, but the combination of schema coverage and the list_mentions reference makes it sufficiently complete.

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?

With 100% schema description coverage, the baseline is 3, but the description adds semantic insight beyond the schema: it clarifies that bucket= is used for sorting categories (e.g., pricing complaints), that q= in text mode is the keyword filter (so bucket should not be used for that), and that cursor must be passed back unchanged. These clarifications help avoid common mistakes.

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 states exactly what the tool does: returns the same mentions as list_mentions but scoped to one keyword, additionally carrying the bucket each mention was sorted into. It gives concrete use cases ("what has my <brand> monitor caught?", "show me the pricing complaints") and explicitly differentiates it from the sibling list_mentions, making the purpose unambiguous.

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?

The description provides explicit when-to-use guidance with concrete examples, and warns against a common misuse ("Do not set it to filter by keyword: that is what q= in text mode already does"). It also names the alternative list_mentions as the baseline and explains cost implications of mode selection, helping the agent choose the right tool and parameters.

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

All Nephia tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?