# 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's Top-100 BSR in core subcategories. Fact-only, neutral, free.

## Endpoint

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

## Tool catalog (9 read-only tools)

| Tool | Description | Key inputs |
|---|---|---|
| `list_categories` | List the top-level product categories covered by this service. | — |
| `get_top100` | Get the Top-100 Best Sellers Rank list for a product category. | `category_id` (top-level) or `subcategory_id` (optional) |
| `get_category_brief` | Get a structured brief for a category: market overview, considering factors, gotchas, common questions, needs, and keywords. | `category_id` |
| `get_product` | Get a product's full profile: specs, ratings, price, trend, dimension scores/percentiles, three-source facts check, red-flag signals, and sentiment. | `asin` |
| `search_products` | Search for candidate products matching a query, each with a data-maturity tier. | `query`, `category_id` (optional) |
| `compare_products` | Compare two to five products side-by-side across dimensions. | `asins[]` (2-5) |
| `request` | Fetch structured data by URL or ASIN with optional field filters. | `url` or `asin`, optional `fields` |
| `get_price` | Get a product's latest price and product-page link. | `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` |

## 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, 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_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 slower (~30s): call only when the latest price or stock is required.

## 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)