Nephia

Create a keyword

keyword_create

Create a keyword, the one object you monitor with. A keyword carries its terms (globalCriteria, and the searches of each Source), the Sources it polls and its settings: interval, webhook, mute rules and the other exclusions, sorting and sentiment. The smallest keyword is one Source, one interval and an optional webhook: sources with a single entry, refreshIntervalSeconds, webhookUrl. A Source whose search needs more than the shared text (a subreddit, a feed URL, a prompt, Vinted filters) takes it in searches[].overrides, whose description says what each Source needs. For the shape of rules or channels, read get_keyword on an existing keyword. A topic keyword (subjectRole topic) sent without globalCriteria.match is created with match word, the phrase as written; send match contains to widen it, or platform for the platform's own matching. For a topic, also send sentimentEnabled true and an aiStep with a boolean problem_fit field (true only when the author has the problem themselves): the opportunity filter of list_mentions reads it. Call keyword_estimate with the same arguments first: it runs the same validation, writes nothing, and returns the price and the estimateToken this tool requires. Starts or changes polling that is charged per check at each Source's credit rate (AI answers per engine asked) until the keyword or the Source is paused. Call keyword_estimate first, show the person the monthlyCredits it returns, and send its estimateToken only after they agree.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	Yes
`color`	No	The keyword colour in the dashboard. Left out on create, an unused one is picked.
`rules`	No	Replaces the list. Copy the shape from get_keyword on an existing keyword.
`aiStep`	No	Your own question asked of every mention, with the fields to fill: {"instruction": one or two sentences, 800 characters at most, "schema": 1 to 12 flat fields, each {"type": "string" \| "number" \| "boolean" \| "enum", "description", "values" for an enum, "maxLength" for a string}}, no nesting and no arrays. The answer arrives on each event as analysis. Costs 1 credit per 25 items, on top of the check rate. Delivery waits up to 120s for it; on timeout the event is still delivered, with the answer null and a status saying why. null removes it.
`sources`	Yes	The Sources this keyword polls, one entry each; a single entry is a keyword that polls one Source. Each enabled search is one check at its rate. What each Source needs is in the description of searches[].overrides.
`aiPreset`	No
`aiPrompt`	No
`backfill`	No	true runs a first scan right away, so the keyword is not empty on day one. What it finds fires no webhook, since a first scan is context and not news, and comes back marked seeded. A first scan is one search per enabled Source at that Source's check rate, except where a Source is billed per result: on X it is 5 credits plus 3 per result returned, at most 65 credits for its page of 20. So a first scan that includes such a Source is quoted at its ceiling: say "up to". Needs the nephia:spend permission. AI answers never backfills.
`channels`	No	Replaces the delivery channels attached to the keyword.
`schedule`	No	An activation window with ISO instants. null keeps the keyword always on.
`aiEnabled`	No	Sort mentions into buckets.
`muteRules`	No	Replaces the list. A plain string mutes that word.
`spikeAlert`	No	The alert a new keyword starts with. null starts with none. Free.
`vipAuthors`	No	Replaces the list. A plain string is a handle.
`webhookUrl`	No	A publicly reachable HTTPS endpoint the person controls: new mentions are POSTed there. Never invent this URL, ask the person for it. Left out, the keyword records what it catches without pushing it, and you read it with list_mentions, get_keyword_results or get_keyword_events. null removes the webhook.
`subjectRole`	No	What the keyword is about: your own brand, a competitor's, or a topic. A new topic without globalCriteria.match is created with match word.
`webhookMode`	No	all delivers every new mention; rules delivers only what a rule routes.
`estimateToken`	Yes	The estimateToken keyword_estimate returned for exactly these arguments. Valid 15 minutes. A token for other arguments is refused: estimate again.
`globalCriteria`	Yes	The criteria every search inherits: market (required, e.g. "us") and query or terms. AI answers reads no search text, so a keyword of prompts only still names a market.
`coBrandsEnabled`	No	AI answers only: also read each answer for the other brands it names, charged per answer on top of the run.
`relevanceContext`	No	One sentence the AI reading uses to judge relevance, such as "Acme is a cloud storage company, not the cartoon." null clears it.
`sentimentEnabled`	No	Read every mention for sentiment and intent.
`refreshIntervalSeconds`	Yes	Default seconds between checks, for every Source without its own interval. The plan and each Source set a floor; the estimate names the band when a value is outside it.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 26, 2026

changedInput schema / properties / subjectRole / description

Previous value: -"What the keyword is about: your own brand, a competitor's, or a topic."New value: +"What the keyword is about: your own brand, a competitor's, or a topic. A new topic without globalCriteria.match is created with match word."

Changed2 schema fields changedSep 24, 2026

addedInput schema / properties / color

Added value: +{
+  "description": "The keyword colour in the dashboard. Left out on create, an unused one is picked.",
+  "enum": [
+    "keyword-1",
+    "keyword-2",
+    "keyword-3",
+    "keyword-4",
+    "keyword-5",
+    "keyword-6",
+    "keyword-7",
+    "keyword-8"
+  ],
+  "type": "string"
+}

addedInput schema / properties / relevanceContext

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 400,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "One sentence the AI reading uses to judge relevance, such as \"Acme is a cloud storage company, not the cartoon.\" null clears it."
+}

AddedSep 21, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Even though annotations already mark this as a write operation, the description reveals substantial behavior beyond them: charging ('polling that is charged per check at each Source's credit rate'), the estimateToken's 15-minute validity and argument-binding constraint ('A token for other arguments is refused'), the backfill side effects and its nephia:spend permission requirement, and the webhook rule ('Never invent this URL, ask the person for it'). No contradiction with the annotations; openWorldHint=true is consistent with the many additionalProperties objects in the schema.

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 long but front-loaded — definition first, then the minimal shape, then the estimate workflow — and every sentence carries information an agent needs rather than repeating schema text. For a 23-parameter tool with 14 source types and billing semantics, the length is proportionate; a small amount of material (topic-keyword handling) also appears in the schema's subjectRole description, so it is slightly redundant but not wasteful.

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?

Given the tool's complexity — 23 parameters, nested source overrides, per-source interval floors, billing, and a required estimate artifact — the description covers everything an agent needs to call it correctly: prerequisites, approval workflow, special cases, permissions, and cost disclosure. No output schema exists, so return-value documentation is not required, and the success path is adequately hinted by the pointer to read results via list_mentions, get_keyword_results, or get_keyword_events.

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 87%, so the baseline is 3, and the description wisely avoids restating the schema's per-source override details. Instead it adds cross-parameter meaning the schema cannot: the minimal viable keyword ('one Source, one interval and an optional webhook'), the estimateToken-to-arguments binding, the topic-keyword default ('created with match word'), and the inheritance model where an absent searches array inherits globalCriteria. This is meaningful added semantics above the high-coverage baseline.

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 opening sentence states a specific verb and resource — 'Create a keyword, the one object you monitor with' — and then defines the object's anatomy (terms, Sources, settings). It names the confusable sibling keyword_estimate and clarifies the relationship ('it runs the same validation, writes nothing, and returns the price and the estimateToken this tool requires'), so an agent can distinguish create from estimate and update without opening schemas.

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

Usage Guidelines4/5

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

The description gives an explicit, two-part workflow: 'Call keyword_estimate with the same arguments first' and 'send its estimateToken only after they agree,' which is strong when-to-use guidance with a named alternative. It also routes the agent to get_keyword for the shape of rules and channels. However, it never states when NOT to use this tool — e.g., that modifying an existing keyword belongs to keyword_update — so the exclusion half of the guidance is implicit.

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?