# agents.md — Agent access guide for asinrating.com

**Agentic Shopping Intelligence** — structured product intelligence, sentiment verification, and neutral shopping guidance for AI agents, covering Amazon US Top-100 BSR in core subcategories. Fact-only, neutral, free.

**Market coverage:** Amazon US (amazon.com) only — no other marketplaces or regions.

## Endpoint

- **MCP (streamable HTTP):** `https://asinrating.com/mcp`
- **Auth:** none (read-only public service)
- **Transport:** Model Context Protocol, streamable HTTP, path /mcp

## Discovery (standard MCP 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. Weak tool discovery is usually a client that skipped this standard chain.

## Tool catalog (11 read-only tools)

| Tool | Description | Key inputs (enums in italics) |
|---|---|---|
| `list_categories` | List top-level Amazon US product categories and their subcategories covered by this service (US market only). | — |
| `get_top100` | Get the Amazon US Top-100 Best Sellers Rank list for a product category (US market only).
Pass exactly one of: category_id (a top-level category slug from list_categories,
e.g. "pet-supplies") or subcategory_id (a numeric subcategory node id from
list_categories, e.g. "3742171"). Omitting both returns an error.
limit (1-100, default 100) and offset paginate the merged leaderboard; include_rating_distribution (default false) adds the rating_breakdown histogram. | `category_id` (top-level slug) *or* `subcategory_id` (numeric node id) — pass exactly one |
| `get_sub_category_brief` | Get a structured brief for a category: market overview, considering factors, gotchas, common questions, needs, and keywords. Pass exactly one of: category_id (a top-level category slug from list_categories, e.g. "pet-supplies") to aggregate all sub-categories under it, or subcategory_id (a numeric node id from list_categories) to get a single node's own brief. Omitting both returns an error. | `category_id` (top-level slug) *or* `subcategory_id` (numeric node id) — pass exactly one |
| `get_product` | Get a product's full profile: specs, full description, feature bullets, ratings, price,
trend, dimension scores/percentiles, facts check, red-flag signals, and sentiment.
profile.full_description carries the complete listing description paragraph when available
in the source listing; otherwise it is null (specifications and feature_bullets remain present). | `asin` |
| `search_products` | Search for candidate products matching a query, each with a data-maturity tier.
query: 1-8 space-separated plain words (no SQL/special chars).
category_id: optional top-level category slug from list_categories (e.g. "pet-supplies").
sort (enum): price_asc | price_desc | rating_desc | review_count_desc. Omit for relevance order.
Relevance (default order) weights title match (3) > brand match (2) > feature-bullet match (1) per term; every term must match at least one field. matched reports the total hit count (matched=0 means no product matched every term). limit (1-100, default 20) / offset paginate; include_rating_distribution (default false) adds the rating_breakdown histogram.
Filters: min_price / max_price in USD (floats), min_rating on a 0-5 scale.
Invalid values return an error listing the allowed enum. | `query` (1-8 words), optional `category_id`, `sort` (*price_asc \| price_desc \| rating_desc \| review_count_desc*), `min_price`/`max_price` (USD), `min_rating` (0-5), `limit`/`offset` (paging), `include_rating_distribution` |
| `compare_products` | Compare two to five products side-by-side across dimensions.
asins: a list of 2-5 valid ASINs (10-char alphanumeric, e.g. "B08N5WRWNW").
Fewer than 2 or more than 5 items returns an error. | `asins[]` (2-5 valid ASINs) |
| `request` | Fetch structured data by URL or ASIN with optional field filters.
Pass either url (an Amazon product page URL) or asin (10-char alphanumeric).
fields (optional enum): profile | price | trend | ratings | competitiveness |
seller | facts_check | red_flags | sentiment | data_limitations.
live (optional, default false): when true, additionally hits a live data endpoint (~15-30s) and appends a "live" block with the freshest price, stock,
Buy Box seller, rating, and review count, plus data_as_of and is_stale flags.
Unknown field values return an error with the full list of allowed fields. | `url` *or* `asin`, optional `fields` (*profile \| price \| trend \| ratings \| competitiveness \| seller \| facts_check \| red_flags \| sentiment \| data_limitations*), optional `live` |
| `get_price` | Get a product's latest price and product-page link. | `asin` |
| `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. Answers "is now a good time to buy" style questions from historical data; it is a stored snapshot, not a real-time quote (call scrap_page for live price). | `asin` |
| `scrap_page` | Scrape a product page in real time for the latest price, stock, Buy Box seller, rating, and review count. Typically returns in 15-30 seconds, excluding first-time cold start and queueing. The response carries data_as_of (when the platform observed the data) and an is_stale flag for freshness judgment. | `asin` *or* `url` |
| `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. | `brand_name` (exact or partial match) |

## Suggested flow

```
Intent → Discovery (list_categories, get_top100)
       → Filter/Compare (get_sub_category_brief, search_products, get_product, compare_products)
       → Verify (get_product: facts check + red flags + sentiment)
       → Transact (get_price, get_price_change, request; scrap_page only when the latest snapshot is required)
```

## Response conventions

- Every response carries `notes` with `confidence`, `confidence_basis`, `data_as_of`, `data_age_days`, `is_stale` (and `sample_size` where applicable).
- `get_product.profile.full_description` carries the complete listing description paragraph when available in the source listing; otherwise it is null (`specifications` and `feature_bullets` remain present).
- `get_top100` items may carry `buyer_signal: watch` — flags suspicious review-manipulation cases. It is not a recommendation.
- `get_product` exposes the facts check (Amazon user-review topic sentiment only) with no synthesis. Each claim carries its verdict plus `evidence_source`, which tells whether the quote came from an Amazon aspect summary or a review body. Red-flag signals flag suspicious review-manipulation cases as `watch`; `avoid_strong` is no longer emitted.
- Quantitative fields return `insufficient_sample` when the sample is insufficient.
- Product links are Amazon product-page URLs with no promotional tags; this service derives no commercial benefit from links.
- BSR ranking is an objective representation of Amazon's official best-seller list, presented without evaluation.
- `compare_products` is a side-by-side presentation with no ranking of better or worse. Judge for yourself.
- `scrap_page` is a real-time scrape that typically returns in 15-30 seconds, excluding first-time cold start and queueing: call only when the latest price or stock is required; check `data_as_of` and `is_stale` in the response.

## Example prompts

1. "Show me the Top-100 BSR list in Amazon's pet-feeder category" → `list_categories` + `get_top100`
2. "Compare the selling points and prices of these pet feeders" → `compare_products` + `get_price`
3. "Does this product show signs of review manipulation?" → `get_product` (red-flag signal)
4. "Are this product's core selling points contradicted by users?" → `get_product` (facts check)

## Full documentation

All tool guides in one file: [/docs/full.md](/docs/full.md) — also linked from the [docs center](/docs).