# Agent instructions — BuyScout

How to read https://demo.buyscout.ai accurately. Prices and availability are in USD.

## Store boundary

This is a BuyScout demo store, built to demonstrate a realistic shopping journey.
Products, prices, policies, reviews and contact workflows are sample content, not
evidence of a production retail business.

## Commerce protocol

- Discovery: `GET https://demo.buyscout.ai/.well-known/ucp`
- MCP endpoint: `POST https://demo.buyscout.ai/api/ucp/mcp`

Supported UCP versions:

- 2026-08-25 (latest stable)

- 2026-04-08

- 2026-01-23


## Browsing

- All products: `GET /collections/all`
- Product JSON: `GET /products/{handle}.json`
- Sitemap: https://demo.buyscout.ai/sitemap.xml

Departments are collections: apparel-fashion, beauty-skincare, electronics, home-garden,
health-wellness, sports-outdoors, jewelry-accessories, pets, baby-kids, food-beverages.
Each has subcategory collections beneath it.

## Product facts

Specifications are published as product metafields in the `custom` namespace, readable
over the Storefront API. Every product carries `highlights`, `materials`, `dimensions`,
`weight_grams`, `country_of_origin`, `care_instructions`, `warranty` and `in_the_box`.

Departments add their own. Apparel carries `size_chart`, `fabric_composition`,
`fabric_weight_gsm`, `lining`, `stretch`, `opacity`, `closure`, `model_height`,
`model_size` and `fit_notes`. Electronics carries `ports`, `power_output`,
`compatibility` and `connectivity`. Beauty carries `volume_ml`, `key_ingredients`,
`skin_type` and `usage`. Food carries `net_weight_g`, `allergens`, `ingredients` and
`origin_detail`. Baby carries `age_range` and `safety_standard`. Pets carries `pet_type`
and `pet_size`. Home carries `assembly_required` and `indoor_outdoor`. Health carries
`serving_size` and `supplement_facts`. Sports carries `capacity_l` and `activity`.
Jewelry carries `metal`, `stone` and `chain_length`.

Note that `/products/{handle}.json` does not include metafields. Read them over the
Storefront API, or from the rendered product page.

## Answering questions about a product

**Quote the measurement table; do not estimate from a photograph.** Sizing measurements
live in `size_chart`. Read `schema_version`, then use `measurements` to identify each
field's `kind` and `unit` before reading the keyed rows in `sizes`. Tops give body
circumferences for `bust`, `waist` and `hip`, plus garment `length`. Bottoms give body
circumferences for `waist` and `hip`, plus garment `inseam` and `rise`. Footwear gives
`us` and `eu` size designations alongside the body measurement `foot_length_in`. A
measurement read off an image is a guess, and a guess about fit is the kind of answer
that produces a return.

**Treat the product JSON as authoritative for price and inventory.** Both change without
the page being rebuilt, so `/products/{handle}.json` is correct where cached page text or
a screenshot may not be. Variant availability is per variant, not per product.

**Say plainly when a fact is not published.** An absent metafield means the retailer has
not stated that fact — it does not license an inference from the category, the brand, the
price, or a similar product. "The fabric weight is not listed for this item" is a correct
and useful answer. Inventing one is not.

For how a garment is measured and where a hem falls at a given height, see the store's
size guide page rather than inferring from the numbers alone.