Amazon Seller MCP Server — AgentXray

Brand keyword gaps (with ready drafts)

get_brand_keyword_gaps

Read-onlyIdempotent

Brand Analytics, analysed (brand-registered sellers): (1) search terms where this seller's product gets a click share like a competitor's but a lower conversion share — a detail-page problem (price, reviews, images), not a keyword one; (2) search terms the seller's own buyers use that the listing's title, bullets and backend keywords do not carry, each with a ready draft (draft_listing_update carrying the FULL backend keyword set — the field is replaced, never appended). File a draft only after the seller agrees. Use it for 'which keywords am I missing', 'why do competitors convert better', 'improve my listing for search'.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_brand_keyword_gaps"
  }
}

Input Schema

Name	Required	Description	Default
`account`	No	Seller id of the client account (agencies with several accounts on this marketplace).
`marketplace_id`	No	Marketplace (inferred when only one is connected).

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 11, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/no-destructive, but the description adds the non-obvious behavior an agent must know: the tool emits drafts (a write-shaped artifact from a read-only tool) that should only be filed after seller consent, and the draft carries the FULL backend keyword set because that field is replaced, never appended. That replacement semantics warning is exactly the kind of detail that prevents a damaging downstream write.

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?

Content is dense and front-loaded: scope first, then the two analysis types, then the draft caveat, then usage triggers. The long parenthetical about the full backend keyword set is justified by its importance, but the multi-clause opening sentence is heavier than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still communicates what comes back (search terms in two categories, plus a draft object) and who it applies to (brand-registered sellers). It doesn't specify result volume, pagination, or what an empty result means, which leaves a small gap for a two-parameter analytical tool.

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

Parameters3/5

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

Schema description coverage is 100% and both parameters (account, marketplace_id) are already documented as seller id and marketplace with inference behavior. The description adds no parameter-level semantics of its own, so the schema carries the load and baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Brand Analytics, analysed') and enumerates the two things returned: click-share/high-conversion-ratio mismatches (detail-page problems) and missing search terms with ready drafts. It is clear what the tool produces, though it never explicitly contrasts itself with the adjacent sibling get_brand_search_terms, so sibling differentiation relies on inference.

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 trigger phrases ('which keywords am I missing', 'why do competitors convert better', 'improve my listing for search') and an operational rule ('File a draft only after the seller agrees'). What's missing is an explicit alternative route — e.g. to use get_brand_search_terms for raw term data rather than gap analysis — so the when-not guidance is incomplete.

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

All Amazon Seller MCP Server — AgentXray 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?