Skip to main content
Glama

@datadive-tools/mcp

An MCP server that lets Claude (or any MCP-compatible client) query your DataDive niches, keywords, competitors, and Rank Radar data using your existing API key.

Runs locally on your machine over stdio. Your API key never leaves your machine except as the x-api-key header on requests to api.datadive.tools.

What you can ask

  • "List my DataDive niches in marketplace com."

  • "What's the master keyword list for niche z515cGOFg3?"

  • "Who are the top competitors in niche X and what are their sales?"

  • "What's my ranking juice for niche X — where can I improve?"

  • "Show me my rank radars."

  • "Plot the organic ranking trend for rank radar Y from 2024-03-01 to 2024-04-01."

  • "Run a niche dive on ASIN B08N5WRWNW in the US marketplace with 5 competitors."

  • "Refresh niche X with today's data, same competitors."

  • "Re-dive niche X with 12 competitors but keep B08N5WRWNW in the set."

  • "Is my dive done yet?"

  • "Start a rank radar tracking 10 keywords for ASIN B08N5WRWNW in niche X."

  • "Which Amazon seller accounts are connected?"

  • "Search my catalog for active 'widget' products in the US."

  • "What price or content changes happened on my listings last week?"

Related MCP server: YouTube MCP Server

1. Get a DataDive API key

  1. Sign in at https://2.datadive.tools.

  2. Go to Settings → API Key (/api-key).

  3. Click Generate API Key. Copy the value — you'll paste it into your MCP client config below.

Requires the Billing Manager or Owner role and the Standard plan or higher. Contact your org admin if you can't see the page.

2. Add it to your MCP client

Claude Desktop

Edit your config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the datadive entry under mcpServers:

