Skip to main content
Glama
Data-Dive-Tools

DataDive MCP

Official
by Data-Dive-Tools
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

List PPC Campaigns for a Seller

list_ppc_campaigns
Read-only

Pull Sponsored Products campaign data for a seller and marketplace to compare spend, ACOS, placements, and product-level performance, with filtering and sorting.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
asinNoOnly campaigns advertising this ASIN. Cannot be combined with parentAsin.
stateNoOnly ENABLED or only PAUSED campaigns. Omit for both.
searchNoPartial match on campaign name or advertised ASIN. At least 3 characters.
sortByNoSort field. Defaults to "name". Any of name, state, bidStrategy, budget, impressions, clicks, ctr, cpc, spend, unitsSold, sales, acos, cvr, tosImpressionShare. The placement fields (e.g. "tosSpend", "tosAcos", "ppBidAdjustment") are only accepted when includePlacements is not false.
endDateNoEnd of the reporting window, ISO-8601. Defaults to now. At most 90 days after startDate.
pageSizeNoCampaigns per page (max 50). Defaults to 20.
sellerIdYesAmazon seller account ID. Get it from `list_seller_profiles`, or find it on the Connections page at https://2.datadive.tools.
sortOrderNoSort direction. "ASC" (default) or "DESC".
startDateNoStart of the reporting window, ISO-8601. Defaults to 30 days before endDate.
parentAsinNoOnly campaigns advertising any ASIN of this variation family. Cannot be combined with asin.
currentPageNoPage number, 1-indexed. Defaults to 1.
marketplaceYesAmazon marketplace code, e.g. "com" for amazon.com or "co.uk" for amazon.co.uk.
includePlacementsNoInclude the per-placement breakdown (topOfSearch, restOfSearch, productPage, offAmazon, each with its bid adjustment). Defaults to true; set false for a smaller response when placements are not needed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.16.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint. The description adds the operational context that matters: ~60 requests/minute rate limit, each call counting toward API usage, a 30-day default window capped at 90 days, pagination semantics, and the includePlacements toggle affecting both response size and which sort fields are accepted.

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 use case before requirements and output details, and almost every sentence carries non-redundant information. It is a dense single block, though, and the long enumeration of returned metrics could be trimmed since much of it is inferable.

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?

No output schema exists, so the description compensates by enumerating the returned campaign fields and pagination metadata. Together with prerequisites, window limits, rate limits, and filter exclusivity, an agent has everything needed to call it correctly.

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 schema already documents all 13 parameters; the baseline would be 3. The description still adds value by stating the asin/parentAsin mutual exclusion, the default reporting window, and a concrete sort recipe (sortBy: "spend", sortOrder: "DESC") that the schema alone does not suggest.

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 (list Sponsored Products PPC campaigns for a seller) plus the concrete questions it answers (top spenders, high ACOS, placements, campaigns advertising a product). It also distinguishes itself from the closest sibling by naming get_rank_radar_ppc_data as the per-keyword alternative.

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 about when to use it (user questions about Sponsored Products campaigns), prerequisites (sellerId + marketplace from list_seller_profiles), and where it stops (per-keyword ad data belongs to get_rank_radar_ppc_data). It also gives a routing heuristic for the common 'biggest spenders' question instead of paging everything.

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