Skip to main content
Glama

Nova Amazon MCP Server

query_search_terms

Read-only

The actual customer SEARCH QUERIES behind Sponsored Products and Sponsored Brands spend — the search-term report, same pipeline as the app (Sponsored Display and Full-Funnel have no search-term report: asking for either is refused by name). Answers: what customers really type before clicking an ad, negative-keyword candidates (queries with spend and zero sales), auto-campaign discoveries worth promoting to exact match. groupBy="searchTerm" is the main drill-down; the ad product (adProduct), ad-structure grains (portfolio/campaign/adGroup/targetingType/targetingDetail/keyword) and TIME grains also work. Metric universe = the ads keys MINUS impressions/ctr (biased at this grain, rejected) and MINUS the seven brand keys (newToBrand*, videoCompleteViews, viewableImpressions, brandedSearches, topOfSearchImpressionShare — the search-term reports carry none of them) and MINUS the four profit keys (this grain carries no ASIN, so there is no product margin to price a query at — use query_advertising for those): spend, sales, sales14d, clicks, orders, units, units14d, acos, roas, cpc, cvr. NO product (ASIN/SKU) dimension or filter exists here — the search-term report carries no ASIN attribution; for per-product ads use query_advertising. Rows with search term '*' are PDP placements with no typed query. ⚠️ groupBy="searchTerm" serves CLICKED QUERIES ONLY: a query with 0 clicks over the requested period is not served, and rows, summary.count and summary.total all follow that rule (Amazon also emits 0-click / 0-spend rows carrying attribution-window sales; they used to top every ACOS-ascending sort at a fake 0.0%). It is a PERIOD rule, not a daily one — a query clicked on one day keeps the sales its other days attribute. ACOS is null, never 0, when nothing was spent. 🚫 Each searchTerm row carries attrs.negatedLevel ('campaign' | 'ad_group' | null): a keyword negative on that EXACT text already blocking the traffic THIS row is made of — a campaign the row spent in, or an ad group it spent in. A negative in a SIBLING ad group is NOT reported: the query is still costing money where you are looking. Expect it to be null almost everywhere and do not read that as "nothing is blocked" — a negative that works stops the query being served, so it leaves this report entirely; what lights up is a query negated DURING the period. For "have I ever blocked this anywhere", use list_negative_targets with q = the term. ⚠️ Never cross-sum with query_metrics' ad metrics. 🧭 AD PRODUCTS: the console serves Sponsored Products, Sponsored Brands, Sponsored Brands Video, Sponsored Display and Full-Funnel campaigns as DISJOINT blocks of rows — adProducts picks which (default ['sponsored_products'] until the fact serves the others; pass several to read them in ONE call, or groupBy='adProduct' to split the money by product). Each block is read from its own cut of the fact at its OWN attribution window: SP orders/sales/units are 7-day on a Seller Central account and 14-day on a Vendor Central account (each console's own window), SB and SBV 14-day, SD 14-day after a click OR a view, as Amazon's console counts them (the *14d metrics keep the clicks alone) — so never sum or compare sales, orders, ACOS or ROAS across products; spend is the ONE additive column across all of them, sponsored_brands + sponsored_brands_video (one report, split per row) the ONE additive pair, and sales14d / units14d the like-for-like 14-day reading. Sponsored Display has no search-term and no placement report (such a call is refused by name). Entity rows carry attrs.adProduct; it is null on a VALUE row (an ASIN, a placement, a targeting type, a search term) that folds two products. 🎯 FULL-FUNNEL ('full_funnel'): Amazon's Full-Funnel campaigns, ONE campaign serving on Amazon, off Amazon and on streaming video. Read them in total, over time, by campaign, or by product (childAsin / sku / parentAsin: the spend Amazon reports on no product, streaming video mostly, is one row with no ASIN, so the products re-sum to the campaign). They have no ad group, no keyword or target, no search term and no placement of this console: those grains and filters are refused by name. Their sales / orders / units are EVERY sale Amazon attributes to the campaign, the promoted products and the rest of the brand together, at a window Amazon does not state; sales14d / units14d, the profit keys, newToBrandUnits, viewableImpressions, brandedSearches and topOfSearchImpressionShare come back null with an unservedMetrics note, while newToBrandOrders, newToBrandSales and videoCompleteViews are served. A campaign Amazon's weekly report has not named yet reads its id without a name, and their current day is as of Nova's last hourly build, not the live stream. The P&L counts the same campaigns' cost as fullFunnelCost (query_metrics), where the part on no product is shared among the campaign's products. 💱 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": {
      "metrics": "<metrics>",
      "from": "<from>",
      "to": "<to>"
    },
    "name": "query_search_terms"
  }
}

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).
limitNoRows per call of an entity grouping, 1 to 1000 (default 50). A time grain is never cut: its series comes whole, in date order, 1000 buckets at most.
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.
sortByNoMetric key of THIS universe to rank rows by (e.g. "spend"). Refused with a time grain: a series comes in date order.
groupByNosearchTerm (the main drill-down), the ad product (adProduct), an ad-structure grain (portfolio/campaign/adGroup/targetingType/targetingDetail/keyword), or a time grain. Omit for a single total row.
metricsYesADS metric keys minus impressions/ctr and minus the profit keys — NOT product keys from list_metrics.
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.
channelsNoONE Amazon programme per call. 'SELLER' = Seller Central (3P) advertising: the seller's own Amazon Ads campaigns. 'VENDOR' = Vendor Central (1P) advertising: the campaigns of the vendor's own Amazon Ads profile. Omit = SELLER whenever the accounts of the call include a Seller Central account, else VENDOR. Pass ['VENDOR'] only when the user asks about Vendor Central / 1P advertising. Both at once is refused: 3P and 1P spend and sales are never added into one total.
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.
sortFieldNoWhat to rank on: 'value' (default), or 'variance' / 'variancePercentage' (need a comparison period).
sortOrderNodesc (default) = biggest first.
adGroupIdsNo
adProductsNoWhich ad products to read, as disjoint blocks: sponsored_products, sponsored_brands, sponsored_brands_video, sponsored_display, full_funnel (Amazon's Full-Funnel campaigns: by campaign or by product only). Default ['sponsored_products'] until the fact serves the others. Each has its own attribution window and history floor — see the AD PRODUCTS note.
keywordIdsNo
campaignIdsNo
searchTermsNoExact customer queries to keep (identity filter).
comparisonToNoBaseline period end (inclusive).
marketplacesNoMarketplace IDs.
portfolioIdsNoPortfolio ids.
metricFiltersNoServer-side threshold filters (ANDed) — e.g. spend > 20 AND sales < 1 for negative-keyword candidates. Needs an entity grouping.
comparisonFromNoBaseline period start (inclusive) — enables variance.
targetingTypesNoe.g. keyword, auto, product, category.
targetingDetailsNo
excludeUnfinishedNoExclude the current, still-incomplete period so a partial day/week/month is not read as a drop.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / adProducts / description
      Previous value: -"Which ad products to read, as disjoint blocks: sponsored_products, sponsored_brands, sponsored_brands_video, sponsored_display. Default ['sponsored_products'] until the fact serves the others. Each has its own attribution window and history floor — see the AD PRODUCTS note."New value: +"Which ad products to read, as disjoint blocks: sponsored_products, sponsored_brands, sponsored_brands_video, sponsored_display, full_funnel (Amazon's Full-Funnel campaigns: by campaign or by product only). Default ['sponsored_products'] until the fact serves the others. Each has its own attribution window and history floor — see the AD PRODUCTS note."
    • changedInput schema / properties / adProducts / items / enum
      Previous value: -[
      -  "sponsored_products",
      -  "sponsored_brands",
      -  "sponsored_brands_video",
      -  "sponsored_display"
      -]New value: +[
      +  "sponsored_products",
      +  "sponsored_brands",
      +  "sponsored_brands_video",
      +  "sponsored_display",
      +  "full_funnel"
      +]
  2. Changed1 schema field changed
    • changedInput schema / properties / portfolioIds / description
      Previous value: -"Portfolio ids — needs the stacked-cut ads fact (ADS_FACT_ENABLED)."New value: +"Portfolio ids."
  3. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Far exceeds the readOnly/destructive annotations: it discloses the clicked-queries-only period rule for served rows, that ACOS is null not 0, what `attrs.negatedLevel` means and why it is usually null, per-ad-product attribution windows and why cross-product sums are invalid, full-funnel null-metric behavior, and the currency/currencyNotice relay obligation. These are exactly the behaviors an agent could not derive from structured fields.

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?

The purpose and the pointer to query_advertising are front-loaded, which is good, but the body is a very dense multi-paragraph wall of caveats with heavy emoji/symbol markers. For a 25-parameter tool much of it earns its place, yet the volume of full-funnel and currency detail makes it hard to scan and pushes the core 'what and when' far from the details an 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?

For a 25-parameter, no-output-schema tool, the description covers grain selection, metric universe, attribution windows, refusal behavior, response attributes (`attrs.negatedLevel`, `summary.count`, `currencyNotice`) and the cross-tool boundaries. Nothing an agent needs in order to call it correctly appears missing.

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 already 84%, so the baseline is 3; the description still adds real meaning on top, explaining that `adProducts` selects disjoint blocks with different attribution windows, that `metrics` excludes impressions/ctr, the seven brand keys and the four profit keys (the schema only says 'ADS metric keys minus impressions/ctr'), and how `currency` pinning resolves. It does not walk every parameter, but the high-value ones are covered.

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 first sentence names the specific resource ('the actual customer SEARCH QUERIES behind Sponsored Products and Sponsored Brands spend — the search-term report') and the main drill-down grain (`groupBy="searchTerm"`). It explicitly separates itself from siblings: query_advertising for per-product ads, query_metrics for ad metrics, list_negative_targets for lifetime negative history.

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?

Gives concrete use cases (negative-keyword candidates = spend with zero sales, auto-campaign discoveries to promote to exact match) and explicit exclusions ('NO product dimension... use query_advertising', 'Never cross-sum with query_metrics', 'for have I ever blocked this anywhere, use list_negative_targets'). It also states which ad products are refused by name, so the agent knows not to attempt them.

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.