{
  "mcpServers": {
    "datadive": {
      "command": "npx",
      "args": ["-y", "@datadive-tools/mcp"],
      "env": {
        "DATADIVE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. You should see datadive in the tools menu.

Claude Code

claude mcp add datadive -- npx -y @datadive-tools/mcp
# Then add the env var via:
#   claude mcp add datadive --env DATADIVE_API_KEY=YOUR_API_KEY -- npx -y @datadive-tools/mcp

Or edit .mcp.json in your project / ~/.claude/mcp.json globally with the same JSON shape as above.

Cursor

Settings → MCP → Add new MCP server and paste the same JSON shape:

{
  "datadive": {
    "command": "npx",
    "args": ["-y", "@datadive-tools/mcp"],
    "env": { "DATADIVE_API_KEY": "YOUR_API_KEY" }
  }
}

3. Verify

Ask Claude: "List my DataDive niches."

You should see a tool call to list_niches and a JSON response with your niches, plus pagination metadata. If you don't, see Troubleshooting below.

Available tools

Tool

Description

list_niches

Paginated list of your niches. Discovery step — returns nicheIds for the niche-scoped tools below.

list_niches

Paginated list of your niches. Discovery step — returns nicheIds for the niche-scoped tools below. Filter by searchText, searchAsin, spaces or labels; each niche lists the ids of its spaces and labels.

list_spaces

Your Spaces as a tree (id, name, path, children). A connected member sees only the Spaces they have rights on. Ids feed add_niche_spaces and the spaces filters.

list_labels

Your labels as a tree. Ids feed add_niche_labels and the labels filters.

list_fast_keywords

Paginated list of your organization's Fast Keywords runs (fastKeywordsId, ASIN, status, keyword count, search volume). Filter by search or marketplace.

get_fast_keywords

One Fast Keywords result: product, keyword roots and the top 10 competitors. Poll it until status is success.

get_fast_keywords_keywords

The keywords of a finished Fast Keywords run: search volume, organic and sponsored rank, highest volume first. Paged (up to 100).

run_fast_keywords

Spends 1 dive token. Finds a product's keywords from just its ASIN. Async — poll get_fast_keywords. Previews the cost first and requires confirm: true.

refresh_fast_keywords

Spends 1 dive token. Re-runs a Fast Keywords result; allowed once every 24 hours. Requires confirm: true.

get_niche_keywords

Master keyword list for a niche: search volume, relevancy, competitor ASIN ranks, suggested bid.

get_niche_outlier_keywords

A niche's Outliers, paginated: high search volume keywords only a few competitors rank for.

get_niche_residue_keywords

A niche's Residue, paginated: keywords in neither the Master Keyword List nor the Outliers.

get_niche_roots

Keyword lexical roots for a niche — high-impact words with frequency and broad search volume.

get_niche_competitors

Competitor ASINs, titles, BSR, category and niche statistics (sales, revenue, ratings, opportunity score).

get_ranking_juice

DataDive proprietary ranking-juice metric per competitor (current vs optimized listing).

list_rank_radars

Paginated list of rank radars. Filter by nicheId, searchText, spaces, labels (matched through the niche) or status (ACTIVE by default, plus PAUSED, ARCHIVED, ALL).

get_rank_radar_data

Historical keyword rankings for a rank radar within a startDate/endDate range (max 90 days). Returns every active keyword by default; pass currentPage/pageSize (up to 100) to read one page at a time.

get_rank_radar_sqp_data

Amazon Search Query Performance per Rank Radar keyword: search volume, impressions, clicks, cart adds, purchases — market total vs this ASIN family. Same date range and paging as get_rank_radar_data.

get_rank_radar_ppc_data

Sponsored Products metrics per Rank Radar keyword: sponsored rank, spend, sales, ACOS, CPC, match types; optional per-campaign breakdown. Same date range and paging as get_rank_radar_data.

create_niche_dive

Spends dive tokens. Starts new niche research from a seed ASIN. Async — returns a diveId to poll with get_dive_status. Pass fastKeywordsRequestId (from run_fast_keywords) to link it to a Fast Keywords run. Requires confirm: true.

create_niche_dive_from_competitors_list

Spends dive tokens. Starts niche research from your own list of 2–200 competitor ASINs, with no automatic discovery. Async — returns a diveId to poll with get_dive_status. Requires confirm: true.

redive_niche

Spends dive tokens. Refreshes an existing niche with current data — either the same competitors or a newly discovered set. Async — returns a diveId to poll with get_dive_status. Requires confirm: true.

add_niche_keywords

Adds keywords to a niche's Master Keyword List (1–100 per call). Free on a niche dived in the last 24 hours. On an older niche it re-dives the niche and spends dive tokens — then it asks for confirm: true first.

remove_niche_keywords

Takes keywords back out of a niche's Master Keyword List: hand-added ones are deleted, ones from Outliers/Residue go back there, dive-found ones stay. Free.

list_keyword_exclusions

The keywords a niche hides from its Master Keyword List: exact entries with their search volume, phrase entries with how many keywords and how much search volume they hide.

add_keyword_exclusions

Hides keywords from a niche's Master Keyword List — exact (one keyword) or phrase (every keyword containing it), 1–100 entries per call. Free; undone by remove_keyword_exclusions.

remove_keyword_exclusions

Removes exact or phrase exclusions so the keywords they hid show again. Free.

add_niche_spaces / remove_niche_spaces

Puts a niche in, or takes it out of, 1–100 Spaces (spaceIds from list_spaces). Free, no confirm. Needs Manage access to the niche, as in the web app; a Space you only have view rights on is refused. One unknown or refused id fails the whole call and nothing changes.

add_niche_labels / remove_niche_labels

Same for labels (labelIds from list_labels). Needs Manage access to the niche.

get_dive_status

Poll a dive started by create_niche_dive or redive_niche: in_progress, success (carries the nicheId), or error.

create_rank_radar

Spends Search Term tokens. Starts tracking keyword rankings for an ASIN in a niche. Returns a rankRadarId. Requires confirm: true.

add_rank_radar_search_terms

Starts tracking extra keywords on an existing rank radar. Takes one Daily Tracked Keywords slot per new keyword; reversible with pause_rank_radar_search_terms.

pause_rank_radar_search_terms

Pauses individual keywords of a rank radar, keeping their history and freeing their tracking slots. Takes keyword ids from get_rank_radar_data.

resume_rank_radar_search_terms

Restarts tracking on paused keywords of a rank radar. Takes back one tracking slot each.

pause_rank_radar

Pauses a whole rank radar (what the API calls archiving — listed under status: PAUSED, not ARCHIVED). Tracking stops, the history is kept, and the tracking slots are freed. Reversible with resume_rank_radar.

resume_rank_radar

Reactivates a paused rank radar, restoring as many keywords as the remaining quota allows (most relevant first).

delete_rank_radar

Destroys ranking history. Deletes a rank radar permanently (listed under status: ARCHIVED) and frees its tracking slots. Requires confirm: true — prefer pause_rank_radar if the data may be wanted later.

delete_niche

Destroys niche data. Deletes a niche with its keywords, competitors and dive history; spent dive tokens are not refunded. Blocked while a rank radar uses the niche. Requires confirm: true.

generate_listing_copy

Spends an AI Copywriter prompt. Drafts an optimised title, bullets and description from a niche's keyword research. Nothing is published to Amazon. Async — returns a generationId. Requires confirm: true.

get_listing_copy_generation_status

Poll a draft started by generate_listing_copy: generating, complete (carries the generated copy), or failed. Free to poll.

list_seller_profiles

Paginated list of connected Amazon seller accounts. Discovery step — returns the sellerId + marketplace the seller-scoped tools below (and the alert tools) need.

get_seller_catalog

Paginated catalog of a seller's own ASINs. Filter by search, brand, and status (Active by default).

get_seller_listing_changes

Paginated price/content/image changes on a seller's listings, including Item Highlights changes (contentType: "Highlights"). Filter by types, asin, brand, search, and a date range; optionally include ranking/conversion correlation.

list_ppc_campaigns

Sponsored Products campaigns of a seller account with window totals and a per-placement breakdown. Filter by asin / parentAsin, state, search; sort by any metric. Window up to 90 days (default 30).

get_asin_inventory_distribution

Inventory metrics for an ASIN (stock, days of stock, low-inventory state, LILF and LTSF fees, aged units) and its per-fulfillment-center sellable inventory. Requires sellerId from list_seller_profiles or your Connections page.

list_indexing_issue_alerts

Paginated list of indexing-issue alerts — ASINs no longer indexed for their tracked keywords. Filter by sellerId, marketplace, status, or updatedSince.

list_blind_spend_alerts

Paginated list of blind-spend alerts — ad spend on search terms with little or no sales, with per-term spend/clicks/CVR. Same filters as above.

get_quota

Current quota usage and capacity per billable feature, plus the next refresh date. No arguments.

list_usage

Paginated billable usage logs (token-consumption events). Filter by type, search (user), and startDate/endDate.

All data is scoped to the organization that owns the API key. Most tools are read-only. The tools that change something are marked above; the ones that cannot be undone also require an explicit confirm: true — see Tools that change something.

Tools that change something

Six tools cannot be undone, so they require an explicit confirm: true argument. Called without it, they change nothing and return a note asking the assistant to confirm the cost with you first:

  • create_niche_dive, redive_niche — spend dive tokens (scales with numberOfCompetitors).

  • create_rank_radar — spends Search Term tokens (scales with numberOfKeywords).

  • generate_listing_copy — spends one AI Copywriter prompt per call.

  • delete_niche, delete_rank_radar — destroy data permanently.

Check your remaining balance any time with get_quota.

create_rank_radar uses that first, unconfirmed call to preview the creation against the API, so the note it comes back with can tell you something specific rather than only the token cost — for instance that the product family you asked for is already tracked by another of your Rank Radars, which would spend Tracked Search Terms on it twice. The preview creates nothing and spends nothing, and a warning never blocks the creation: two Rank Radars on one family is how you track two different sets of search terms and keep separate statistics.

The other write tools — pause_rank_radar, resume_rank_radar and the three *_rank_radar_search_terms tools — need no confirmation. They only move Daily Tracked Keywords capacity, which is freed again when you pause, and each is undone by its counterpart.

add_niche_keywords asks for confirm: true only when it would spend: on a niche dived in the last 24 hours its first call adds the keywords for free, while on an older niche that call changes nothing and returns the Dive token cost of the re-dive the add triggers. remove_niche_keywords and the keyword exclusion tools are free and need no confirmation.

To skip the per-call confirmation (e.g. in an automated setup), set DATADIVE_AUTO_CONFIRM_WRITES=true in your client config — then all six run without confirm, deletes included.

None of the three is safe to retry — each call spends tokens again and creates a separate dive / re-dive / Rank Radar, even with identical arguments. If a call errors or times out, check get_dive_status / list_niches / list_rank_radars for what already exists before calling again.

Dives are asynchronous. create_niche_dive returns a diveId and an estimated completion time immediately; poll get_dive_status with that diveId until it reports success, which carries the new nicheId you then feed to list_niches, get_niche_keywords, and the other niche tools.

redive_niche refreshes a niche you already have rather than creating another one, and it keeps the same nicheId — so rank radars and reports built on that niche follow the refreshed data. It takes a mode:

  • same_competitors — re-dive the niche's current competitor set. Nothing else to supply; use it purely to pull in current sales, price and keyword data.

  • discover — search for a fresh competitor set of numberOfCompetitors ASINs. Steer it with heroAsin (the seed to build around; defaults to the niche's highest-selling competitor, preferring one of your own ASINs), lockedAsins (kept no matter what discovery finds) and excludedAsins (never selected).

⚠️ For create_niche_dive, marketplace uses full Amazon domain suffixes (com, co.uk, com.mx, co.jp, …) — e.g. the UK marketplace is co.uk, not uk.

Configuration

Env var

Required

Default

Notes

DATADIVE_API_KEY

yes

—

Generate at https://2.datadive.tools/api-key

DATADIVE_API_BASE_URL

no

https://api.datadive.tools

Override for staging

DATADIVE_AUTO_CONFIRM_WRITES

no

false

Set truthy to let every confirm: true tool run without it — dives, rank radar creation, listing copy and the two deletes.

Troubleshooting

If a tool call returns an error message, it'll be one of these — each maps to a specific HTTP status from the DataDive API.

Message starts with…

What to do

Authentication failed: your DATADIVE_API_KEY is invalid or expired

The key is wrong, deleted, or expired. Generate a new one at https://2.datadive.tools/api-key.

Subscription is inactive or paused

Resume billing at https://2.datadive.tools — the API key is valid but the subscription isn't active.

Quota exceeded / … quota exceeded

The subscription's quota for that billable feature (Dive tokens, Rank Radar tracked keywords, AI Copywriter prompts, …) is used up. The message names the feature, the usage, the next refresh date when there is one, and links to the subscription overview page where it can be raised. Don't retry until it has been.

Forbidden

The key is valid but doesn't have access to that resource. Usually a niche/rank-radar that belongs to a different org.

Rate limit exceeded

Wait a few seconds and retry.

Bad request

Check the parameters — the message echoes the server's validation error (e.g., pageSize must not exceed 50).

DataDive API error (5xx)

Transient backend issue. Try again; if it persists, contact support.

Network error reaching …

Your machine can't reach api.datadive.tools — check VPN / firewall / DNS.

If the server itself fails to start, look in your MCP client's log output:

  • DATADIVE_API_KEY environment variable is required — the env var isn't being passed through to the binary. Confirm your client config has it under env (not args), and that you've restarted the client after editing.

Privacy

  • The MCP server runs locally on your machine. It is a thin shim — every tool call becomes a single HTTPS request from your machine to api.datadive.tools with your API key as the x-api-key header.

  • Your API key is stored only in your MCP client's config file (which you control). It is never sent anywhere else.

  • The server logs nothing on its own. Standard backend access logs at DataDive record per-request metadata (organization, route, status, latency) the same way any direct API call would.

Development

npm install
npm run build       # tsup -> dist/index.js (with shebang)
npm test            # vitest run
npm run typecheck   # tsc --noEmit
npm run lint        # eslint

Test the binary end-to-end with the MCP Inspector:

DATADIVE_API_KEY=YOUR_API_KEY npx @modelcontextprotocol/inspector dist/index.js

Releasing

The repo uses Changesets:

npx changeset             # add a changeset describing the change (patch/minor/major)
git commit -am "fix: ..."
git push

A "Version Packages" PR opens automatically. Merging it bumps the version, updates CHANGELOG.md, and publishes to npm with provenance.

Support

License

MIT — see LICENSE.

Available Tools

56 tools
add_keyword_exclusionsExclude Keywords from a NicheA
Destructive
Inspect

Use this to hide irrelevant keywords from a niche's Master Keyword List — e.g. other brands, wrong product types. exact entries hide the one keyword that matches exactly; phrase entries hide every keyword containing the phrase, so prefer exact unless the user wants a whole family of keywords gone. The excluded keywords drop out of get_niche_keywords at once, wherever they come from: the dive, Outliers, Residue, or ones added with add_niche_keywords. Nothing is deleted: remove_keyword_exclusions brings them back. Only the exclusions change — every other niche setting is kept. Send 1–100 entries in total across exact and phrase; a niche can hold at most 1000 exclusions. Free, no tokens, and safe to repeat: entries already excluded come back under unchanged. Returns added, unchanged and the full exact / phrase lists after the change. Limited to 30 calls per minute per niche, so batch entries into one call.

Inputs: nicheId (required), exact, phrase.

add_niche_keywordsAdd Keywords to a Niche's Master Keyword ListA
Destructive
Inspect

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.

Inputs: nicheId (required), keywords (required), confirm, maxTokensUsed.

add_niche_labelsAdd Labels to a NicheA
Destructive
Inspect

Use this to put a niche in one or more labels (ids from list_labels). Returns added and alreadyPresent. Undo with remove_niche_labels. The same rights as the web app: the user needs Manage access to the niche, and to every Space added or removed. A refusal is a 403, so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

Inputs: nicheId (required), labelIds (required).

add_niche_spacesAdd a Niche to SpacesA
Destructive
Inspect

Use this to put a niche in one or more Spaces (ids from list_spaces). A Space controls who can see the niche, so adding or removing one changes access. Returns added and alreadyPresent. Undo with remove_niche_spaces. The same rights as the web app: the user needs Manage access to the niche, and to every Space added or removed. A refusal is a 403, so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

Inputs: nicheId (required), spaceIds (required).

add_rank_radar_search_termsAdd Search Terms to a Rank RadarA
Destructive
Inspect

Use this to start tracking extra keywords on an existing Rank Radar, instead of creating a new one with create_rank_radar. New keywords are added to the niche and tracked from now on; any matching keyword that was previously paused is resumed. Each newly tracked keyword takes one Daily Tracked Keywords slot, and the call fails if the quota is exhausted — check get_quota first. Reversible with pause_rank_radar_search_terms, which frees the slots again, so it needs no confirm. Returns originBreakdown (where each submitted term ended up) and keywordToRankRadarKeywordIdMap, whose ids are what the pause/resume search-term tools take.

Inputs: rankRadarId (required), searchTerms (required).

add_rank_radar_tag_search_termsAttach Search Terms to a Rank Radar TagA
Destructive
Inspect

Use this to tag a batch of keywords on a Rank Radar — the same relation create_rank_radar_tag writes when rankRadarKeywordIds is passed on creation, so this is how you keep extending a tag's keyword set over time. Reversible with remove_rank_radar_tag_search_terms, so no confirmation is required. Idempotent: already-attached keywords are left unchanged, so re-sending the same ids after a timeout is safe. Up to 1000 ids per call — split larger batches into multiple calls. The system "paused" tag (reserved colour, written by the quota pauser) is not addressable: the API answers 404.

Inputs: tagId (required), rankRadarId (required), rankRadarKeywordIds (required).

create_niche_diveCreate a Niche DiveA
Destructive
Inspect

Use this to start new niche research from a seed ASIN. ⚠️ Spends dive tokens (cost scales with numberOfCompetitors) and cannot be undone — set confirm: true only after the user approves the cost. Not safe to retry: each call spends tokens again and starts a separate dive — if a call errors or times out, poll get_dive_status (or check list_niches) instead of re-calling. The dive runs asynchronously: this returns immediately with a diveId and an estimatedCompletionDate. Poll get_dive_status with that diveId until it reports success (which carries the new nicheId for use with list_niches, get_niche_keywords, etc.). Requires marketplace, asin, and numberOfCompetitors (min 2). After a Fast Keywords run for the same product, pass its requestId as fastKeywordsRequestId to link the dive to it.

Inputs: asin (required), marketplace (required), numberOfCompetitors (required), confirm, +1 more.

create_niche_dive_from_competitors_listCreate a Niche Dive from a Competitor ListA
Destructive
Inspect

Use this when the user already knows which products belong in the niche — e.g. they list competitor ASINs, or picked them from search results — and wants niche research on exactly those. Unlike create_niche_dive, which discovers competitors around one seed ASIN, this builds the niche from the given ASINs only (2-200). ⚠️ Spends dive tokens for every ASIN and cannot be undone — set confirm: true only after the user approves the cost. Not safe to retry: each call spends tokens again and starts a separate dive — if a call errors or times out, poll get_dive_status (or check list_niches) instead of re-calling. Fails without spending tokens when the ASIN count is over the plan's limit, when the account is at its niche limit, or when Amazon product data cannot be found for enough of the ASINs. The dive runs asynchronously: this returns a diveId and an estimatedCompletionDate; poll get_dive_status with the diveId until it reports success, which carries the new nicheId.

Inputs: asins (required), marketplace (required), confirm.

create_rank_radarCreate a Rank RadarA
Destructive
Inspect

Use this to start tracking organic and sponsored keyword rankings for an ASIN within a niche. ⚠️ Spends Search Term tokens (cost scales with numberOfKeywords) and cannot be undone — set confirm: true only after the user approves the cost. Not safe to retry: each call spends tokens again and creates a separate Rank Radar — if a call errors or times out, check list_rank_radars instead of re-calling. The first call previews the creation and may return warnings alongside the cost note — for example that this product family is already tracked by another Rank Radar. Show every warning message to the user verbatim, before asking them to confirm; do not summarise it or decide on their behalf. A warning never blocks creation. Returns the new rankRadarId; read its data later with get_rank_radar_data. Requires asin, numberOfKeywords (min 1), and a nicheId from list_niches.

Inputs: asin (required), nicheId (required), numberOfKeywords (required), confirm.

create_rank_radar_tagCreate a Rank Radar TagA
Destructive
Inspect

Use this to create a new user tag ("highlight") on a Rank Radar — the way the UI marks a window on the ranking chart. Writing a tag costs nothing and is reversible with delete_rank_radar_tag, so no confirmation is required. Returns the new tag row (id, title, color, description, startAt, endAt, keywordCount, createdAt); the id is the tagId the other tag tools take. If the title clashes with an existing tag on this Rank Radar, the API answers 409 { error: 'TAG_TITLE_EXISTS', existingTagId } so callers can reuse the existing tag without a follow-up list_rank_radar_tags. The reserved colour #EB5757 is rejected with 400. Pass rankRadarKeywordIds to tag a batch of keywords in the same call; otherwise create the tag and attach keywords later with add_rank_radar_tag_search_terms.

Inputs: title (required), rankRadarId (required), color, endAt, +3 more.

delete_nicheDelete a NicheA
Destructive
Inspect

Use this to permanently remove a niche the user no longer needs. ⚠️ Deletes the niche and everything attached to it — keywords, competitors, all dives and diveboxes — and cannot be undone; the dive tokens already spent on it are NOT refunded. Set confirm: true only after the user approves. A niche used by any Rank Radar cannot be deleted: the call fails with a conflict, so delete or archive those rank radars first (list_rank_radars with the nicheId filter shows them).

Inputs: nicheId (required), confirm.

delete_rank_radarDelete a Rank RadarA
Destructive
Inspect

Use this to permanently remove a Rank Radar and all of its keyword ranking history. ⚠️ Cannot be undone — there is no restore endpoint; set confirm: true only after the user approves. It does free the Daily Tracked Keywords quota those keywords held. Deleted Rank Radars are what list_rank_radars returns for status: ARCHIVED. If the user only wants to stop tracking for a while and keep the history — or asks to 'archive' the Rank Radar, which is what the DataDive API calls pausing — use pause_rank_radar instead: it frees the same quota and is reversible with resume_rank_radar.

Inputs: rankRadarId (required), confirm.

delete_rank_radar_tagDelete a Rank Radar TagA
Destructive
Inspect

Use this to permanently remove a tag from a Rank Radar. ⚠️ The tag itself is gone and the assignments linking it to each tagged keyword are removed with it; the keywords themselves keep tracking. The deletion cannot be undone from this tool, so set confirm: true only after the user approves. The system "paused" tag (reserved colour, written by the quota pauser) cannot be addressed from here — the API answers 404. To remove just the assignments and keep the tag, use remove_rank_radar_tag_search_terms instead.

Inputs: tagId (required), rankRadarId (required), confirm.

generate_listing_copyGenerate Listing Copy for a NicheA
Destructive
Inspect

Use this to draft an optimised Amazon listing — title, bullets and description — from a niche's keyword research and the seller's current listing. It writes text only: nothing is published to Amazon, and the user still has to paste the result into Seller Central. ⚠️ Spends one AI Copywriter prompt from the quota per call and cannot be undone — set confirm: true only after the user approves. Not safe to retry: each call spends another prompt, so if a call errors or times out, poll get_listing_copy_generation_status instead of re-calling. Runs asynchronously: returns a generationId — poll get_listing_copy_generation_status with it until the status is complete.

Inputs: nicheId (required), strategy (required), currentListing (required), confirm.

get_asin_inventory_distributionGet Inventory Metrics and Fulfillment-Center Distribution for an ASINA
Read-only
Inspect

Use this when the user asks about an ASIN's inventory: stock levels, days of stock or when it will run out, low-inventory or aged-inventory risk, low-inventory-level (LILF) or long-term storage (LTSF) fees, or where their units sit across Amazon's fulfillment network. Requires the Amazon sellerId (from list_seller_profiles or the user's DataDive Connections page at https://2.datadive.tools), the marketplace code, and the ASIN. Returns the metrics the DataDive Inventory page shows — fulfillableStock, totalStock, reservedStock, inboundStock, researchingStock, unfulfillableStock, daysOfStock (with daysOfStockSource AMAZON or ESTIMATE), daysOfStock30, daysOfStock90, inLowInventoryState, estWeeklyLilf, estLtsfNextAssessment, ltsfLastMonthActual, agedUnits, oldestUnitAgeDays, with fees in currency — plus totalSellableUnits and a per-FC distribution array (fc, state, availableStock, availableStockPercentage). A metric is null, never 0, when Amazon has no data (e.g. merchant-fulfilled); metrics the user's plan does not include are null and listed in lockedFields (say they need a plan upgrade, do not report them as zero). lastUpdatedAt dates the stock and metrics; distributionLastUpdatedAt dates the distribution, which is usually up to 2 days behind. Either may be null when no successful refresh happened in the last 30 days.

Inputs: asin (required), sellerId (required), marketplace (required).

get_dive_statusGet Niche Dive StatusA
Read-only
Inspect

Use this to poll a niche dive started with create_niche_dive, create_niche_dive_from_competitors_list or redive_niche, or the re-dive add_niche_keywords started on a stale niche, until it finishes. Returns one of three shapes keyed by status: in_progress (with estimatedCompletionDate), success (with the nicheId plus tokensUsed/tokensLeft), or error (with an error message). On success, use the nicheId with list_niches, get_niche_keywords, get_niche_competitors, etc. (for a re-dive it is the same niche you passed in, now carrying refreshed data). Re-poll periodically — dives can take minutes; the estimatedCompletionDate hints at when to check.

Inputs: diveId (required).

get_fast_keywordsGet a Fast Keywords ResultA
Read-only
Inspect

Use this to poll a Fast Keywords run started with run_fast_keywords or refresh_fast_keywords, and to read its result. While status is in-progress, wait a few seconds and call again; stop at success or failed. On failed, failureReason and failureMessage say why (safe to show to the user). On success it returns the product (title, brand, price, imageUrl), its variations, keywordCount, lastRefreshedAt, the top keyword roots by search volume (root, aggregateSearchVolume, medianOrganicRank, keywordCount, and a sample of its keywords; totalRoots is how many there are) and the top 10 competitors. insufficientKeywordData: true means the run succeeded but found too few keywords to be useful. The keyword rows themselves are in get_fast_keywords_keywords.

Inputs: fastKeywordsId (required).

get_fast_keywords_keywordsGet the Keywords of a Fast Keywords ResultA
Read-only
Inspect

Use this to read the keywords of a finished Fast Keywords run (check status is success with get_fast_keywords first). Returns keyword, searchVolume, organicRank and sponsoredRank per keyword, highest search volume first, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). A page holds at most 100 keywords; keep requesting the next page while hasNext is true.

Inputs: fastKeywordsId (required), pageSize, currentPage.

get_listing_copy_generation_statusGet Listing Copy Generation StatusA
Read-only
Inspect

Use this to poll a listing-copy draft started with generate_listing_copy until it finishes. Returns one of three shapes keyed by status: generating (still running — poll again in a few seconds), complete (with result, carrying the generated title, bullets, description, itemHighlights and its rankingJuice score), or failed (with an error message). Polling is free — it does not spend another AI Copywriter prompt, so always poll rather than re-calling generate_listing_copy.

Inputs: nicheId (required), generationId (required).

get_niche_competitorsGet Competitors and Niche StatisticsA
Read-only
Inspect

Use this for competitor ASINs, product titles, BSR, sales/revenue benchmarks, or niche opportunity scoring. Retrieves the list of Competitors within the specified Niche along with Niche statistics. For the Niche: keyword statistics, opportunity evaluation, benchmark median values, and overall competitor strength assessment. For each Competitor: ASIN, product title, BSR, category and full category tree, sales, revenue, ratings, reviews, price, number of variations, image URL, total Ranking Juice, and ranking data. BSR supports ranking Competitors by sales position within mentioned category. For the Ranking Juice breakdown by title, bullets and description, use get_ranking_juice.

Inputs: nicheId (required).

get_niche_keywordsGet Master Keyword List for a NicheA
Read-only
Inspect

Use this when the user asks about keywords, search terms, or search volume for a niche. Retrieves the master keyword list for the specified Niche — the relevant search terms monitored for ranking and performance metrics. For each keyword, returns search volume, relevancy (numeric score or "Outlier"), and competitor ASIN organic ranks (asinRanks: { ASIN -> rank | null }), the exact-match suggestedBid (min / max / median in cents; null when not yet fetched for the latest dive), plus origin: mkl (found by the dive), manual (added by hand with add_niche_keywords), outlier / residue (moved in from those lists). Only manual, outlier and residue keywords can be taken out with remove_niche_keywords. Keywords hidden by the niche's keyword exclusions are not listed; see list_keyword_exclusions. Also returns the latestResearchDate.

Inputs: nicheId (required).

get_niche_outlier_keywordsGet the Outlier Keywords of a NicheA
Read-only
Inspect

Use this when the user asks about a niche's Outliers: high search volume keywords that only a few of the niche's competitors rank for, so they fall outside the Master Keyword List (get_niche_keywords). For each keyword, returns search volume, relevancy, competitor ASIN organic ranks (asinRanks: { ASIN -> rank | null }) and the exact-match suggestedBid (min / max / median in cents; null when not yet fetched for the latest dive), plus latestResearchDate and pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). A page holds at most 100 keywords; keep requesting the next page while hasNext is true. To move a keyword into the Master Keyword List, use add_niche_keywords.

Inputs: nicheId (required), pageSize, currentPage.

get_niche_residue_keywordsGet the Residue Keywords of a NicheA
Read-only
Inspect

Use this when the user asks about a niche's Residue: the niche's keywords that are in neither the Master Keyword List (get_niche_keywords) nor the Outliers (get_niche_outlier_keywords). For each keyword, returns search volume, relevancy, competitor ASIN organic ranks (asinRanks: { ASIN -> rank | null }) and the exact-match suggestedBid (min / max / median in cents; null when not yet fetched for the latest dive), plus latestResearchDate and pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). A page holds at most 100 keywords; keep requesting the next page while hasNext is true. To move a keyword into the Master Keyword List, use add_niche_keywords.

Inputs: nicheId (required), pageSize, currentPage.

get_niche_rootsGet Keyword Roots for a NicheA
Read-only
Inspect

Use this when the user wants to find the highest-impact words across a niche's keywords, asks about 'keyword roots', or wants to prioritize terms for a listing. Retrieves the keyword lexical roots for the Niche — individual words or word-combinations extracted from the Master Keyword List (e.g. 'bluetooth headphones' yields roots 'bluetooth', 'headphones', 'bluetooth headphones'). Returns roots and normalizedRoots tables, each item with root, frequency (how many keywords contain it), broadSearchVolume (summed search volume of those keywords), and broadSearchVolumeRatio (0-1, relative to the top root), plus the per-keyword breakdowns and latestResearchDate.

Inputs: nicheId (required).

get_quotaGet Quota UsageA
Read-only
Inspect

Use this when the user asks how much quota or how many tokens they have left, or before creating a Niche Dive or Rank Radar to check remaining headroom. Returns current quota usage and capacity for each billable feature — DIVED_ASINS (Dive tokens), RANK_RADAR_KEYWORDS (tracked keywords), PRODUCT_BRIEF_ASINS, and AI_COPYWRITER_PROMPTS — each with used and capacity (null when unlimited / not applicable), plus nextRefreshDate (ISO-8601 timestamp of the next quota reset, or null). Takes no arguments.

Inputs: no named parameters.

get_ranking_juiceGet Ranking Juices for a NicheA
Read-only
Inspect

Use this when the user asks 'how do I rank higher', 'what's my ranking juice', or wants listing-optimization guidance. Retrieves the Ranking Juices for each Competitor within the specified Niche. Ranking Juice is DataDive's proprietary metric identifying the key factors driving search-ranking success for each Competitor's listing. Returns currentListing and optimizedListing breakdowns (rankingJuice + per-property contributions: title, bullets, description) plus per-competitor listing scores and the latestResearchDate.

Inputs: nicheId (required).

get_rank_radar_dataGet Keyword Rankings for a Rank RadarA
Read-only
Inspect

Use this to analyze keyword ranking trends over time. Requires startDate and endDate (yyyy-mm-dd), at most 90 days apart. Retrieves historical keyword ranking data for the specified Rank Radar within the date range. Without currentPage and pageSize it returns every active keyword in one result. To read one page instead — faster for large Rank Radars — pass currentPage and/or pageSize (max 100) and continue with currentPage + 1 while hasNext is true. The response carries currentPage, pageSize, total, lastPage, hasNext and hasPrev; total is the Rank Radar's active keyword count. Paused keywords are not included. Each keyword has id, keyword, searchVolume, relevancy, ranks (per-day { date, organicRank, sponsoredRank, impressionRank }), and highlights — the user tags on this keyword. Each highlights entry is the same object list_rank_radar_tags returns (id, title, color, description, startAt, endAt, type, krtId, krtKeywordId); its id is the tagId the tag-management tools take. A rank of 101 means the product was not in the top 100 results that day. For PPC metrics use get_rank_radar_ppc_data; for Search Query Performance use get_rank_radar_sqp_data. Use after list_rank_radars to discover a rankRadarId.

Inputs: endDate (required), startDate (required), rankRadarId (required), pageSize, +1 more.

get_rank_radar_ppc_dataGet PPC Data for a Rank RadarA
Read-only
Inspect

Use this when the user asks about advertising (Sponsored Products) performance for the keywords of a Rank Radar. Requires startDate and endDate (yyyy-mm-dd), at most 90 days apart; 30 days or less keeps it fast. Each keyword's metrics are aggregated over the range: sponsoredRank (median; 101 means not in the top 100 sponsored results), impressionRank and impressionRankShare; how many exact, phrase, broad and auto campaigns target it; organicSales, ppcSales, ppcSpend, costPerClicks, clickThroughRate, conversionRate, totalClicks, totalImpressions, totalOrders and acos. Metrics are null or 0 when the seller runs no ads on a keyword. Set includeCampaigns for the per-campaign breakdown. Results are paged by keyword: data holds one page, and the response carries currentPage, pageSize, total, lastPage, hasNext and hasPrev. total is the Rank Radar's active keyword count; to read every keyword, call again with currentPage + 1 while hasNext is true, using pageSize 100 for large Rank Radars. Paused keywords are not included. Each call counts toward API usage and is rate limited (about 60 requests/minute). For the seller's campaigns as a whole, use list_ppc_campaigns. Use after list_rank_radars to discover a rankRadarId.

Inputs: endDate (required), startDate (required), rankRadarId (required), pageSize, +2 more.

get_rank_radar_sqp_dataGet Search Query Performance for a Rank RadarA
Read-only
Inspect

Use this when the user asks how shoppers search, click, add to cart and buy for the keywords of a Rank Radar — Amazon's Search Query Performance (SQP) data, from Brand Analytics. Requires startDate and endDate (yyyy-mm-dd), at most 90 days apart; 30 days or less keeps it fast. Each keyword's metrics are aggregated over the range: searchQueryVolume and searchQueryScore; impressions, clicks, cart adds and purchases, each as the total across all sellers (*TotalCount), this ASIN family's count (*AsinCount) and its share (*AsinShare); click, cart-add and purchase rates; and ctr/cvr for the market (*Total) and for this ASIN family (*Asin). numberOfDaysWithData says how many days of the range had SQP data; metrics are null when there is none, which is normal for low-volume keywords, recent dates (Amazon publishes SQP with a delay) and sellers without Brand Analytics. Results are paged by keyword: data holds one page, and the response carries currentPage, pageSize, total, lastPage, hasNext and hasPrev. total is the Rank Radar's active keyword count; to read every keyword, call again with currentPage + 1 while hasNext is true, using pageSize 100 for large Rank Radars. Paused keywords are not included. Each call counts toward API usage and is rate limited (about 60 requests/minute). Use after list_rank_radars to discover a rankRadarId.

Inputs: endDate (required), startDate (required), rankRadarId (required), pageSize, +1 more.

get_seller_catalogList Catalog ASINs for a SellerA
Read-only
Inspect

Use this when the user wants to browse or search a seller's own Amazon catalog — the products they sell on a given marketplace. Requires a sellerId + marketplace (use list_seller_profiles to discover them). Filter by search (title/brand), brand, and status (Active by default, or all; deleted listings are never returned). Only listings Amazon reported in the last 30 days are included. Returns a paginated list where each item has asin, title, parentAsin, brand, status, imageUrl, and hasVariations, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Inputs: sellerId (required), marketplace (required), brand, search, +3 more.

get_seller_listing_changesList Listing Changes for a SellerA
Read-only
Inspect

Use this when the user asks what changed on their Amazon listings — price, content (title/bullets/description), or image edits — for a seller account. Requires a sellerId + marketplace (use list_seller_profiles to discover them). Filter by types, asin/parent ASIN, brand, search, and a startDate/endDate range; sort with sortBy/sortOrder. Set includeCorrelations: true to attach the ranking/conversion impact per change. Returns a paginated list where each item has asin, title, imageUrl, date, type, contentType, description, previousValue, newValue, and (optionally) correlation, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Inputs: sellerId (required), marketplace (required), asin, brand, +9 more.

list_blind_spend_alertsList Blind-Spend (Wasted-Spend) AlertsA
Read-only
Inspect

Use this to find wasted PPC ad spend. Retrieves a paginated list of blind-spend alerts across the user's connected Amazon seller accounts — an alert flags ad spend on customer search terms that produced little or no sales. By default returns active (unresolved) alerts from the last 30 days; filter by sellerId, marketplace, status, or updatedSince (for incremental polling). Each item includes id, asin, title, imageUrl, sellerId, marketplace, lastAlertedAt, resolvedAt, wastedSpend (total ad spend across unresolved terms), totalKeywordCount, unresolvedKeywordCount, and searchTerms — the unresolved wasted-spend search terms, each with term, spend, sales, clicks, cvr (0-1), and impressions. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Inputs: status, pageSize, sellerId, currentPage, +2 more.

list_fast_keywordsList Fast Keywords RunsA
Read-only
Inspect

Use this first when the user asks about their Fast Keywords runs, or to find a fastKeywordsId for get_fast_keywords, get_fast_keywords_keywords or refresh_fast_keywords. Fast Keywords finds the keywords a product ranks for from just an ASIN, in minutes and for 1 Dive token, without a full niche dive. Lists the runs of the whole organization, newest request first: fastKeywordsId, asin, parentAsin, marketplace, status (in-progress, success or failed), title, brand, price, keywordCount, totalSearchVolume, top10OrganicRankCount, rootCount, lastRefreshedAt and requestedAt, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). Narrow with search or marketplace.

Inputs: search, pageSize, currentPage, marketplace.

list_indexing_issue_alertsList Indexing-Issue AlertsA
Read-only
Inspect

Use this to find products that may have lost search visibility. Retrieves a paginated list of indexing-issue alerts across the user's connected Amazon seller accounts — an alert fires when one of their ASINs is no longer indexed for its tracked keywords. By default returns active (unresolved) alerts from the last 30 days; filter by sellerId, marketplace, status, or updatedSince (for incremental polling). Each item includes id, asin, title, imageUrl, isParent, sellerId, marketplace, lastAlertedAt, and resolvedAt. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Inputs: status, pageSize, sellerId, currentPage, +2 more.

list_keyword_exclusionsList a Niche's Keyword ExclusionsA
Read-only
Inspect

Use this to see which keywords are hidden from a niche's Master Keyword List, e.g. when a keyword the user expects is missing from get_niche_keywords. Returns the same lists the DataDive web app shows, oldest first: exact — each entry hides the one keyword that matches it exactly, with that keyword's searchVolume (0 when the niche has no such keyword); phrase — each entry hides every keyword that contains the phrase, with excludedKeywordsCount and the total searchVolume of the keywords it hides (not counting ones already excluded exactly). Exclusions hide keywords wherever they come from: the dive, the Outliers and Residue lists, and hand-added ones. Change them with add_keyword_exclusions and remove_keyword_exclusions.

Inputs: nicheId (required).

list_labelsList LabelsA
Read-only
Inspect

Use this first when the user talks about labels, or to find the ids that add_niche_labels, remove_niche_labels and the labels filter of list_niches and list_rank_radars take. Returns the labels as a tree: each node has id, name, path (names from the root joined with /), parentId and children. Labels carry no access rights, so every label of the organization is listed. Niches carry the ids of their labels in spaces / labels on list_niches.

Inputs: no named parameters.

list_nichesList DataDive NichesA
Read-only
Inspect

Use this first when the user asks about their niches, or to find a nicheId for use with get_niche_keywords, get_niche_competitors, or get_ranking_juice. Retrieves a paginated list of Niches, newest dive first. Each Niche represents a market segment or product category being tracked. Returns nicheId, heroKeyword, nicheLabel, marketplace (com/uk/de/...), and latestResearchDate per niche, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). Narrow with searchText (label/keyword) or searchAsin (a competitor ASIN), spaces or labels (ids from list_spaces / list_labels) instead of scanning pages; each niche lists the ids of its spaces and labels. A page holds at most 50 niches, so the full list of a large account needs several calls.

Inputs: labels, spaces, orderBy, pageSize, +4 more.

list_ppc_campaignsList PPC Campaigns for a SellerA
Read-only
Inspect

Use this when the user asks about their Sponsored Products campaigns — which campaigns spend the most, which have a high ACOS, how placements (top of search, rest of search, product pages) perform, or which campaigns advertise a given product. Requires a sellerId + marketplace (use list_seller_profiles to discover them). Narrow to one product with asin, or to a variation family with parentAsin (not both). The reporting window defaults to the last 30 days and cannot exceed 90 days. Returns a paginated list where each campaign has campaignId, name, type, state, targetingType, bidStrategy, budget { type, amount, currencyCode }, window totals (impressions, clicks, ctr, cpc, cvr, spend, unitsSold, orders, sales, tosImpressionShare, acos, roas, tacos), asinCount and, unless includePlacements is false, placements; plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). To find the biggest spenders, sort with sortBy: "spend", sortOrder: "DESC" rather than paging through every campaign. Each call counts toward API usage and is rate limited (about 60 requests/minute). For per-keyword ad data of a Rank Radar, use get_rank_radar_ppc_data.

