selling-partner-listing-searchability

Overview

Answers "why isn't this showing up, and how do I get found?" Discoverability in a Selling Partner API (SP-API) listing is two things: whether the listing is indexed at all, and, once indexed, whether its content is strong enough to rank for what shoppers type. This skill checks discoverability, then helps optimize the searchable content (title, description, bullet points, and generic keywords) with the seller's approval. It is the searchability member of the SP-API listing troubleshooter family; not-buyable and reported issues are separate skills (see the sibling skills in Resources).

Workflow

<Definition - Discoverability> Whether shoppers can find a listing in search, treated as a spectrum, not a binary. It has two parts: whether the listing is indexed at all (DISCOVERABLE present in the status array), and, once indexed, whether its content is strong enough to rank for what shoppers type. A listing can be indexed but rank poorly, or fail to index on a content gap (for example a missing main image) that carries no formal issue. So an empty issues[] does not mean the listing is discoverable. </Definition - Discoverability>

<Definition - Searchable Content> The listing attributes shoppers search against, which this skill optimizes with approval: item_name (the title), product_description, bullet_point, and generic_keyword. These are the content fields the seller controls; improving them is the skill's main lever for discoverability. </Definition - Searchable Content>

<Definition - Listing Status> The summaries[].status field returned by the listings search operation is an array of independent states, not a single value. DISCOVERABLE means the listing appears in search; BUYABLE means customers can buy it. They are independent: a listing can be BUYABLE but not DISCOVERABLE, or the reverse. This skill acts on discoverability; not-buyable is a sibling skill. </Definition - Listing Status>

<Definition - Validation Preview> A dry-run write: calling the listings patch operation with mode VALIDATION_PREVIEW returns the issues a change would produce and persists nothing. It is how a content change is checked and shown to the seller before a live write. Removing the mode and re-running the same call is the live submission. </Definition - Validation Preview>

<Workflow - Diagnose Searchability description="Check whether a listing is discoverable, then optimize the searchable content with the seller's approval, without overpromising rank." tools=[] triggers=["not showing up in search", "can't be found", "not discoverable", "improve ranking", "search visibility", "optimize my listing", "search engine optimization"]

1. [Agent] Confirm the built-in Amazon Selling Partner connector is connected before any work, per the README pre-requisites. This skill reads listings and patches searchable content through that connector's listings search and patch operations. The connector is offered during onboarding, but the seller may have skipped it and added this skill manually. Validate: The connector is connected and its listings operations are reachable. If fails: Tell the seller the Amazon Selling Partner connector must be connected and authenticated (from onboarding or Settings > Capabilities), and stop rather than simulating a result.

2. [Agent] Establish account context (pre-resolved). The connector resolves the seller's merchant account(s) and marketplace(s) at the start of the session. Pin exactly one merchant account (entityId) and one marketplace before any call: if several accounts are in scope, ask which; if several marketplaces are in scope, ask which; if exactly one of each, use it. Keep this context in the session only. Validate: One entityId and one marketplaceId are pinned for the calls. If fails: Ask the seller for the missing identifier once, and do not guess a value.

3. [Agent] Check whether the listing is discoverable. Call the listings search operation with includedData=summaries,attributes,issues for the SKU in question. Check whether DISCOVERABLE is present in the status array, and read the current searchable content (title, description, bullet points, generic keywords). Validate: A result is returned and the discoverable state plus current searchable content are captured. If fails: If the read returns nothing or errors, report what came back and ask the seller to confirm the SKU or marketplace before retrying.

4. [Decide] Is the listing discoverable?

   • Not discoverable: look for a content gap that blocks indexing (for example a missing main image), noting it may carry no formal issue. If it surfaces as a reported issue, hand to selling-partner-listing-issues; otherwise relay the content gap and continue to optimize what the seller controls.
   • Discoverable but ranking poorly: continue to content optimization; there is no rank-check operation, so treat ranking as guidance. Validate: The discoverability state is classified and the path (route vs optimize) is chosen. If fails: If the state is ambiguous, relay what the data shows and ask the seller whether to pursue indexing or optimization.

5. [Agent] Optimize the searchable content. Review the current item_name (title), product_description, bullet_point, and generic_keyword, and suggest concrete improvements: clarity, relevant terms shoppers actually use, no keyword stuffing, within Amazon's length and policy limits. Explain why each change helps discoverability. Validate: One or two concrete, policy-compliant content improvements are identified with a plain-language reason. If fails: If you cannot identify a clear improvement, say so rather than fabricating keywords, and ask the seller what terms their shoppers use.

6. [Decide] Does the proposed content add or alter a regulated or prohibited claim, or change category, condition, images, or identifiers?

   • Yes: run the selling-partner-listing-compliance gate now and continue only on the seller's explicit go.
   • No (wording and relevance only): continue. Validate: The gate ran, or the change was classified as claim-free. If fails: If unsure whether a term is a regulated claim, run the gate.

7. [Agent] Draft the change in preview, do not execute. Call the listings patch operation with mode VALIDATION_PREVIEW for the improved content so nothing changes yet. Show the seller current then proposed for each field, and any issue the preview still reports (for example a length violation). Validate: A preview result is produced and shown, with no live write yet. If fails: If the preview surfaces a new issue (for example exceeding a length limit), show it and refine before going live.

8. [Ask user] Wait for explicit approval. Present the previewed content change and ask the seller to approve or adjust. Do not write until they explicitly approve that specific change. Validate: The seller explicitly approves the specific previewed change. If fails: If they do not approve, adjust per their feedback and re-preview; make no live change.

9. [Agent] Apply only on approval, then verify. Re-run the same patch call without VALIDATION_PREVIEW. A live ACCEPTED means validation passed, not that the change is live or indexed yet, since processing is asynchronous. Offer to re-read the item once after a short wait to confirm the change landed; do not promise an immediate ranking change, and do not poll in a loop. Validate: The live patch returns and the seller is told acceptance is asynchronous, with a re-read offered. If fails: If the write is rejected, report the exact error, return to the preview step, and refine before retrying.

10. [Agent] Summarize. State whether the listing is discoverable, the top one or two content improvements made or drafted, and that ranking effects are not immediate or guaranteed. Keep it short and seller-friendly. Validate: A short summary with the discoverability state and the concrete next action is produced. If fails: If the outcome is unknown (for example an async change still processing), say so and offer the re-read rather than asserting improved rank.

</Workflow - Diagnose Searchability>

This skill depends on the built-in Amazon Selling Partner connector in Amazon Quick (see README.md ## Pre-requisites). The connector is offered during onboarding; if the seller skipped it, they connect and authenticate it from Settings > Capabilities.

Amazon Selling Partner API and Seller Central references (public):

• Amazon selling policies: https://sellercentral.amazon.com/help/hub/reference/GSNV3657R94YP9DZ