Skip to main content
Glama
Sign In

Sellantica Amazon Ads

by ai.sellantica
OverviewDiscussionsAdmin

Prepare one or more product ad create previews

prepare_product_ad_create_v1
DestructiveIdempotent

Create an idempotent, auditable write intent to create one or more brand-new product ads (advertising an ASIN in an ad group) in existing ad groups. adgroup_id must come from get_ad_groups; the ASIN (or, when sku is given, that SKU) must not already have a product ad in that ad group. For seller profiles the SKU is resolved at prepare time: an ASIN with several seller SKUs is refused with the candidate list until sku is passed. state is optional: ENABLED (default) or PAUSED, and the ad is created in that state. Nothing changes on Amazon or in Sellantica until the returned request is confirmed via approve_write_v1 and then execute_write_v1. The preview states will_dispatch: true means execute_write_v1 sends it to Amazon, false (execution_mode PREVIEW_ONLY) means it is recorded and never sent. To change an existing product ad's state (enable/pause/archive) instead of creating one, use prepare_product_ad_state_v1; to create a TARGETING clause for an ASIN (not the ad itself) use prepare_product_target_create_v1 instead.

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": {
      "profile_id": "<profile_id>",
      "profile_pk": "<profile_pk>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "prepare_product_ad_create_v1"
  }
}

Input Schema

NameRequiredDescriptionDefault
skuNoSeller profiles only: the seller SKU to advertise. Optional when the ASIN has exactly one SKU. Required when it has several (for example an FBM SKU and an FBA SKU such as 12345 and 12345_afn): prepare then fails and lists the candidate SKUs. To advertise several SKUs of one ASIN, pass one item per SKU.
asinNoASIN (B-prefixed, e.g. B0CXYZ1234) or 10-digit ISBN to advertise. For seller profiles the SKU is resolved and checked here, at prepare time.
itemsNoBatch form: an array of per-ad create objects (adgroup_id, asin, sku?, state?). Use this instead of the flat arguments to create more than one product ad in a single call; never pass both.
stateNoOptional initial product ad state: ENABLED (default) or PAUSED. The ad is created in that state.
adgroup_idNoAmazon ad group id the new product ad is created in, from get_ad_groups. Use this or items, not both.
profile_idYesAmazon Ads profile id, from list_profiles.
profile_pkYesSellantica's internal profile primary key, from list_profiles (needed when profile_id is not unique).
idempotency_keyYesCaller-chosen key (6-128 safe characters) that makes a retry of this exact call return the same write request instead of creating a duplicate.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / items / items / properties / state / description
      Previous value: -"Optional; only ENABLED is accepted because a product ad is always created ENABLED. To pause it afterwards use prepare_product_ad_state_v1."New value: +"Optional initial product ad state: ENABLED (default) or PAUSED. The ad is created in that state."
    • addedInput schema / properties / items / items / properties / state / enum
      Added value: +[
+  "ENABLED",
+  "PAUSED"
+]
    • changedInput schema / properties / state / description
      Previous value: -"Optional; only ENABLED is accepted because a product ad is always created ENABLED. To pause it afterwards use prepare_product_ad_state_v1."New value: +"Optional initial product ad state: ENABLED (default) or PAUSED. The ad is created in that state."
    • addedInput schema / properties / state / enum
      Added value: +[
+  "ENABLED",
+  "PAUSED"
+]
  2. Changed2 schema fields changed
    • changedInput schema / properties / items / items / properties / state / description
      Previous value: -"Human-readable desired state label only (ENABLED or PAUSED); the actual create is always dispatched as ENABLED regardless of this value."New value: +"Optional; only ENABLED is accepted because a product ad is always created ENABLED. To pause it afterwards use prepare_product_ad_state_v1."
    • changedInput schema / properties / state / description
      Previous value: -"Human-readable desired state label only (ENABLED or PAUSED); the actual create is always dispatched as ENABLED regardless of this value."New value: +"Optional; only ENABLED is accepted because a product ad is always created ENABLED. To pause it afterwards use prepare_product_ad_state_v1."
  3. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare non-read-only, destructive and idempotent; the description adds the crucial write-intent lifecycle (nothing dispatched until approve_write_v1 and execute_write_v1), the meaning of will_dispatch and PREVIEW_ONLY mode, and the refusal behavior when an ASIN resolves to multiple SKUs. That is behavioral context well beyond the annotations.

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?

Front-loads the verb, resource and idempotency, then constraints, then the sibling routing in the final sentence. Dense but every sentence carries information; a little redundancy with the schema's own batch/flat guidance keeps it slightly below top marks.

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?

For an 8-parameter mutation tool with no output schema, the description covers prerequisites, failure modes, mutation semantics, the confirm/execute chain and the will_dispatch return flag. What an agent needs to call it and interpret the response is essentially all present.

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, but the description adds semantics beyond the schema: SKU resolution happens at prepare time, a multi-SKU ASIN is refused with the candidate list, and the preview's will_dispatch flag is explained. The batch-vs-flat mutual exclusion is stated in both places, so the description mainly reinforces rather than extends here.

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?

States a specific verb and resource — creating an idempotent, auditable write intent for new product ads (advertising an ASIN in an ad group) inside existing ad groups. It immediately distinguishes itself from the two closest siblings (prepare_product_ad_state_v1 for state changes, prepare_product_target_create_v1 for targeting clauses).

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 explicit preconditions (adgroup_id from get_ad_groups, ASIN/SKU must not already exist in the ad group) and names two alternatives with the exact condition that selects each. It also spells out the full lifecycle: nothing changes until approve_write_v1 then execute_write_v1.

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

All Sellantica Amazon Ads toolsInspect
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