Inputs: sellerId (required), marketplace (required), asin, state, +9 more.

list_rank_radarsList Rank RadarsA
Read-only
Inspect

Use this to find a rankRadarId before calling get_rank_radar_data. Filter by nicheId if the user has already identified a niche, or by spaces / labels (ids from list_spaces / list_labels), which match through the Rank Radar's niche. Retrieves a paginated list of Rank Radars — keyword-rank trackers monitoring organic and sponsored positions for specific ASINs over time. Each item includes id, status (ACTIVE, PAUSED or ARCHIVED), asin, marketplace, keywordCount, title, imageUrl, and summary metrics: top10KW, top10SV, top50KW, top50SV. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev); a page holds at most 50 Rank Radars, so a large account needs several calls.

Inputs: labels, spaces, status, nicheId, +3 more.

list_rank_radar_tagsList Tags of a Rank RadarA
Read-only
Inspect

Use this to find a tagId before calling update_rank_radar_tag, delete_rank_radar_tag, add_rank_radar_tag_search_terms or remove_rank_radar_tag_search_terms. Returns the user tags ("highlights") on the specified Rank Radar, ordered by title (case-insensitive, ascending). Each row carries id, title, color, description, startAt, endAt, createdAt, and keywordCount — the number of Rank Radar keywords this tag is applied to. The system "paused" tag (the one the quota pauser writes with a reserved colour) is not listed and cannot be addressed from these tools. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev); a page holds at most 50 tags.

