Product Intelligence¶
Rank a website's products on a performance dimension: best sold on Tuesdays, most bought in the evening, highest lifetime value, best candidates for a 10% discount, most seasonal for Christmas.
Free beta
Product Intelligence is in beta, and free while it's in beta. Expect it to move: dimensions and fields can be renamed, added or removed. Don't build anything business-critical on it without a fallback.
This tool reads the same data as the Product Intelligence API and the dashboard, so the numbers match. Where the API's productInsight query answers "what do I know about this product?", this tool answers the inverse question: "which of my products best match this criterion?".
Products need enough purchase history before Product Intelligence can score them, and those that don't have it are left out. An empty result means nothing matched; it isn't an error. The API page covers what the model needs.
Tips & tricks¶
Pick the card that matches what you're doing. Each prompt is ready to paste into your assistant.
Ask by the occasion
Ask for products by the occasion you're planning for, and let the assistant pick the dimension.
Name the offer
Discount planning works the same way. Name the discount you're considering.
Rank on one, filter on another
Rank on one dimension and filter on another to keep the list commercially sensible.
Look past the rank
Every result carries a 0-1 score and the raw dimensionValue behind it: for DAY_OF_WEEK, the share of a product's purchases that fall on that day. Ask for it when you need to know whether the top product is a strong signal or the best of a weak field.
Plan the whole week
One call ranks one day. Your assistant is happy to make seven: ask for the whole week and it runs the ranking once per weekday and assembles the calendar.
Plan the season ahead
MONTH_OF_YEAR ranks products by how much of their yearly sales land in a month window. Christmas decorations top Q4, and a bestseller that sells evenly all year stays off the list. A window can run past New Year: December to February is monthFrom: 12, monthTo: 2.
Put the winners to work
The ranked list doesn't have to stop in the chat. The same MCP server carries write tools for Pages, Recommendations and Newsletter Content campaigns, so the assistant can put the winners to work. It asks before it changes anything.
productIntelligence_getTopProducts¶
Rank a website's products on a Product Intelligence performance dimension, best first. Each result carries a 0-1 score for how well the product matches the dimension (results are ordered by it) and the product's raw dimensionValue. For DAY_OF_WEEK, that's the share of its purchases that happen on that day. For MONTH_OF_YEAR, it's the share of its yearly purchases that fall in the month window, which makes the ranking a measure of seasonality: a product that sells evenly all year ranks low in every month.
Some dimensions need extra arguments: DAY_OF_WEEK needs weekday, TIME_OF_DAY needs hourFrom and hourTo, DAY_AND_TIME_OF_DAY needs all three, DISCOUNT needs discountFrom and discountTo, and MONTH_OF_YEAR needs monthFrom and monthTo. PRODUCT_LIFETIME_VALUE, RETENTION_RATE and RECURRENCE_RATE take none. Passing a dimension without its arguments returns a validation error naming what's missing. The topProducts API page documents each dimension in full, including how discount ranges round out to 10-point bands.
| Name | Type | Required | Description |
|---|---|---|---|
websiteUuid | string | Yes | The UUID of the customer's website in Hello Retail. Use website_getInfo to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id. |
dimension | string | Yes | What to rank by: DAY_OF_WEEK, TIME_OF_DAY, DAY_AND_TIME_OF_DAY, DISCOUNT, MONTH_OF_YEAR, PRODUCT_LIFETIME_VALUE, RETENTION_RATE or RECURRENCE_RATE. |
weekday | integer | No | Day of the week to rank by, 1 for Monday through 7 for Sunday. Required by DAY_OF_WEEK and DAY_AND_TIME_OF_DAY. |
hourFrom | integer | No | Start of the time-of-day window, 0-23 inclusive. Required by TIME_OF_DAY and DAY_AND_TIME_OF_DAY. |
hourTo | integer | No | End of the time-of-day window, 0-23 inclusive. Required by TIME_OF_DAY and DAY_AND_TIME_OF_DAY. |
discountFrom | integer | No | Start of the discount range, 1-100 inclusive, to rank purchase probability within. Required by DISCOUNT. The discount data is grouped in 10-point bands (1-10, 11-20, ...), so a range covers every band it touches. The range exactly 0-0 ranks by full-price purchases instead. |
discountTo | integer | No | End of the discount range, 1-100 inclusive. Required by DISCOUNT. |
monthFrom | integer | No | First month of the month window, 1-12 with January as 1. Required by MONTH_OF_YEAR. A single month is monthFrom = monthTo; Q3 is 7-9. A monthFrom after monthTo wraps the year end, so 12-2 is December to February. |
monthTo | integer | No | Last month of the month window, 1-12 inclusive. Required by MONTH_OF_YEAR. |
filters | array of objects | No | Threshold conditions on product metrics, combined with AND. Per entry: metric (any ranking dimension, or PRICE), operator (GT, GTE, LT or LTE) and value are required. A parameterized metric takes the same arguments inside the filter as its dimension takes on the query (DAY_OF_WEEK a weekday, TIME_OF_DAY an hourFrom/hourTo window, DISCOUNT a discountFrom/discountTo range, MONTH_OF_YEAR a monthFrom/monthTo window), and compares against the same 0-1 share the dimension reports. Products without data for a filtered metric are excluded. |
limit | integer | No | Number of products to return, 1-100. Default 10. |
Example request & response
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "productIntelligence_getTopProducts",
"arguments": {
"websiteUuid": "<string>",
"dimension": "DISCOUNT",
"discountFrom": 1,
"discountTo": 10,
"filters": [
{
"metric": "RETENTION_RATE",
"operator": "GT",
"value": 0.4
}
],
"limit": 3
}
}
}