Agent Capabilities

Reference for the shopping.agent tool.

Server

Item	Value
Transport	MCP Streamable HTTP, stateless
Endpoint	`https://commerceai.ai/mcp/`
Auth	`Authorization: Bearer <YOUR_API_KEY>` on every request
Server name	`commerce-ai-shopping`
Tools	`shopping.agent` (one tool)

The server keeps no MCP session between calls and does not return an Mcp-Session-Id header. Your client stores conversation_id and item_id values and sends them back when needed.

What the tool can do

The query text selects the capability. There is no mode parameter.

Capability	Example `query`	Needs
Search	"running shoes for flat feet under $120"	`query`
Comparison	"compare these two on battery and weight"	`query` + `conversation_id` + `selected_item_ids` from an earlier answer
Product Q&A	"does this one come with a charger?"	`query` + `conversation_id` + `selected_item_ids`
Follow-up	"only ones under $30"	`query` + `conversation_id`
Clarification	"a gift for my dad"	`query`; the agent may answer with a question instead of products

Request

Parameter	Type	Required	Description
`query`	string	Yes	The shopper's request in natural language, 1 to 4,000 characters. Leading and trailing spaces are trimmed; a blank query is rejected.
`conversation_id`	string	No	32-character lowercase hex id from an earlier call. Omit to start a new conversation. Unknown ids, ids from another account, and expired ids are rejected.
`selected_item_ids`	string[]	No	`item_id` values from an earlier `answer_items` list in the same conversation. Send them unchanged. At most 10, no duplicates. Requires `conversation_id`. If any value is not valid for this conversation, the whole call is rejected.
`market`	string	No	Two uppercase letters. Default `US`. Any other market gets a refusal without searching and is not charged. Lowercase values are rejected with `INVALID_ARGUMENT`.
`locale`	string	No	BCP 47 locale for the reply, for example `en-US`. May be ignored for now; replies are in English.
`request_id`	string	No	Your own UUIDv4 or UUIDv7 for this call. The server generates one if omitted. The response always includes `request_id`. Each id runs one turn: reusing it after that turn returns `IDEMPOTENCY_CONFLICT`.

Unknown parameters are rejected with INVALID_ARGUMENT.

Response

The tool result has two parts:

Part	Content
`content`	One text block for the model. See Text for the model.
`structuredContent`	The response object below. Read this in code.

When the call fails, isError is true and structuredContent holds an error object instead. See Errors & Retries.

Response object

Field	Type	Description
`request_id`	string	Your `request_id`, or the one the server generated. Quote it when you contact support.
`conversation_id`	string \| null	Send this back to continue the conversation. `null` on a refused request (cart, orders, non-US market, and so on) unless you sent one.
`outcome`	string	What kind of result this is: `SUCCESS`, `NEEDS_CLARIFICATION`, `NO_RESULTS`, or `UNSUPPORTED`. See Outcomes.
`answer_text`	string	The reply for the shopper, in Markdown, with inline product and table markers. See Answer text.
`answer_items`	Item[]	The products the answer recommends, in display order. Empty when the agent asks a question, finds nothing, or refuses.
`item_comparison_table`	object	Present only when the agent built a comparison table. See Comparison table.
`usage`	Usage	Credits this call used.

The response contains only these fields.

Answer text

answer_text is Markdown. It can contain two kinds of self-closing markers on their own lines:

Marker	Meaning
`<item_mini_card item_id="pr_..." />`	Render the product from `answer_items` with this `item_id` here.
`<item_comparison_table table_ref_id="cmp1" />`	Render the table `item_comparison_table["cmp1"]` here.

If you only show text, remove these markers before display. If you render cards, replace each marker with the matching card or table.

Text for the model

content[0].text is the same answer as answer_text, rendered as self-contained text for a model to read:

Each <item_mini_card> marker is replaced in place by one line: [item_id] name · price · rating/5 · merchant · purchase_url. Empty values are left out.
Each <item_comparison_table> marker is replaced in place by a Markdown table whose first column is item_id.
The last line is conversation_id: <id>.

text

**Best all-around daily trainer**
NITRO foam provides a smooth, cushioned ride for everyday mileage and varied distances.

[pr_mig9IoxC] Puma Mens Velocity Nitro 3 Running Shoes · $59.95 · 4.5/5 · amazon · https://www.amazon.com/...

conversation_id: e79b7b6c42c348a3b5098150824bb2c2

Give this text to your model, so it can answer from it and send conversation_id and selected_item_ids on follow-ups. Render cards and tables in your UI from structuredContent.

Item

Field	Type	Description
`item_id`	string	Opaque reference to this product, starting with `pr_`. Pass it in `selected_item_ids` in the same conversation. Do not parse or build it.
`name`	string	Product title.
`price`	number \| null	Price as a number, in `currency`.
`price_formatted`	string \| null	Display price with currency symbol, for example `"$15.19"`.
`price_min`, `price_max`	number \| null	Price range across offers for this product.
`currency`	string	Currency code, `USD`.
`rating`	number \| null	Average rating, for example `4.3`.
`rating_count`	integer	Number of ratings. `0` when unknown.
`brand`	string \| null	Brand name.
`description`	string	Short product description.
`image_url`	string \| null	Main product image.
`images`	string[]	All product images.
`purchase_url`	string \| null	Merchant page where the shopper can buy.
`item_source`	string	Merchant the offer comes from, for example `walmart`.
`availability`	string	Stock status, for example `in_stock`.
`rank`	integer	Position in the agent's recommendation, starting at 1.
`rcmd_reason`	string[]	Short reasons the agent picked this product.
`key_selling_point`	object[]	Highlights as `{tag, value}` pairs, for example `{"tag": "Durability", "value": "40 hours playtime"}`.
`key_attributes`	object[]	Product attributes as `{tag, value}` pairs.

Any field can be empty. Render what is present.

Comparison table

item_comparison_table maps a table_ref_id to a table:

json

{
  "cmp1": {
    "columns": ["Comparison", "Current price", "Verified total battery", "Water resistance"],
    "rows": [
      {
        "item_id": "pr_xK-ALgZ8",
        "cells": [
          {"value": "Hoey XY60", "value_type": "inner_link", "highlight": false},
          {"value": "$15.19", "highlight": true},
          {"value": "40 hours", "highlight": false},
          {"value": "IPX5", "highlight": false}
        ]
      }
    ]
  }
}

Field	Description
`columns`	Column headers. The first column names the product.
`rows[].item_id`	The product this row describes. Matches an `item_id` in `answer_items`.
`rows[].cells`	One cell per column, in column order. `value` is display text. `highlight: true` marks the best value in that column. `value_type: "inner_link"` marks the product name cell.

Usage

Field	Type	Description
`credits_used`	integer	Credits this call used: input tokens, output tokens, and tool calls added up and rounded up to a whole credit for a completed shopping turn; `0` for a refused request. See Credits.
`billing_status`	string	`PENDING`: the charge is recorded and is being deducted from your balance. `NOT_REQUIRED`: nothing to charge.

The response does not include your balance. Check it in the console. See Credits.

Agent Capabilities ​

Server ​

What the tool can do ​

Request ​

Response ​

Response object ​

Answer text ​

Text for the model ​

Item ​

Comparison table ​

Usage ​

Next ​