Inputs: rankRadarId (required), pageSize, currentPage.

list_seller_profilesList Connected Amazon Seller ProfilesA
Read-only
Inspect

Use this when the user asks which Amazon seller accounts are connected, or as the discovery step to find the sellerId and marketplace required by get_asin_inventory_distribution, get_seller_catalog, get_seller_listing_changes, and the alert tools. Returns a paginated list of the organization's connected seller profiles — each item has sellerId, sellerName, marketplace (e.g. "com", "co.uk"), hasAdApi (whether Advertising API credentials are connected), and createdAt — plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Inputs: pageSize, currentPage.

list_spacesList SpacesA
Read-only
Inspect

Use this first when the user talks about Spaces, or to find the ids that add_niche_spaces, remove_niche_spaces and the spaces filter of list_niches and list_rank_radars take. Returns the Spaces as a tree: each node has id, name, path (names from the root joined with /), parentId and children. An MCP user sees only the Spaces they have rights on, so a Space that is missing from the tree is one they cannot use. Niches carry the ids of their Spaces in spaces / labels on list_niches.

Inputs: no named parameters.

list_usageList Billable Usage LogsA
Read-only
Inspect

Use this when the user asks who consumed tokens, how their quota was spent, or wants an audit of billable activity over a date range. Retrieves a paginated list of billable feature usage logs for the organization — each entry is a token-consumption event (a dive, rank-radar creation, AI copywriter prompt, etc.). Filter by type (billable feature), search (user name/email), and startDate/endDate. Each item includes name, email, qty (tokens consumed), type, action (specific operation), nicheId/nicheName, rankRadarId, and date, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Inputs: type, search, endDate, pageSize, +2 more.

