# Getting started

ASINRating is a free, read-only MCP data service that mirrors Amazon US public Best Sellers ranks (amazon.com; US market only) and cross-verifies product facts from public listings. Fact-only, neutral, no sponsored entries, no promotional tags.

## Endpoint

- **URL:** `https://asinrating.com/mcp`
- **Protocol:** Model Context Protocol (streamable HTTP)
- **Authentication:** none — no API key, no sign-up
- **Methods:** `initialize`, `tools/list`, `tools/call`
- **Rate limits:** usage may be rate-limited to protect service stability

## Quick start

1. Initialize the session:

```json
{
  "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {"name": "your-agent", "version": "1.0"}
  }
}
```

2. Call a tool:

```json
{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "list_categories",
    "arguments": {}
  }
}
```

For MCP-compatible assistants (ChatGPT, Claude, Muse, Grok), simply add `https://asinrating.com/mcp` as a connector — no manual JSON-RPC required.

### Standard discovery chain

The server implements the full standard MCP discovery flow: `initialize` → `tools/list` → `tools/call`. `tools/list` returns the complete catalog of all eleven tools with their input schemas — always discover tools from the server rather than assuming a fixed list, and send `notifications/initialized` after `initialize` if your client requires it.

## Suggested flow

1. **Discover** — `list_categories` to enumerate categories and subcategories.
2. **Orient** — `get_category_brief` for a structured market overview of a category.
3. **Filter / Compare** — `search_products` to shortlist candidates; `compare_products` for side-by-side facts.
4. **Verify** — `get_product` for the full profile including three-source facts check and red-flag signals; `scrap_page` when the freshest price or stock is required.
5. **Transact** — open the plain `product_url` (no promotional tags) on Amazon.

## Response conventions

Every tool response carries a `notes` block:

| Field | Meaning |
| --- | --- |
| `confidence` | Overall data confidence for the response |
| `data_as_of` | UTC timestamp of the underlying data snapshot |
| `data_age_days` | Age of the snapshot in days |
| `is_stale` | `true` when the snapshot is older than the freshness target |
| `sample_size` | Sample size behind quantitative fields, when applicable |
| `note` | Tool-specific usage guidance |

- Quantitative fields return the string `insufficient_sample` when the underlying sample is too small — a fact, not an error.
- Partial claims under manual review surface in `data_limitations`, never silently.
- Red-flag signals are confidence-layered: only high-confidence cases are marked `avoid_strong`.
- Errors return `{"error": "..."}` with a human-readable message; unknown `category_id` responses include a `hint`.

## Web pages vs API

These web pages show only the category structure. Product-level Top-100 lists and all product data are served exclusively through the MCP API.

## Tool catalog

| Tool | Purpose |
| --- | --- |
| `list_categories` | Categories and subcategories |
| `get_category_brief` | Structured category market brief |
| `get_top100` | Best Sellers Rank list |
| `get_product` | Full product profile |
| `search_products` | Search with sort and filters |
| `compare_products` | Side-by-side comparison |
| `request` | Fetch by URL or ASIN with field filters |
| `get_price` | Latest stored price |
| `scrap_page` | Real-time page scrape |
| `get_price_change` | 180-day price change summary |
| `get_brand` | Brand profile from the brand registry |

## Data principles

- Facts only: no composite scores, no verdicts, no recommendations.
- Transparent freshness: every response exposes its data timestamp and staleness.
- No commercial bias: product links are plain Amazon pages; the service derives no commercial benefit from links.

Full machine-readable guides: [agents.md](/agents.md) and [llms.txt](/llms.txt).

## Maintenance

ASINRating is maintained by Bobbi Tseng, reachable at support@asinrating.com. Security reports: support@asinrating.com, admin@asinrating.com.


---

# list_categories

List the top-level product categories and their subcategories covered by this service. Subcategories are enumerable: each carries a human-readable name and a stable `subcategory_id` you can pass directly to `get_top100`.

