Add Keywords to a Niche's Master Keyword List
add_niche_keywordsAdds 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
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Leave 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. | |
| nicheId | Yes | The niche whose Master Keyword List to add to. Get one from `list_niches`. | |
| keywords | Yes | The 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. | |
| maxTokensUsed | No | With `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. |