pause_rank_radarPause a Rank RadarA
Destructive
Inspect

Use this to pause tracking on a Rank Radar without losing anything — the action the DataDive API calls 'archiving', so when a user asks to archive a Rank Radar, this is the tool they mean. Tracking stops for all of its keywords and the Daily Tracked Keywords quota they held is freed for other Rank Radars, while the Rank Radar and its ranking history are kept. Fully reversible with resume_rank_radar, so it needs no confirm — prefer it over delete_rank_radar whenever the user may want the data back. Paused Rank Radars show up in list_rank_radars under status: PAUSED — not ARCHIVED, which covers Rank Radars removed with delete_rank_radar. Safe to repeat: pausing an already paused Rank Radar succeeds and changes nothing.

Inputs: rankRadarId (required).

pause_rank_radar_search_termsPause Search Terms of a Rank RadarA
Destructive
Inspect

Use this to stop tracking individual keywords on a Rank Radar while keeping the Rank Radar itself active — the way to trim a keyword set the user finds too broad. The DataDive API calls this 'archiving' the search terms; nothing is lost. The paused keywords keep their history and their Daily Tracked Keywords slots are freed for other keywords. Reversible with resume_rank_radar_search_terms, so it needs no confirm. Takes keyword ids, not keyword text: get them from get_rank_radar_data. Safe to repeat: already-paused terms are left unchanged.

