Percentile-rank a single product price against tracked Amazon competitors in a CPG category.

Use when a multi-channel CPG brand asks where their Amazon listing price sits against 100+ tracked products — e.g. checking whether a $4.99 granola is competitively positioned on Amazon, auditing whether a retail MSRP is reasonable against Amazon reality before a buyer meeting, or sanity-checking a wholesale-to-retail markup.

Returns: percentile_rank (string, e.g. "72nd percentile"), price_index_label (ratio vs. category median), position (Value / Parity / Premium), category (resolved name), last_refreshed (ISO timestamp), cta (link to full per-SKU report).

Args: price: Product price in dollars (e.g. 4.99). Must be > 0 and <= 10000. category: Exact category name — Grocery & Gourmet Food, Health & Beauty, Household, or Pet Supplies. Case-insensitive. Call list_categories first to confirm available names.

Report the 30-day Amazon price-trend direction for a CPG category.

Use when a pricing ops lead asks whether category pricing is rising, stable, or falling — e.g. setting retail promo calendar against an Amazon backdrop, deciding whether to raise wholesale prices during inflationary windows, or catching a price war before it spills into their channel.

Returns: trend_direction (Rising / Stable / Falling / Insufficient Data), trend_window ("30 days"), confidence (note with product count), category (resolved name), last_refreshed, cta.

Args: category: Exact category name — Grocery & Gourmet Food, Health & Beauty, Household, or Pet Supplies. Case-insensitive.

Return pricing-tier breakdown and category stats for an Amazon CPG category.

Use when a brand is sizing up a shelf — e.g. evaluating whether a new SKU should enter at budget / midmarket / premium tier, benchmarking their retail pricing against Amazon tier structure, or preparing for a retail buyer meeting that will ask "what's the typical shelf price here?".

Returns: category (resolved name), product_count (bucketed, e.g. "100+ products"), price_tiers (dict with budget / midmarket / premium dollar bands, rounded to nearest $0.50 for abstraction), median_price, trend_direction, last_refreshed, cta.

Args: category: Exact category name — Grocery & Gourmet Food, Health & Beauty, Household, or Pet Supplies. Case-insensitive.

Compare multiple product prices against an Amazon CPG category's peers.

Use when a multi-channel CPG brand needs to stack-rank their SKUs — e.g. identifying which SKUs are underpriced relative to Amazon peers, flagging products where the Amazon Buy Box sits materially below the retail MSRP, or building a cross-channel price-audit table for an ops review. Replaces manual store walks and spreadsheet comparisons.

Returns: comparisons (list, per product: name, price, percentile_rank, position, vs_median), category, category_trend, sample_size, last_refreshed, cta.

Args: products: List of items, each a dict with 'name' (string) and 'price' (number in dollars). Minimum 1 item; 3-20 is the useful range. category: Exact category name — Grocery & Gourmet Food, Health & Beauty, Household, or Pet Supplies. Case-insensitive.

List Amazon CPG categories with current product counts and trend direction.

Use as the first call in any pricing-analysis workflow — returns the exact category names expected by other tools, plus product count and trend for each. Lightweight; safe to call before any category-specific query.

Returns: categories (list of {name, product_count, trend_direction, last_refreshed}), note (summary of coverage), cta.

Covers Grocery & Gourmet Food, Health & Beauty, Household, and Pet Supplies.

Report PricePilot server health, data freshness, and degraded-state reason.

Use to check whether category seeding is current (staleness threshold is 10 days) before trusting downstream tool output. Returns degraded status with reason if data is overdue; healthy otherwise.

Returns: server (name), version, status (healthy / degraded), categories_available, data_freshness (ISO timestamp of last seed), degraded_reason (null if healthy).