Browsing, filters and reviews
Browse a shop by collection and price, read ratings and reviews, and list the collections, through UCP, MCP and WebMCP.
An agent can search a shop with a question, and it can also browse: list what the shop has on sale in a collection or a price range, a page at a time. Every product it is shown carries its rating and the collections it is in, and the reviews behind the rating can be read in full. The same filters and the same values work on every door.
Categories are collection handles
A category is one of the shop's collections, named by its handle: the last part of its address, as in /collections/knitwear. A product's categories lists the collections it is in, and a filter on categories matches a product in any of the ones named. Handles are stable and are not translated, so they are safe to store. List them with list_collections.
On UCP, each entry is { "value": "knitwear", "taxonomy": "merchant" }, and the filter takes the value.
Filters
| Filter | Takes |
|---|---|
categories | A list of collection handles, at most 50. A product in any of them matches. |
price | min, max or both, in minor units of the currency asked for (2500 is 25.00). A product matches when any variant does. |
Both must hold when both are given. The price filter reads the shop's own price in that currency, or in the shop's currency when none was asked for; a product with no price in that currency does not match. A handle that names no collection matches nothing and comes back as a warning, so a typo is not mistaken for an empty shelf.
Browsing and paging
Send filters without a query to browse. The answer lists what is on sale and matches, ordered by handle, with prices and stock read live. An empty filters object lists everything on sale.
A browse pages with a cursor. Pass back the cursor you were given to read the next page; it is opaque, so do not build one. A search with a query answers one ranked page and gives no cursor. Filters on a search narrow its results.
Ratings and reviews
A product's rating is the average of the reviews the merchant approved, on a scale of 1 to 5, with how many there are. It is left out when there are none. Reviews that are waiting for the merchant, or that were rejected, are never counted or served.
get_reviews reads them, newest first, a page at a time (up to 50). Each review has its stars, a title, the words, the name the reviewer signed with as the shop shows it, the date, and verified_purchase, which is true only when the purchase was proved against an order. No email address or account is ever included. Reviews are read only for a product the shop has on sale.
On UCP
Two capabilities of Storeware's own are declared on the shop's profile, each with its schema at https://api.storeware.ai/schemas/ucp/2026-11-11/<name>.json. Both are read only, so any agent key may use them and no shopper needs to be linked.
| Job | REST, under /api/ucp/v1 | MCP tool | Capability |
|---|---|---|---|
| Search or browse | POST /catalog/search | search_catalog | dev.ucp.shopping.catalog.search |
| A product's reviews | POST /catalog/reviews | get_reviews | ai.storeware.shopping.reviews |
| The shop's collections | POST /catalog/collections | list_collections | ai.storeware.shopping.collections |
POST /catalog/search takes filters and pagination as UCP defines them, and answers with pagination: has_next_page, and a cursor when there is one. The query may be left out when there are filters. A page holds 10 products unless pagination.limit says otherwise, and at most 50.
POST /api/ucp/v1/catalog/search
UCP-Agent: profile="https://platform.example/profile.json"
Authorization: Bearer <agent key>
Content-Type: application/json
{
"filters": { "categories": ["knitwear"], "price": { "max": 5000 } },
"context": { "currency": "GBP" },
"pagination": { "limit": 20 }
}get_reviews takes product_id (the product's id from the catalog, or its handle) and pagination, and answers with rating, distribution (how many gave each star), reviews and pagination, whose total_count is the number of approved reviews.
Lookup and get_product take a product's id, a variant's id (both as search returns them), or the product's handle. A lookup answers each product once, with only the variants your ids led to: a variant id brings that variant, and a product id or handle brings the one the shop would show first. Each of those variants lists the ids that reached it under inputs, with match set to exact or featured. Ask get_product for every variant. Given a variant id, get_product leads with that variant and takes its options as the choice.
A shop quotes in the currencies it sells in. Ask for another in context.currency and the answer comes in the shop's own currency, with a warning coded ai.storeware.currency_not_sold saying which one.
Every product on a search, lookup or product answer carries rating, categories, its options, and list_price_range when something is reduced. get_product also takes selected and preferences: it leads with the variant that fits what was chosen, says the full choice under selected, and marks each option value exists and available against it. When nothing fits every choice, the choices ranked last in preferences are given up first.
Over A2A, the same tools are DataParts naming the tool, as for Ask.
On the shop's MCP server
At /mcp, search_products takes filters in the same shape and a cursor. With filters and no query it browses, and next_cursor reads the next page. Each result carries rating and categories, as do get_product and compare_products. get_reviews takes a product handle, with limit and cursor. list_collections takes nothing.
In the shopper's browser
The WebMCP search_products tool takes filters and cursor too, and browses without a query; nextCursor reads the next page. Prices and the price filter are in the shopper's own currency. Each result carries rating and categories. list_collections lists the collections, each with its address on the shop. See WebMCP.