Skip to main content
Glama
Data-Dive-Tools

DataDive MCP

Official
by Data-Dive-Tools
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

List DataDive Niches

list_niches
Read-only

Retrieve a paginated, filterable list of tracked market niches to find niche IDs for keyword, competitor, and ranking queries.

Instructions

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.

Input Schema

NameRequiredDescriptionDefault
labelsNoOnly niches with at least one of these labels (ids from `list_labels`, up to 100). Combines with `spaces` and the other filters with AND.
spacesNoOnly niches in at least one of these Spaces (ids from `list_spaces`, up to 100). Combines with `labels` and the other filters with AND.
orderByNoSort field: `lastDived` (by latestResearchDate, newest first by default) or `name` (by nicheLabel, A→Z by default). Defaults to `lastDived`.
pageSizeNoItems per page (max 50). Defaults to 20.
sortOrderNoSort direction. Defaults to DESC for `lastDived` and ASC for `name`.
searchAsinNoOnly niches whose competitor set contains this ASIN (10 characters, e.g. B08N5WRWNW).
searchTextNoCase-insensitive partial match on the niche label or hero keyword. Prefer this over paging through everything when the user names a niche.
currentPageNoPage number, 1-indexed. Defaults to 1. Keep requesting the next page while `hasNext` is true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.20.1
    • addedInput schema / properties / labels
      Added value: +{
+  "description": "Only niches with at least one of these labels (ids from `list_labels`, up to 100). Combines with `spaces` and the other filters with AND.",
+  "items": {
+    "minimum": 1,
+    "type": "integer"
+  },
+  "maxItems": 100,
+  "type": "array"
+}
    • addedInput schema / properties / spaces
      Added value: +{
+  "description": "Only niches in at least one of these Spaces (ids from `list_spaces`, up to 100). Combines with `labels` and the other filters with AND.",
+  "items": {
+    "minimum": 1,
+    "type": "integer"
+  },
+  "maxItems": 100,
+  "type": "array"
+}
  2. Changed5 schema fields changedv0.12.0
    • changedInput schema / properties / currentPage / description
      Previous value: -"Page number, 1-indexed. Defaults to 1."New value: +"Page number, 1-indexed. Defaults to 1. Keep requesting the next page while `hasNext` is true."
    • addedInput schema / properties / orderBy
      Added value: +{
+  "description": "Sort field: `lastDived` (by latestResearchDate, newest first by default) or `name` (by nicheLabel, A→Z by default). Defaults to `lastDived`.",
+  "enum": [
+    "lastDived",
+    "name"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / searchAsin
      Added value: +{
+  "description": "Only niches whose competitor set contains this ASIN (10 characters, e.g. B08N5WRWNW).",
+  "pattern": "^[A-Za-z0-9]{10}$",
+  "type": "string"
+}
    • addedInput schema / properties / searchText
      Added value: +{
+  "description": "Case-insensitive partial match on the niche label or hero keyword. Prefer this over paging through everything when the user names a niche.",
+  "maxLength": 200,
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / sortOrder
      Added value: +{
+  "description": "Sort direction. Defaults to DESC for `lastDived` and ASC for `name`.",
+  "enum": [
+    "ASC",
+    "DESC"
+  ],
+  "type": "string"
+}
  3. Changed2 schema fields changedv0.11.0
    • changedInput schema / properties / pageSize / description
      Previous value: -"Items per page (max 100). Defaults to 20."New value: +"Items per page (max 50). Defaults to 20."
    • changedInput schema / properties / pageSize / maximum
      Previous value: -100New value: +50
  4. First observedv0.8.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations only supply readOnlyHint=true, so the description carries most of the behavioral burden — and it does: page cap of 50, the need for several calls on a large account, newest-dive-first ordering, the exact returned fields, and pagination metadata including `hasNext`. It doesn't mention auth, rate limits, or errors, which keeps it short of a 5.

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 the primary use case and the id-passing rationale, then filtering, then return shape and pagination. Dense but every sentence carries information; the explicit field list is justified because there is no output schema. Slightly long, but not padded.

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?

For an eight-parameter, zero-required list tool with no output schema and only a readOnly annotation, the description covers use case, filtering strategy, ordering, return fields, and pagination mechanics. An agent has everything needed to call it and to know when the results are incomplete.

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, but the description adds cross-tool meaning: `spaces`/`labels` take ids from `list_spaces`/`list_labels`, `searchAsin` is a competitor ASIN, and `searchText` matches label or keyword. That's genuine semantic value beyond the already-documented schema.

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?

States a specific verb and resource ('Retrieves a paginated list of Niches') with scope ('newest dive first') and defines what a Niche is ('a market segment or product category being tracked'). It also distinguishes itself from siblings by naming the three tools that consume its `nicheId`.

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?

Explicitly says 'Use this first when the user asks about their niches' and names the downstream tools that need the resulting `nicheId`. It also gives a when-not-to-page rule: 'Narrow with `searchText`... instead of scanning pages.' Alternatives and conditions are both covered.

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

Deploy Server

Other Tools