**When to use:** always call this first — every category-scoped tool takes a `category_id` or `subcategory_id` returned here.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| *(none)* | — | — | — |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {"name": "list_categories", "arguments": {}}
}
```

## Response shape

```json
{
  "categories": [
    {
      "category_id": "all-departments",
      "name": "All Departments",
      "subcategories": [
        {"subcategory_id": "7073960011", "name": "Portable Power Banks"},
        {"subcategory_id": "...", "name": "On-Dash Cameras"}
      ],
      "coverage_status": "covered"
    }
  ],
  "notes": {"confidence": "...", "data_as_of": "...", "...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Field | Description |
| --- | --- |
| `categories[].category_id` | Slug identifier for top-level category tools (`get_top100(category_id)`, `get_category_brief`) |
| `categories[].name` | Display name, mirrors Amazon's public department naming |
| `categories[].subcategories[].subcategory_id` | Numeric node identifier; pass it verbatim to `get_top100(subcategory_id=...)` |
| `categories[].subcategories[].name` | Human-readable subcategory name |
| `coverage_status` | `"covered"` — the category is in active coverage |

## Tool note

Subcategory names mirror Amazon's public category tree. Use `get_top100` with either the parent `category_id` (whole department) or a specific `subcategory_id` (single list).

## Related tools

- `get_top100` — rankings for a category or a single subcategory
- `get_category_brief` — structured market brief for a top-level category


---

# get_category_brief

Get a structured market brief for a top-level category: market overview metrics, consideration factors, gotchas, scene needs, keywords, and a candidate pool of ASINs.

**When to use:** to orient within a category before picking individual products.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `category_id` | string | yes | Slug of a top-level category (from `list_categories`) |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 5, "method": "tools/call",
  "params": {
    "name": "get_category_brief",
    "arguments": {"category_id": "all-departments"}
  }
}
```

## Response shape

```json
{
  "category": {"category_id": "...", "name": "..."},
  "market_overview": {
    "subcategories": 9,
    "heat_score": 72.4,
    "brand_count": 148.2,
    "seller_count": 210.9,
    "monopoly_index": 0.31,
    "top100_coverage": 0.87,
    "congestion_score": 55.0
  },
  "considering_factors": ["..."],
  "gotchas": [{"factor": "...", "source": "multi-source cross-verified review corpus"}],
  "common_questions": [],
  "common_questions_available": false,
  "needs": ["..."],
  "keywords": ["..."],
  "candidate_pool": {"sample_asins": ["B01MTB55WH", "..."]},
  "notes": {"sample_size": 1200, "...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Field | Description |
| --- | --- |
| `market_overview` | Averages across the category's subcategories; `subcategories` is the count |
| `considering_factors` | Inductive purchase-consideration factors from a cross-verified review corpus |
| `gotchas` | Inductive pitfalls with their verification source |
| `common_questions_available` | `false` when this dataset is not published for the category |
| `needs` / `keywords` | Scene needs and search keywords observed in the corpus |
| `candidate_pool.sample_asins` | ASIN sample to feed into `get_product` / `compare_products` |

## Tool note

> The category brief is derived from a sample of products. CCF/Gotchas are inductive findings, not exhaustive; mention rates and sentiment distributions are statistical representations, not recommendations. See sample_size; quantitative fields return insufficient_sample when the sample is insufficient.

## Related tools

- `get_top100` — the ranked list behind the category
- `get_product` — verify candidate ASINs individually


---

# get_top100

Get the Best Sellers Rank list (rank 1..N) for either a whole top-level category or a single subcategory. Ranking is an objective representation of Amazon's official best-seller list, presented without evaluation.

**When to use:** after `list_categories`, to pull the ranked list that anchors category research.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `category_id` | string | one of two | Slug of a top-level category (from `list_categories`) |
| `subcategory_id` | string | one of two | Numeric node id of a single subcategory (from `list_categories`) |

Provide exactly one of the two. Rankings are per subcategory list (rank 1..N).

## Example call

```json
{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": {
    "name": "get_top100",
    "arguments": {"subcategory_id": "7073960011"}
  }
}
```

## Response shape

```json
{
  "category": {"category_id": "...", "name": "..."},
  "list_size": 100,
  "top100": [
    {
      "rank": 1,
      "bsr_subcategory_rank": 1,
      "subcategory_id": "7073960011",
      "asin": "B01MTB55WH",
      "brand": "Anker",
      "title": "Portable Charger ...",
      "rating": 4.6,
      "review_count": 25000,
      "rating_distribution": {"five_star": 78, "four_star": 14, "...": "..."},
      "price": 29.99,
      "price_as_of": "2026-11-04T08:12:00Z",
      "product_url": "https://www.amazon.com/dp/B01MTB55WH",
      "buyer_signal": null
    }
  ],
  "notes": {"...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Field | Description |
| --- | --- |
| `rank` | Position in this list (1-based, contiguous) |
| `bsr_subcategory_rank` | Best Sellers Rank within the subcategory as observed |
| `rating` / `review_count` | Snapshot values at collection time |
| `rating_distribution` | Full 5-to-1 star percentage breakdown |
| `price` / `price_as_of` | Observed price snapshot with its UTC timestamp — not real-time |
| `product_url` | Plain Amazon product page, no promotional tags |
| `buyer_signal` | `avoid_strong` only when a high-confidence red flag exists; otherwise absent |

## Tool note

> BSR ranking is an objective representation of Amazon's official best-seller list, presented without evaluation. Rankings update over time; see data_as_of for the data timestamp. Prices are snapshots (see price_as_of); for a real-time quote call scrap_page or open product_url. For side-by-side comparison, call compare_products with 2-5 ASINs.

## Related tools

- `get_product` — full profile for any ASIN in the list
- `compare_products` — side-by-side across dimensions
- `scrap_page` — real-time price/stock snapshot


---

# get_product

Get a product's full profile: specifications, the complete listing description, ratings, price, trend, dimension scores and percentiles, three-source facts check, red-flag signals, and sentiment.

**When to use:** to verify a candidate ASIN in depth before recommending or comparing it.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `asin` | string | yes | 10-character Amazon ASIN |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 6, "method": "tools/call",
  "params": {
    "name": "get_product",
    "arguments": {"asin": "B01MTB55WH"}
  }
}
```

## Response shape

```json
{
  "profile": {
    "asin": "B01MTB55WH",
    "title": "Portable Charger ...",
    "brand": "Anker",
    "specifications": {"...": "..."},
    "feature_bullets": ["..."],
    "full_description": "Complete product description paragraph from the listing (null when the source listing has no description)",
    "categories": ["..."],
    "product_url": "https://www.amazon.com/dp/B01MTB55WH",
    "media": {"videos_count": 2, "images_count": 18}
  },
  "price": {
    "price_current": 29.99,
    "currency": "USD",
    "hist_180d_min": 25.99,
    "hist_180d_max": 35.99,
    "price_as_of": "2026-11-04T08:12:00Z"
  },
  "ratings": {"rating": 4.6, "review_count": 25000, "rating_distribution": {"...": "..."}},
  "competitiveness": {"bsr_leaf_rank": 1, "bought_past_month": 9000, "...": "..."},
  "seller": {"buybox_seller": "...", "fba": true, "is_prime": true, "...": "..."},
  "facts_check": [
    {"claim_id": "...", "claim_text": "...",
     "user_reviews": "corroborated", "social_ugc": "unmentioned_in_reviews",
     "seller_self": "consistent", "needs_manual_review": false}
  ],
  "red_flags": {"verdict": "...", "confidence": "...", "buyer_signal": null},
  "sentiment": {"overall_polarity": "positive", "themes": ["..."], "sample_size": 320},
  "data_limitations": [],
  "notes": {"...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Field | Description |
| --- | --- |
| `profile` | Identity, specs, bullets, categories, media counts, plain product URL |
| `price` | Current stored price, 180-day history min/max/avg, node price percentiles |
| `trend` | 180-day price trend and 60-day review growth |
| `ratings` | Snapshot rating, review count, full star distribution, node percentiles |
| `competitiveness` | BSR rank, monthly bought estimate, brand concentration (HHI, top shares), in-node percentiles |
| `seller` | Buy Box seller profile, fulfillment type, in-stock percentage, tier |
| `facts_check` | Per-claim verdicts from three independent sources: `user_reviews`, `social_ugc`, `seller_self` |
| `red_flags` | Confidence-layered integrity signals; only high confidence maps to `avoid_strong` |
| `sentiment` | Overall polarity plus themes with sample size; sparse or low-confidence data is flagged |
| `data_limitations` | Explicit list, e.g. partial claims under manual review |

## Verdict vocabulary

- `corroborated` / `contradicted` — the source confirms or contradicts the claim.
- `unmentioned_in_reviews` — data sparsity, meaning "not mentioned in reviews", **not** "refuted".
- `consistent` / `inconsistent` — internal consistency of the seller's own copy.

## Tool note

> Facts check presents three sources independently: user reviews and social UGC may show unmentioned_in_reviews due to data sparsity (meaning "not mentioned in reviews", not "refuted"); seller_self verifies internal consistency of the seller's own copy. Red-flag signals are layered by confidence — only high-confidence suspicious cases are marked avoid_strong. Evaluate each claim's credibility yourself; this tool draws no conclusion. Prices are snapshots (see price_as_of in the price block); for a real-time quote call scrap_page or open product_url. For side-by-side comparison, call compare_products with 2-5 ASINs.

## Related tools

- `compare_products` — side-by-side across dimensions
- `scrap_page` — real-time price/stock snapshot
- `request` — same payload with field filtering


---

# request

Fetch structured data by URL or ASIN with optional field filters. Same payload as `get_product`, but accepts an Amazon product URL directly and lets you request only the fields you need.

**When to use:** when you have a product URL instead of an ASIN, or want a trimmed payload.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | one of two | A valid Amazon product URL containing an ASIN |
| `asin` | string | one of two | 10-character Amazon ASIN |
| `fields` | list of string | no | Subset of top-level fields to return |

## Available fields

`profile`, `price`, `trend`, `ratings`, `competitiveness`, `seller`, `facts_check`, `red_flags`, `sentiment`

## Example call

```json
{
  "jsonrpc": "2.0", "id": 9, "method": "tools/call",
  "params": {
    "name": "request",
    "arguments": {
      "url": "https://www.amazon.com/dp/B01MTB55WH",
      "fields": ["price", "ratings"]
    }
  }
}
```

## Response shape

```json
{
  "price": {"price_current": 29.99, "currency": "USD", "price_as_of": "2026-11-04T08:12:00Z"},
  "ratings": {"rating": 4.6, "review_count": 25000, "rating_distribution": {"...": "..."}},
  "notes": {"...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

- Unknown `fields` values return an error listing the `available` keys.
- Quantitative fields return `insufficient_sample` when the underlying sample is too small.

## Tool note

> Returns raw data by structured fields; see schema for field definitions. Quantitative fields return insufficient_sample when the sample is insufficient.

## Related tools

- `get_product` — full payload, ASIN input
- `get_price` — price-only shortcut


---

# get_brand

Get a brand's full profile from the brand registry: tier, product count, cumulative review count, rating breakdown, seller positive percentage, subcategory monopoly HHI, 90-day trend, and ratings gained over 30/90 days. Pass a brand_name for an exact match, or a partial name to receive candidate matches.

**When to use:** researching a brand's market footprint and concentration; pass an exact `brand_name` or a partial name to receive candidate matches.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `brand_name` | string | yes | Exact brand name, or a partial name to receive candidate matches |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 12, "method": "tools/call",
  "params": {
    "name": "get_brand",
    "arguments": {"brand_name": "Samsung"}
  }
}
```

## Response shape

```json
{
  "brand": {
    "brand_name": "Samsung",
    "category_ids": ["Electronics"],
    "product_count": 12,
    "variant_count": 30,
    "review_count_total": 120000,
    "avg_rating": 4.5,
    "rating_breakdown": {"five_pct": 74.0, "four_pct": 10.8, "three_pct": 6.0, "two_pct": 3.0, "one_pct": 6.6},
    "seller_positive_pct": 0.92,
    "buybox_share_30d": 0.85,
    "monopoly_hhi": 0.12,
    "ratings_gained_30d": null,
    "ratings_gained_90d": null,
    "trend_90d": null,
    "tier": "head",
    "amazon_buybox_share": 0.85,
    "first_seen_at": "2026-11-04T00:00:00Z",
    "updated_at": "2026-11-04T00:00:00Z",
    "avg_price": 299.99,
    "max_bought_past_month": 5000,
    "best_bsr": 1234,
    "price_bucket": ">$100"
  },
  "notes": {"...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Field | Description |
| --- | --- |
| `tier` | Brand tier label (an objective registry classification) |
| `product_count` / `review_count_total` / `avg_rating` | Brand-level aggregate counts and rating |
| `rating_breakdown` | Full 5-to-1 star percentage breakdown |
| `seller_positive_pct` / `monopoly_hhi` | Seller positive percentage and subcategory monopoly HHI |
| `trend_90d` / `ratings_gained_30d` / `ratings_gained_90d` | 90-day trend and ratings gained |
| `category_ids` | Categories the brand appears in |

## Tool note

> Brand fields are objective registry facts: tier, counts, rating breakdowns, and concentration measures. No evaluation or recommendation is attached.

## Related tools

- `get_product` — product-level profile with brand tier and social presence
- `list_categories` — categories a brand may appear in


---

# search_products

Search for candidate products matching a query, each with a data-maturity tier. Supports sorting and price/rating filters.

**When to use:** to shortlist candidates by keyword before deeper verification.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | 1-8 space-separated terms (title / brand / feature-bullet match) |
| `category_id` | string | no | Restrict to a top-level category (from `list_categories`) |
| `sort` | string | no | `price_asc` \| `price_desc` \| `rating_desc` \| `review_count_desc` |
| `min_price` | number | no | Minimum price, USD |
| `max_price` | number | no | Maximum price, USD |
| `min_rating` | number | no | Minimum average rating, 0-5 |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {"query": "power bank", "sort": "rating_desc", "max_price": 40}
  }
}
```

## Response shape

```json
{
  "results": [
    {
      "asin": "B01MTB55WH",
      "brand": "Anker",
      "title": "Portable Charger ...",
      "data_tier": "top",
      "price": 29.99,
      "price_as_of": "2026-11-04T08:12:00Z",
      "rating": 4.6,
      "review_count": 25000,
      "rating_distribution": {"five_star": 78, "...": "..."},
      "product_url": "https://www.amazon.com/dp/B01MTB55WH"
    }
  ],
  "notes": {"...": "..."}
}
```

*(abbreviated for readability; result limit 100)*

## Field notes

| Field | Description |
| --- | --- |
| `results[].data_tier` | Data-maturity tier label describing how completely this product is covered |
| `results[].price` / `price_as_of` | Stored price snapshot, not real-time |
| `results[].rating_distribution` | Full star breakdown |

## Tool note

> Sort with sort (price_asc | price_desc | rating_desc | review_count_desc); filter with min_price, max_price, min_rating (USD / 0-5 stars). Results include product_url and price_as_of; prices are snapshots — for a real-time quote call scrap_page. For side-by-side comparison, call compare_products with 2-5 ASINs.

## Related tools

- `compare_products` — side-by-side for the shortlist
- `get_product` — deep verification per ASIN


---

# compare_products

Compare two to five products side-by-side across dimensions. The comparison is a dimension-by-dimension presentation with no ranking of better or worse — judgment is left to you.

**When to use:** after shortlisting, to put the candidates' facts next to each other.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `asins` | list of string | yes | 2-5 valid ASINs |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 8, "method": "tools/call",
  "params": {
    "name": "compare_products",
    "arguments": {"asins": ["B01MTB55WH", "B07QK2SPP7"]}
  }
}
```

## Response shape

```json
{
  "products": ["B01MTB55WH", "B07QK2SPP7"],
  "dimensions": {
    "specs": {"B01MTB55WH": {"...": "..."}, "B07QK2SPP7": {"...": "..."}},
    "rating": {"B01MTB55WH": 4.6, "B07QK2SPP7": 4.4},
    "review_count": {"B01MTB55WH": 25000, "B07QK2SPP7": 12000},
    "price": {"B01MTB55WH": 29.99, "B07QK2SPP7": 25.99},
    "competitiveness": {"B01MTB55WH": {"...": "..."}, "B07QK2SPP7": {"...": "..."}},
    "facts_check": {"B01MTB55WH": {"claims": 12, "social_ugc_corroborated": 5, "...": "..."}}
  },
  "notes": {"...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Dimension | Description |
| --- | --- |
| `specs` | Specification payload from each product's profile |
| `rating` / `review_count` / `price` | Snapshot values |
| `competitiveness` | In-node percentiles, brand concentration, monthly bought estimate |
| `facts_check` | Claim counts per source verdict (corroborated / contradicted / consistent / inconsistent) |

## Tool note

> The comparison is a side-by-side, dimension-by-dimension presentation with no ranking of better or worse. Judge for yourself.

## Related tools

- `get_product` — full profile for each compared ASIN
- `scrap_page` — freshest price for the finalists


---

# get_price

Get a product's latest stored price and product-page link.

**When to use:** quick price check from the stored snapshot; call `scrap_page` if you need a real-time quote.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `asin` | string | yes | 10-character Amazon ASIN |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 10, "method": "tools/call",
  "params": {
    "name": "get_price",
    "arguments": {"asin": "B01MTB55WH"}
  }
}
```

## Response shape

```json
{
  "asin": "B01MTB55WH",
  "price_current": 29.99,
  "price_currency": "USD",
  "product_url": "https://www.amazon.com/dp/B01MTB55WH",
  "price_as_of": "2026-11-04T08:12:00Z",
  "notes": {"...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Field | Description |
| --- | --- |
| `price_current` / `price_currency` | Latest stored price and currency |
| `price_as_of` | UTC timestamp of the price snapshot |
| `product_url` | Plain Amazon product page with no promotional tag |

## Tool note

> Price is as of query time (see price_as_of). The product link is an Amazon product-page URL with no promotional tag; this tool derives no commercial benefit from the link.

## Related tools

- `scrap_page` — real-time price and stock
- `get_product` — full price block with 180-day history


---

# get_price_change

Get a product's 180-day price change summary from recorded history: current price, 180-day low/high/average, sample count, and where the current price sits among its own recorded observations.

**When to use:** answering "is now a good time to buy" style questions from historical data. This is a stored snapshot — call `scrap_page` for a real-time quote.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `asin` | string | yes | 10-character Amazon ASIN |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 11, "method": "tools/call",
  "params": {
    "name": "get_price_change",
    "arguments": {"asin": "B01MTB55WH"}
  }
}
```

## Response shape

```json
{
  "asin": "B01MTB55WH",
  "price_current": 29.99,
  "price_currency": "USD",
  "low_180d": 24.99,
  "high_180d": 39.99,
  "avg_180d": 32.45,
  "sample_count_180d": 6,
  "position_in_180d_range_pct": 16.7,
  "current_vs_avg_180d_pct": -7.6,
  "current_vs_low_180d_pct": 20.0,
  "current_vs_high_180d_pct": -25.0,
  "price_as_of": "2026-11-04T08:12:00Z",
  "product_url": "https://www.amazon.com/dp/B01MTB55WH",
  "notes": {"...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Field | Description |
| --- | --- |
| `low_180d` / `high_180d` / `avg_180d` | Lowest, highest, and average recorded price over the trailing 180 days |
| `sample_count_180d` | Number of price observations behind the statistics |
| `position_in_180d_range_pct` | Percentile of the current price among its own recorded 180-day observations (lower = closer to the historical low) |
| `current_vs_avg_180d_pct` | Current price vs the 180-day average, in percent (negative = below average) |
| `change` | Returned as `insufficient_sample` when no usable history exists |

## Tool note

> Statistics come from the recorded pipeline history (see price_as_of), presented without evaluation. This tool draws no conclusion on whether to buy; interpret the numbers yourself.

## Related tools

- `get_price` — latest stored price
- `scrap_page` — real-time price and stock
- `get_product` — full price block with the same 180-day history


---

# scrap_page

Scrape a product page in real time for the latest price, stock, Buy Box seller, rating, and review count. This is the only tool that returns a live snapshot rather than stored data.

**When to use:** only when the freshest price or stock is required — real-time scraping is slower than stored-data tools.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `asin` | string | one of two | 10-character Amazon ASIN |
| `url` | string | one of two | A valid Amazon product URL containing an ASIN |

## Example call

```json
{
  "jsonrpc": "2.0", "id": 11, "method": "tools/call",
  "params": {
    "name": "scrap_page",
    "arguments": {"asin": "B01MTB55WH"}
  }
}
```

## Response shape

```json
{
  "asin": "B01MTB55WH",
  "price": 29.99,
  "currency": "USD",
  "stock": "In Stock",
  "buybox_seller": "Amazon.com",
  "buybox_seller_note": null,
  "rating": 4.6,
  "review_count": 25000,
  "product_url": "https://www.amazon.com/dp/B01MTB55WH",
  "data_as_of": "2026-11-04T09:30:00Z",
  "notes": {"...": "..."}
}
```

*(abbreviated for readability)*

## Field notes

| Field | Description |
| --- | --- |
| `price` / `currency` | Live Buy Box price at scrape time |
| `stock` | Availability string from the page |
| `buybox_seller` | Buy Box winner name; `buybox_seller_note` explains when it is not disclosed |
| `rating` / `review_count` | Live values from the page |
| `data_as_of` | UTC timestamp of this scrape |

- Results are cached for 10 minutes per ASIN; repeated calls within the window return the same snapshot.
- A failed scrape returns `{"error": "scrape failed: <type>"}` — never a fabricated value.

## Tool note

> This is a real-time scrape snapshot; see data_as_of for the data timestamp. Real-time scraping is slower — call only when the latest price or stock is required.

## Related tools

- `get_price` — stored price, faster
- `get_product` — full profile from stored data