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. 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).

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 }). Also returns the latestResearchDate.

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.

Use this for competitor ASINs, 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, sales, revenue, ratings, reviews, price, image URL, and ranking data.

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.

Use this to find a rankRadarId before calling get_rank_radar_data. Filter by nicheId if the user has already identified a 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, asin (with id, krtId, asin), marketplace, keywordCount, title, imageUrl, and summary metrics: top10KW, top10SV, top50KW, top50SV. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).

Use this to analyze keyword ranking trends over time. Requires startDate and endDate (yyyy-mm-dd). Retrieves historical keyword ranking data for the specified Rank Radar within the date range. Returns an array of tracked keywords; each has id, keyword, searchVolume, ranks (per-day { date, organicRank, impressionRank }), and any highlight annotations. Use after list_rank_radars to discover a rankRadarId.

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. Returns the new rankRadarId; read its data later with get_rank_radar_data. Requires asin, numberOfKeywords (min 1), and a nicheId from list_niches.

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. 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).

Use this to poll a niche dive started with create_niche_dive until it finishes. Returns one of three shapes keyed by status: in_progress (with estimatedCompletionDate), success (with the new 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. Re-poll periodically — dives can take minutes; the estimatedCompletionDate hints at when to check.

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).

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). 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).

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).

Use this when the user asks about inventory levels, stock by fulfillment center, or where their units are sitting across Amazon's fulfillment network for a specific ASIN. 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 totalSellableUnits and a per-FC distribution array (fc, state, availableStock, availableStockPercentage). lastUpdatedAt may be null when no successful inventory ingestion has occurred in the last 30 days.

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).

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).

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.

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).