Skip to main content
Glama

Nova Amazon MCP Server

query_dsp

Read-only

AMAZON DSP: the seller's Amazon DSP (Demand-Side Platform) advertising, Amazon's PROGRAMMATIC display and video ads bought in the DSP console: banners and video on Amazon's own sites and devices (its stores, Fire TV, Twitch...) and on third-party sites and apps, bought by audience rather than by keyword and billed per line item. It is NOT Sponsored ads: Sponsored Products / Brands / Display are the search-and-browse PPC that query_advertising serves. Separate budgets, separate consoles, separate attribution: a DSP conversion is counted post-click AND post-view over 14 days (a shopper who saw the ad and bought later counts), where PPC conversions are click-attributed. So NEVER add DSP spend to PPC spend, never add DSP sales to PPC sales, never compute one ACOS or ROAS across the two, and never compare a DSP ROAS with a PPC ROAS. In the app, the Advertising filter has three channels read side by side, PPC, Creator Connections and DSP; the P&L line 'Amazon DSP' (dspCost, under Advertising Cost) is this spend allocated to products, which query_metrics serves. Use query_dsp for anything about the DSP: what it costs, what it drives, which advertiser / order / line item / product / inventory / device / creative / audience / country, whether a line item is running; use query_advertising for Sponsored ads, query_metrics for advertising totals in the P&L. WHO IS READ: the DSP advertisers LINKED to the accounts of this call (Nova links each DSP advertiser to one of the seller's accounts, Seller Central or Vendor Central); accounts narrows them. History: Amazon's DSP reports reach back about 95 days, so an advertiser's figures start about 95 days before its connection to Nova; an earlier period comes back empty, never as zero spend. When no DSP advertiser is linked to the accounts, the answer says so (dspAdvertisers: 0, a notice, no rows): it is not an error, the seller does not run Amazon DSP through Nova. level (REQUIRED) picks the row: 'advertiser' (one per linked DSP advertiser), 'order' (a DSP campaign, with its budget, flight dates, pacing and Amazon's reach to date, household reach and frequency in attrs, as of the latest closed month), 'lineItem' (the grain Amazon bills, with its current status, type, budget and flight dates), 'product' (per ASIN, conversions only: Amazon reports no cost per ASIN), 'supplyFamily' and 'supplySource' (where the ads ran), 'device' (the screen), 'creative' (the ad asset), 'audience' (the segments reached: NOT additive, segments overlap), 'country' (where the ads served; the row with id '' is Unattributed). Each level is one of Amazon's DSP reports with its own metric universe, and the answer's levelNote says in one sentence what its rows are and what may be added across them: relay it whenever it qualifies the figures. Start at 'advertiser' or 'lineItem' for totals (no time grain here: a trend is several periods, one call each); the partitions (supply, device, creative, country) re-add to the line items; 'audience' is read beside them, never summed. Rows come biggest first on the first metric of the call unless sortBy says otherwise, and a row stays while it spent or sold over the period (sold, at 'product'), whatever metrics asks: the page's own population. METRICS are a SEPARATE universe from list_metrics and from query_advertising (same spellings, different meanings): spend (the total cost: supply cost plus every fee), supplyCost, fees, audienceFee, consoleFee, agencyFee, thirdPartyFees, impressions, viewableImpressions, viewabilityRate, clicks, ctr, ecpm, detailPageViews, dpvr, ecpdpv, addToCart, addToCartViews, addToCartClicks, atcr, purchases, unitsSold, sales (the PROMOTED products' conversions), totalPurchases, totalUnitsSold, totalSales (the promoted products plus the brand halo), purchaseRate, ecpp, newToBrandPurchases, newToBrandUnitsSold, newToBrandSales, newToBrandShare, totalNewToBrandPurchases, totalNewToBrandUnitsSold, totalNewToBrandShare, roas (promoted sales over spend), totalRoas (total sales over spend). Each level serves the subset its report carries: a key outside it is refused with the keys the level serves (no spend, impressions or ROAS at 'product'; no sales, units or halo at 'audience'; newToBrandSales and the four fee lines read on the 'advertiser', 'order' and 'lineItem' levels, the other reports carry fewer of them). Omit metrics for the level's core: spend, impressions, clicks, purchases, sales, totalSales, roas (the conversions at 'product'; no sales at 'audience'). FILTERS, on every level: dspAdvertiserIds, dspOrderIds, dspLineItemIds (the ids the upper levels return, strings), lineItemStatuses (the CURRENT status of the line items the rows belong to: RUNNING, PAUSED_BY_USER, ENDED, the DSP page's Status chip, Running / Paused / Ended), marketplaces. The level's own: asins and promoted ('product'), supplyFamilies and supplySources ('supplyFamily', 'supplySource'), deviceTypes ('device'), creativeIds and creativeTypes ('creative'), segmentIds, segmentClassCodes and targetingMethods ('audience'), countries ('country', '' allowed for the unattributed row). A filter of another level is refused by name. ANSWER: data rows with key (the level's type and id), attrs (the row's name and the level's attributes), metrics (value, and compared_value / variance with a comparison period); summary (total, mean and count over the whole selection before limit; the count only on 'audience'); level, levelNote, dspAdvertisers (the linked advertisers in scope), period and the reporting currency. 💱 CURRENCY: monetary values are served in the caller's Nova display currency when it is one of the organization's configured currencies (its primary or up to four secondary currencies), else in the organization's primary. In the response, currency is the code, currencyBasis says why (user_preference | organization | pinned) and currencyNotice, when present, MUST be relayed to the user. Quote the code; never assume a symbol from the marketplace. Pass currency to pin any configured code — e.g. to reproduce a figure the seller read on a dashboard set to another currency.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "level": "<level>",
      "from": "<from>",
      "to": "<to>"
    },
    "name": "query_dsp"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesPeriod end, INCLUSIVE (YYYY-MM-DD): a calendar month is from=YYYY-MM-01 to=its LAST day. to=the 1st of the next month adds one extra day to every total (and one extra bucket with a time grain).
fromYesPeriod start, INCLUSIVE (YYYY-MM-DD).
asinsNoLevel 'product' only: the ASINs.
levelYesThe row of the answer, one of Amazon's DSP reports: advertiser | order | lineItem | product | supplyFamily | supplySource | device | creative | audience | country. Each has its own metric universe and its own filters (see the description).
limitNoRows per call, 1 to 1000 (default 50); `summary` covers the whole selection.
reasonNoOne sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used.
sortByNoDSP metric key of the level to rank rows by (e.g. "spend"), biggest first by default. Omitted: the first metric of the call (spend when `metrics` is omitted; the purchases at 'product'), biggest first, so `limit` keeps the biggest rows.
metricsNoDSP metric keys (spend, impressions, clicks, purchases, sales, totalSales, roas, newToBrandPurchases, ...): NOT list_metrics keys, NOT query_advertising keys. Omit for the level's core. A key the level's report does not carry is refused with the keys it serves.
accountsNoRestrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id.
currencyNoPin the reporting currency: one of the organization's configured codes — its primary or any of its secondary currencies (e.g. "USD"). Omit to follow the caller's Nova display currency, the dashboard's rule. Any other code is refused.
promotedNoLevel 'product' only: true = the rows where a line item promoted the product, false = its brand-halo rows only. Omit for both.
countriesNoLevel 'country' only: countries by name, as Amazon spells them (France, United States, Germany...); '' selects the unattributed row.
sortFieldNoWhat to rank on: 'value' (default), or 'variance' / 'variancePercentage' (need a comparison period).
sortOrderNodesc (default) = biggest first.
segmentIdsNoLevel 'audience' only: audience segment ids (Amazon's segmentId, as strings).
creativeIdsNoLevel 'creative' only: DSP creative ids (strings), as the level returns them.
deviceTypesNoLevel 'device' only: device types by name, as Amazon spells them (Phone, PC, Tablet, ConnectedDevice, SetTopBox, Unknown, Unallocated).
dspOrderIdsNoDSP order ids (strings), as level 'order' returns them.
comparisonToNoBaseline period end (inclusive).
marketplacesNoMarketplace IDs.
creativeTypesNoLevel 'creative' only: creative types by name, as Amazon spells them (Responsive eCommerce, image, video..., Unallocated).
supplySourcesNoLevels 'supplyFamily' / 'supplySource' only: supply sources by name, as Amazon spells them (AMAZON.FR, Magnite DV+...).
comparisonFromNoBaseline period start (inclusive) — enables variance.
dspLineItemIdsNoDSP line item ids (strings), as level 'lineItem' returns them.
supplyFamiliesNoLevels 'supplyFamily' / 'supplySource' only: supply families by name (Amazon, Amazon Publisher Services, Third-party exchanges, Unallocated).
dspAdvertiserIdsNoDSP advertiser ids (Amazon's 18-digit ids, as strings), as level 'advertiser' returns them.
lineItemStatusesNoThe CURRENT status of the line items the rows belong to (the status on the latest day Amazon reported each one, whatever the period): the DSP page's Status chip, Running / Paused / Ended. Omit for every line item.
targetingMethodsNoLevel 'audience' only: how the line item met the segment, behavioral (targeted) or untargeted (reached anyway).
segmentClassCodesNoLevel 'audience' only: segment class codes, as Amazon spells them (BEHAVIOR, INVENTORY...).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare a safe read; the description adds the behaviour that actually matters: ~95-day history so earlier periods return empty rather than zero, `dspAdvertisers: 0` plus a `notice` is not an error, the audience level is non-additive, rows persist while they spent or sold regardless of `metrics`, one level's metric/filter is refused with the served keys by name, and the currency basis/notice must be relayed. That is well beyond what the annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the PPC-vs-DSP warning are correctly front-loaded, and nearly every sentence carries operational information. But the text sprawls into a very long single block with ALL-CAPS clauses and long metric enumerations that partly duplicate the schema, making it harder to scan for the one detail the agent needs at call time.

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?

Given 29 parameters and no output schema, the description carries the full burden and does so: it documents the response shape (`data` rows with key/attrs/metrics, `summary` semantics, `level`, `levelNote`, `dspAdvertisers`, `period`, `currency`), the meaning of levelNote, the empty-result case, and currency resolution. Nothing required to call or interpret the result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description still adds real meaning: the full DSP metric universe and the level's default core metric set, which filters belong to which level, that `lineItemStatuses` is the CURRENT status on the latest reported day rather than a period filter, the `sortBy` default falling back to the first metric, and `''` selecting the Unattributed country row. These details let an agent choose parameters correctly, not just syntactically.

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?

The opening sentence names the exact resource (Amazon DSP programmatic display/video) together with what it is not, and explicitly routes Sponsored Products/Brands/Display to query_advertising and P&L advertising totals to query_metrics. An agent can distinguish it from every sibling without opening a schema.

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?

It gives explicit when-to-use ("anything about the DSP: what it costs, what it drives, which advertiser/order/line item...") and when-not (Sponsored ads, P&L totals), and names both alternatives. It even states which level to start with ('advertiser' or 'lineItem' for totals) and warns against cross-channel arithmetic.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.