Inputs: rankRadarId (required), rankRadarKeywordIds (required).

redive_nicheRe-dive an Existing NicheA
Destructive
Inspect

Use this to refresh an existing niche's research with current Amazon data, instead of creating a new niche with create_niche_dive. ⚠️ Spends dive tokens (one batch per ASIN dived) and cannot be undone — set confirm: true only after the user approves the cost. Not safe to retry: each call spends tokens again and starts a separate re-dive — if a call errors or times out, poll get_dive_status instead of re-calling. Two modes: same_competitors re-dives the niche's current competitor set (no other argument needed) and discover finds a fresh set, sized by numberOfCompetitors and steerable with heroAsin / lockedAsins / excludedAsins. Runs asynchronously: returns a diveId and an estimatedCompletionDate — poll get_dive_status with that diveId until it reports success. The niche keeps its nicheId, so existing rank radars and reports follow the refreshed data.

Inputs: mode (required), nicheId (required), confirm, heroAsin, +3 more.

refresh_fast_keywordsRefresh Fast KeywordsA
Destructive
Inspect

Use this to re-run an existing Fast Keywords result with current data. ⚠️ Spends 1 Dive token and cannot be undone. The first call checks eligibility and the Dive token balance, spends nothing and returns confirmation_required with tokenCost and hasEnoughTokens; call again with confirm: true only after the user approves. A result can be refreshed once every 24 hours, and not while a run is going: then the call fails with a message that says when it is refreshable again (or to poll get_fast_keywords), and nothing is charged. Not safe to retry after an error or timeout — check get_fast_keywords instead. Returns fastKeywordsId, requestId, status and estimatedCompletionDate; poll get_fast_keywords until status is success.

