# 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. | — |
| `get_top100` | Get the Amazon US Top-100 Best Sellers Rank list for a product category. | `category_id` (top-level slug) *or* `subcategory_id` (numeric node id) — pass exactly one |
| `get_category_brief` | Get a structured brief for a category: market overview, factors, gotchas, questions, needs, and keywords. | `category_id` |
| `get_product` | Get a product's full profile: specs, description, ratings, price, trend, facts check, red-flag signals, and sentiment. | `asin` |
| `search_products` | Search for candidate products matching a query, each with a data-maturity tier. | `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) |
| `compare_products` | Compare two to five products side-by-side across dimensions. | `asins[]` (2-5 valid ASINs) |
| `request` | Fetch structured data by URL or ASIN with optional field filters. | `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. | `asin` |
| `scrap_page` | Scrape a product page in real time for the latest price, stock, Buy Box seller, rating, and review count. | `asin` *or* `url` |
| `get_brand` | Get a brand's full profile from the brand registry: tier, product count, review count, rating breakdown, and more. | `brand_name` (exact or partial match) |

## Suggested flow

```
Intent → Discovery (list_categories, get_top100)
       → Filter/Compare (get_category_brief, search_products, get_product, compare_products)
       → Verify (get_product: three-source 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: avoid_strong` — a high-confidence red-flag signal only. It is not a recommendation.
- `get_product` exposes the three-source facts check (user reviews / social UGC / seller self-consistency) independently, with no synthesis. Red-flag signals are layered by confidence; only high-confidence suspicious cases are marked `avoid_strong`.
- 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 3-10 seconds: 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 or social media?" → `get_product` (three-source facts check)

## Full documentation

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