# Reviews

> Read the merchant's real customer reviews, curate review collections, and choose what product pages show when a product has no reviews

Canonical URL: https://77865786950d:3005/tools/reviews

Reviews come from the merchant's connected review source (Judge.me). Use these
actions to put **real** reviews on a page. Never invent reviews or ratings.

To connect Judge.me or import a CSV, see
[Judge.me reviews](/guides/judge-me-reviews). To render reviews on a page, use
the [ReviewList](/islands/social-proof/review-list) and
[ReviewCarousel](/islands/social-proof/review-carousel) islands.

## Actions

| Tool · action | Access | Use it to |
|---|---|---|
| `lexsis_catalog` · `reviews_status` | Read | Check whether a source is connected and how many reviews are imported. Call this before planning any reviews or testimonials section. |
| `lexsis_catalog` · `reviews` | Read | Browse imported reviews |
| `lexsis_catalog` · `reviews_search` | Read | Find reviews that match a message or theme |
| `lexsis_catalog` · `review_collections` | Read | List curated review collections |
| `lexsis_catalog` · `review_collection_items` | Read | Read the reviews in one collection, in display order |
| `lexsis_drafts` · `review_collection_create` | Draft | Save merchant-confirmed reviews as a draft collection |
| `lexsis_drafts` · `set_review_fallback` | Draft | Choose what a product page shows when the product has no reviews |

Each action accepts optional `workspace_id` and `store_id`. The workspace
resolves on its own when you have access to exactly one.

## Browse reviews

`reviews` filters:

| Arg | Type | Description |
|---|---|---|
| `q` | string | Free-text search over review title and body |
| `rating_min` | 1–5 | Minimum star rating |
| `has_media` | boolean | Only reviews with photos or video |
| `collection_id` | UUID | Only reviews in this collection |
| `product_id` | string | Only reviews for this product |
| `source_type` | string | Only reviews from this source |
| `limit` | 1–100 | Default 25 |
| `cursor` | string | Pagination cursor |

## Search by intent

`reviews_search` takes a `query` (3–500 characters, for example
`"fixed my dry skin in a week"`) and a `limit` (1–50, default 10). It runs a
semantic search.

- Treat the results as candidates for the merchant to confirm, not a final
  selection.
- `index_status` can be `indexing` or `unavailable` while the search index is
  not ready. Fall back to `reviews` with `q` in that case.

## Review collections

A review collection is an ordered, curated set of reviews.

- `review_collections` accepts `collection_status` (`draft`, `active` or
  `archived`), `q`, `limit` (1–48, default 24) and `cursor`.
- `review_collection_items` takes `collection_id`, plus `limit` (1–100,
  default 50) and `cursor`.
- **Only `active` collections render on published pages.**

`review_collection_create` saves a **draft** collection from reviews the
merchant has confirmed:

```json
{
  "name": "lexsis_drafts",
  "arguments": {
    "action": "review_collection_create",
    "args": {
      "name": "Dry-skin results",
      "submission_ids": ["review-uuid-1", "review-uuid-2"]
    }
  }
}
```

`submission_ids` holds 1–100 review UUIDs in display order. The MCP never
activates a collection. The merchant activates it in
**Storefront → Reviews → Collections**.

## No-reviews fallback

On a product page or product template, ReviewList shows the product's own
reviews. When the product has none, the page's **review fallback** decides
what renders instead:

| `type` | Shows |
|---|---|
| `store` | All of the store's reviews. This is the default when nothing is set. |
| `collection` | One review collection. Pass `collection_id`; only an active collection renders. |
| `none` | Nothing. The section hides. |

```json
{
  "name": "lexsis_drafts",
  "arguments": {
    "action": "set_review_fallback",
    "args": {
      "page_id": "page-uuid",
      "type": "collection",
      "collection_id": "review-collection-uuid"
    }
  }
}
```

- `collection_id` is required for `collection` and rejected for any other
  type.
- The change is draft-level, reversible, and applies on the next render. You
  can also pass `review_fallback: { type, collection_id? }` to
  `lexsis_page_create` · `create`.
- Never hard-code `fallbackCollectionId` or `fallbackScope` in island props.
  The fallback is a page setting the merchant can change in the app.
- In product templates, set ReviewList `"productIds": "$resource"`. On a single
  product page, pass that product's ID explicitly.

ReviewList renders no heading or label for the fallback. Write your headings as
page HTML and switch them with CSS on the island root's `data-reviews-source`
(`product`, `fallback` or `none`):

```css
.rv-head[data-for] { display: none; }
[data-section-id="reviews"]:has([data-reviews-source="product"]) .rv-head[data-for="product"] { display: block; }
[data-section-id="reviews"]:has([data-reviews-source="fallback"]) .rv-head[data-for="fallback"] { display: block; }
[data-section-id="reviews"]:has([data-reviews-source="none"]) { display: none; }
```

Section JS can listen for the `lx:reviews:state` event on `window`. Its detail is
`{ source: "product" | "fallback" | "none", total, average }`.

## Related

- [Tool Reference](/tools/reference)
- [Judge.me reviews](/guides/judge-me-reviews)
- [Templates and routing](/tools/templates-and-routing)
- [ReviewList](/islands/social-proof/review-list)
- [ReviewCarousel](/islands/social-proof/review-carousel)