Skip to main content
Glama

Add Keywords to a Niche's Master Keyword List

add_niche_keywords
Destructive

Adds your own search terms or Outlier/Residue keywords to a niche's Master Keyword List, batching them in one call and reporting what was added, moved, or blocked.

Instructions

Use this to add keywords to a niche's Master Keyword List (MKL): the user's own search terms, or keywords from the niche's Outliers or Residue lists. Free while the niche is fresh (dived in the last 24 hours, or a dive is running): the first call adds the keywords at once and they are readable with get_niche_keywords. On a stale niche, any keyword new to the niche makes the add re-dive the whole niche with its current competitors, which spends one Dive token per competitor. The first call then saves and spends nothing and returns confirmation_required with tokenCost; after the user approves, call again with confirm: true and maxTokensUsed set to that tokenCost. Keywords moved in from Outliers or Residue never cost anything. Returns originBreakdown (alreadyInMkl, takenFromOutliers, takenFromResidue, addedManually, takenFromExcluded, blockedByPhraseExclusion) and tokensUsed. When refresh is present a re-dive is running: poll get_dive_status with refresh.diveId; the addedManually keywords show in the MKL once it succeeds. A confirmed call is not safe to retry: if it errors or times out, poll get_dive_status or re-read get_niche_keywords instead of re-calling. Limited to 2 calls per minute per niche, so batch keywords into one call. Undo with remove_niche_keywords. Keyword exclusions: a keyword matching an exact exclusion is added and that exclusion removed, so it shows again; it is listed in takenFromExcluded and also in the group it landed in, so don't count it twice. A keyword matching a phrase exclusion is not added and not charged: it is listed only in blockedByPhraseExclusion with the matchedPhrase. To add it, remove that phrase with remove_keyword_exclusions and add again, but ask the user first, since removing the phrase can unhide other keywords too. Keywords in both lists come back lower-cased and trimmed.

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": {
      "nicheId": "<nicheId>",
      "keywords": "<keywords>"
    },
    "name": "add_niche_keywords"
  }
}

Input Schema

NameRequiredDescriptionDefault
confirmNoLeave unset on the first call. Set to true only after the user approved the Dive token cost from a `confirmation_required` response — it lets the add re-dive a stale niche.
nicheIdYesThe niche whose Master Keyword List to add to. Get one from `list_niches`.
keywordsYesThe keywords to add, 1–100 per call, at most 255 characters each. They are lower-cased and trimmed, and must be unique after that. Put every keyword in one call: this tool allows only 2 calls per minute per niche.
maxTokensUsedNoWith `confirm: true`: the `tokenCost` the user approved. The call then fails with nothing saved or charged rather than spend more. Ignored without `confirm`, where the tool never spends anything.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.17.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only flag destructiveHint=true; the description goes far beyond that by disclosing the token-cost model, the confirmation_required/maxTokensUsed approval round trip, that a confirmed call is not idempotent, a 2-calls-per-minute-per-niche rate limit, and the exact exclusion-resolution semantics (exact vs phrase). These are precisely the costly, non-obvious behaviors an agent needs before invoking.

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 cost, then return values, then recovery and limits – a sensible order. It is a single dense block with some redundancy (the 'first call spends nothing' idea and the Outliers/Residue no-cost rule are restated), but nearly every sentence adds decision-relevant information.

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?

Despite having no output schema, the description documents the return surface itself: confirmation_required with tokenCost, originBreakdown with all six buckets, tokensUsed, and the refresh/diveId handle. Combined with the cost and retry rules, an agent has everything needed to call this correctly and recover from failure.

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 the baseline is 3; the description earns above that by explaining the confirm/maxTokensUsed interlock as a stateful round trip (`confirmation_required` -> approval -> confirm: true with tokenCost) rather than just restating field definitions. It also adds that keywords are lower-cased and trimmed and must be unique after normalization.

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?

Opening clause states a specific verb and resource: 'add keywords to a niche's Master Keyword List (MKL)', and it enumerates the accepted sources (user's own search terms, Outliers, Residue lists). That distinguishes it immediately from siblings like add_keyword_exclusions, add_niche_labels, and remove_niche_keywords.

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?

Explicit routing for the main branches: free on a fresh niche, paid re-dive on a stale niche, never charged for Outliers/Residue moves. It names the alternative actions too – read results with get_niche_keywords, undo with remove_niche_keywords, unblock a phrase with remove_keyword_exclusions – and states the when-not (don't re-call after a confirmed error; poll get_dive_status instead).

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