Inputs: fastKeywordsId (required), confirm.

remove_keyword_exclusionsRemove Keyword Exclusions from a NicheA
Destructive
Inspect

Use this to undo add_keyword_exclusions, so the keywords an exclusion hid show in the niche's Master Keyword List (get_niche_keywords) again. Pass the entries exactly as list_keyword_exclusions shows them, exact and phrase separately: removing a phrase does not touch an exact entry for the same text, and a keyword also hidden by another remaining exclusion stays hidden. Only the exclusions change — every other niche setting is kept. Send 1–100 entries in total across exact and phrase. Free, and safe to repeat: entries that are not excluded come back under unchanged. Returns removed, unchanged and the full exact / phrase lists after the change. Limited to 30 calls per minute per niche.

Inputs: nicheId (required), exact, phrase.

remove_niche_keywordsRemove Keywords from a Niche's Master Keyword ListA
Destructive
Inspect

Use this to undo add_niche_keywords: take keywords back out of a niche's Master Keyword List (MKL). Only keywords that were added to the MKL can be removed — get_niche_keywords shows each keyword's origin. What happens depends on that origin, and the response reports it per keyword: removedManual — added by hand (manual), deleted from the niche; sentBackToOutliers / sentBackToResidue — moved in from those lists (outlier / residue), listed there again with their data kept; notRemovable — found by the dive itself (mkl) or not in the niche, left unchanged. To hide a keyword the dive found, use add_keyword_exclusions instead. Free, and safe to repeat: a keyword already removed comes back under notRemovable. Adding a hand-added keyword back later re-dives the niche and costs Dive tokens if the niche is stale by then. Limited to 2 calls per minute per niche.

