Tool reference
The eight read-only WhatWins MCP tools, their purpose and how to inspect the authoritative live schema.
WhatWins exposes eight bounded tools. Inputs are validated server-side and each successful result carries coverage and source metadata.
| Tool | Use it for |
|---|---|
search_ads | Search and rank verified Meta or Google creatives |
get_top_organic_posts | Rank Instagram, TikTok and YouTube organic posts |
compare_shop_traffic | Compare current and historical monthly visits |
compare_live_ads | Compare observed Meta or Google ad history |
get_shop_products | Query products for selected tracked shops |
get_shop_overview | Read positioning, market, pricing, review and tech data |
discover_products | Find products across the indexed catalog |
discover_shops | Find specialist competitor shops by niche |
Inspect the live schema
tools/list is always authoritative. It returns JSON Schema for the version currently deployed.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}Shared input rules
- A maximum of five
storeIdsmay be used in shop-scoped calls. - Result limits are bounded per tool.
- Country filters use two-letter uppercase codes such as
USorGB. - Global discovery calls do not accept tracked
storeIds. - Price filters must be non-negative and
minPriceshould not exceedmaxPrice.
Shared result envelope
Tool data is returned with verification metadata:
{
"tool": "discover_shops",
"data": [],
"sources": [],
"coverage": {
"status": "verified"
},
"elapsedMs": 142
}coverage.status can be verified, partial or unsupported. Never present partial coverage as a complete market census.