tool4seller-mcp

Query advertising targets

query_advertising_targets

Read-only

Queries advertising keyword, explicit ASIN, product-category, automatic theme, or keyword-group theme target performance, including current targets with zero traffic in the date range. Product-scoped historical keyword or explicit-ASIN results can provide evidence for targeting candidates when a manual AD_STRUCTURE_CREATE draft lacks positive targeting. Average CPC is a historical bid reference, not an Amazon suggested bid; show supporting metrics and obtain customer approval before reusing a target or bid. dimension/values provide product scope; filters enables store-level target attribute and aggregated metric search and cannot be combined with product scope. When the user specifies a supported attribute or metric condition, pass it through filters in the first call; do not retrieve unfiltered pages and filter locally. Paginate only the filtered result. Query results can proceed to AD_TARGETING_CHANGE for bid or ENABLED/PAUSED state changes. Enabled and paused positive Targets can change bids without enabling them first; archived entities are not writable. MCP reporting and workflow metric date ranges use yyyy-MM-dd and include both startDate and endDate, with at most 95 calendar days per range. For longer read-only reports, split into non-overlapping windows: endDate = startDate plus 94 days, capped at the requested end date; the next startDate is the previous endDate plus 1 day. Apply the same limit independently to comparison ranges. Do not average ratios such as ACOS or ROAS across windows; recompute them from summed base metrics. Do not automatically split advertising write plans or metric-based selectors; obtain a supported analysis window from the user. Keyword ranking trends have separate limits: DAILY supports up to 90 inclusive days and RAW up to 31 inclusive days. For keyword ranking trends, use these interval-specific limits when splitting read-only reports. This reporting limit does not apply to campaign scheduling dates.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of items to return. Defaults to 100 and cannot exceed 100.
`offset`	No	Zero-based pagination offset.
`sortBy`	No	Advertising performance sort field.
`values`	No	Optional product scope values for historical targeting candidate lookup. Do not combine with filters.
`endDate`	Yes	End business date in yyyy-MM-dd format. Date range is inclusive and can contain at most 95 days. For longer read-only reports, use non-overlapping windows of up to 95 days.
`filters`	No	Store-level target attribute and aggregated metric filters. When the user supplies a supported condition, use filters in the first request instead of scanning unfiltered pages; paginate only the filtered response. Do not combine with dimension or values.
`storeId`	Yes	Store ID from the Stores API, formatted as sellerId:marketplaceId.
`dimension`	No	Optional product scope dimension for historical targeting candidate lookup. Do not combine with filters.
`searchKey`	No	Optional target search text.
`sortOrder`	No	Sort order.
`startDate`	Yes	Start business date in yyyy-MM-dd format. Date range is inclusive and can contain at most 95 days. For longer read-only reports, use non-overlapping windows of up to 95 days.
`targetType`	Yes	Target report type. asinTarget includes explicit ASIN targets, product-category targets, automatic targeting themes, and keyword-group themes.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, so the description is free to add the operational context that matters: zero-traffic targets are still returned, archived entities are not writable, enabled/paused positives can change bids without re-enabling, and average CPC is a historical reference rather than an Amazon suggested bid requiring customer approval. These are real behavioral traits not derivable from the schema or annotations.

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 scope are correctly front-loaded, but a large trailing block restates date-window mechanics (yyyy-MM-dd, 95 days, endDate = startDate + 94, comparison ranges) that the startDate/endDate schema descriptions already carry verbatim. The keyword-ranking-vs-reporting limit split and the 'do not average ratios' rule are useful, but the section is long enough that the actionable routing guidance is diluted.

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?

An output schema exists, so return values are covered elsewhere; given that, the description supplies everything an agent needs to call it correctly — required date format and window limits, pagination-plus-filter interaction, scope exclusivity, and the follow-up write tool. Nothing material is left for the agent to guess.

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; the description earns an extra point by explaining the semantic relationship the schema cannot express — that dimension/values define product scope while filters define store-level scope, and that the two are mutually exclusive. It also clarifies that filters combine after aggregation and that metric predicates belong in filters.metrics on the first request, reinforcing the deprecation path in the 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?

The description opens with a specific verb and resource ('Queries advertising keyword, explicit ASIN, product-category, automatic theme, or keyword-group theme target performance') and enumerates exactly which target types are covered, including zero-traffic ones. This makes it distinguishable from query_advertising (account-level performance) and query_advertising_negative_targets 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete routing rules: use filters for store-level attribute/metric conditions on the first call rather than scanning pages, use dimension/values only for product-scoped historical candidate lookup, and never combine the two. It also states the downstream path to AD_TARGETING_CHANGE and the 95-day windowing procedure. It stops short of naming sibling alternatives (e.g. query_advertising_target_recommendations) for the 'suggest me a target' case, so the agent must infer that boundary.

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

All tool4seller-mcp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?