Inputs: nicheId (required), keywords (required).

remove_niche_labelsRemove Labels from a NicheA
Destructive
Inspect

Use this to take a niche out of one or more labels (ids from list_labels). Returns removed and notPresent. Undo with add_niche_labels. The same rights as the web app: the user needs Manage access to the niche, and to every Space added or removed. A refusal is a 403, so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

Inputs: nicheId (required), labelIds (required).

remove_niche_spacesRemove a Niche from SpacesA
Destructive
Inspect

Use this to take a niche out of one or more Spaces (ids from list_spaces). A Space controls who can see the niche, so adding or removing one changes access. Returns removed and notPresent. Undo with add_niche_spaces. The same rights as the web app: the user needs Manage access to the niche, and to every Space added or removed. A refusal is a 403, so tell the user instead of retrying. A change is all or nothing: if any id is unknown, or a Space is one the user has only view rights on, the whole call fails and nothing changes (the error lists the offending ids). Ids already in the wanted state are counted, never errors, so a repeat is safe. Costs nothing. Limited to 2 calls per minute per niche, so put every id in one call.

Inputs: nicheId (required), spaceIds (required).

remove_rank_radar_tag_search_termsDetach Search Terms from a Rank Radar TagA
Destructive
Inspect

Use this to remove keywords from a tag without deleting the tag itself. The tag keeps its title, colour and date window; only the keyword assignments listed are cleared. Reversible with add_rank_radar_tag_search_terms, so no confirmation is required. Idempotent: ids that are not currently attached are left unchanged, so re-sending the same ids after a timeout is safe. Up to 1000 ids per call — split larger batches into multiple calls. To remove the tag itself, use delete_rank_radar_tag. The system "paused" tag (reserved colour, written by the quota pauser) is not addressable: the API answers 404.

Inputs: tagId (required), rankRadarId (required), rankRadarKeywordIds (required).

resume_rank_radarResume a Paused Rank RadarA
Destructive
Inspect

Use this to restart tracking on a Rank Radar that was paused with pause_rank_radar (shown by list_rank_radars under status: PAUSED; a deleted, ARCHIVED one cannot be resumed). Keywords are resumed as far as the available Daily Tracked Keywords quota allows, most relevant first — so with a tight quota only part of the original keyword set comes back; check get_quota first if that matters. Reversible with pause_rank_radar, so it needs no confirm. Fails with a bad-request error when there is no quota left at all. Safe to repeat: resuming an already active Rank Radar changes nothing.

Inputs: rankRadarId (required).

resume_rank_radar_search_termsResume Paused Search Terms of a Rank RadarA
Destructive
Inspect

Use this to start tracking keywords again that were paused with pause_rank_radar_search_terms. Each resumed keyword takes back one Daily Tracked Keywords slot, and the call fails if the quota is exhausted — check get_quota first. Reversible with pause_rank_radar_search_terms, so it needs no confirm. Takes keyword ids, not keyword text: get them from get_rank_radar_data. Safe to repeat: already-active terms are left unchanged.

Inputs: rankRadarId (required), rankRadarKeywordIds (required).

run_fast_keywordsRun Fast KeywordsA
Destructive
Inspect

Use this to find the keywords a product ranks for from just its ASIN — in minutes, without a full niche dive. ⚠️ Spends 1 Dive token and cannot be undone. The first call checks eligibility and the Dive token balance, spends nothing and returns confirmation_required with tokenCost and hasEnoughTokens; call again with confirm: true only after the user approves. Not safe to retry: each confirmed call spends a token — if it errors or times out, check list_fast_keywords instead of re-calling. Returns fastKeywordsId, requestId, status and estimatedCompletionDate. Poll get_fast_keywords with the fastKeywordsId until status is success (right away when a fresh result for the same product already exists), then read the keywords with get_fast_keywords_keywords. To follow up with a full niche dive for the same product, pass the requestId to create_niche_dive as fastKeywordsRequestId. Run it again later with refresh_fast_keywords.

Inputs: asin (required), marketplace (required), confirm.

update_rank_radar_tagUpdate a Rank Radar TagA
Destructive
Inspect

Use this to change a tag's title, colour, description, or date window. Partial update: only the fields you pass are modified, the rest are left as they are. The system "paused" tag (reserved colour, written by the quota pauser) cannot be addressed from here — the API answers 404. Writing a tag costs nothing and is reversible, so no confirmation is required. Returns the updated tag row. Title clashes return 409 { error: 'TAG_TITLE_EXISTS', existingTagId }; the reserved colour returns 400; and endAt < startAt returns 400 (for whichever side the body omits, the comparison uses the stored value).

Inputs: tagId (required), rankRadarId (required), color, endAt, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 56 tools

    Disambiguation4/5

    Even in dense clusters (SQP vs PPC vs ranking data on a Rank Radar; MKL vs Outlier vs Residue keywords; labels vs spaces) the descriptions state explicitly which tool to use and cross-reference the alternatives. Near-pairs like add_niche_labels/add_niche_spaces and pause_rank_radar/delete_rank_radar are documented with the exact semantic difference ('archive' = pause). A few pairs still require careful reading (run_fast_keywords vs refresh_fast_keywords, create_niche_dive vs create_niche_dive_from_competitors_list), so not perfect, but boundaries are clear.

    Naming Consistency4/5

    Overwhelmingly consistent snake_case verb_noun: list_*, get_*, create_*, add_*, remove_*, pause_*, resume_*, delete_*. Minor deviations: redive_niche (object-first) sits awkwardly beside create_niche_dive, and run_/refresh_fast_keywords use different verbs for the same resource family than the niche equivalents.

    Tool Count2/5

    56 tools is a very large surface, well beyond the 3-15 sweet spot, and several groups could be consolidated (the six rank-radar tag tools, the four add/remove label/space tools). The domain is genuinely broad (niches, dives, keywords, rank radars, PPC, inventory, alerts, quota, copywriting), which explains the size, but the sprawl still raises selection cost for an agent.

    Completeness4/5

    Coverage across the analytics lifecycle is strong: niche creation/re-dive/deletion, keyword list curation with exclusions, rank-radar creation, pause/resume/delete, tagging, PPC/SQP/ranking data, inventory, catalog, alerts and quota. Gaps remain: no update/rename for a niche, alerts are read-only (no resolve/dismiss tool), and inventory is single-ASIN only with no way to list at-risk ASINs.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers