> For the complete documentation index, see [llms.txt](https://whalecoupons.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whalecoupons.gitbook.io/docs/tool-reference.md).

# Tool reference

The server exposes five tools. All of them are read-only and idempotent. In MCP annotation terms they are `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true` and `openWorldHint: false`.

Every tool returns two things:

* `content`: a short plain-text summary the model can read.
* `structuredContent`: JSON that matches the tool's `outputSchema`.

The examples below are real responses from `https://whalecoupons.co/mcp`, recorded on October 19, 2026 and trimmed. Codes and discounts change as stores update their offers. In the examples, `shop_link` values are replaced with a placeholder.

## Store result object

`find_coupons`, `search_stores`, `get_store` and `list_largest_discounts` all describe a store with the same object:

| Field          | Type   | Always present | Description                                                                     |
| -------------- | ------ | -------------- | ------------------------------------------------------------------------------- |
| `store`        | string | yes            | Store name                                                                      |
| `code`         | string | yes            | Coupon code to enter at checkout                                                |
| `discount`     | string | yes            | The discount, such as `"10% off"` or `"$100 off"`                               |
| `how_to_apply` | string | yes            | Plain-language instructions                                                     |
| `shop_link`    | string | yes            | Link that opens the store with the discount applied. This is an affiliate link. |
| `store_page`   | string | yes            | The store's page on whalecoupons.co                                             |
| `category`     | string | no             | One of the 14 categories                                                        |
| `min_order`    | string | no             | Minimum order, if the store sets one (for example `"69 USD"`)                   |
| `slug`         | string | no             | Store ID, for use with `get_store`                                              |

Results also include a `disclosure` string stating that Whale Coupons may earn a commission.

## Categories

`search_stores` and `list_largest_discounts` accept an optional `category`, which must be one of these values exactly:

`Automotive`, `Baby & kids`, `Beauty`, `Electronics`, `Fashion`, `Food & drink`, `Health & wellness`, `Home & kitchen`, `Learning`, `Other`, `Pets`, `Sports & outdoors`, `Toys & hobbies`, `Travel`

***

## find\_coupons

Finds the code for a **specific store or brand**. The input can be a store name, a domain or a full product URL. Returns up to 3 matching stores.

| Parameter | Type                | Required | Notes                                                                                                                         |
| --------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `store`   | string, 1–300 chars | yes      | Store or brand name, domain, or product/store page URL, exactly as the user gave it. Don't add words like "coupon" or "code". |

**Returns:** `found` (boolean), `match` (`"exact"`, `"partial"` or `"product"`), `query`, `results` (array of store objects), `suggested_category` (when nothing matched but the query looks like a product type), `disclosure`.

When no store has that name but the words describe a product, the server returns stores whose own catalog lists that product, with `found: false` and `match: "product"`.

**Example: store name**

```json
// arguments
{ "store": "Airwheel Luggage" }

// structuredContent
{
  "found": true,
  "match": "exact",
  "query": "Airwheel Luggage",
  "results": [
    {
      "store": "Airwheel Luggage",
      "code": "WHALECOUPONS",
      "discount": "18% off",
      "how_to_apply": "Open the link: the 18% off is applied automatically at checkout. If it doesn't show, enter code WHALECOUPONS.",
      "shop_link": "<store link>",
      "store_page": "https://whalecoupons.co/stores/airwheel-luggage/",
      "category": "Travel",
      "slug": "airwheel-luggage"
    }
  ],
  "disclosure": "Whale Coupons may earn a commission if you buy through these links. It costs you nothing extra."
}
```

**Example: product URL.** `{ "store": "https://www.saguaro.com/products/x" }` returns Saguaro Barefoot Shoes with `match: "exact"`.

**Example: product words instead of a store**

```json
// arguments
{ "store": "wireless headphones" }

// structuredContent (trimmed to 2 of 3 results)
{
  "found": false,
  "match": "product",
  "query": "wireless headphones",
  "results": [
    { "store": "MONODEAL", "code": "WHALECOUPONS", "discount": "10% off", "category": "Electronics", "slug": "monodeal", "...": "..." },
    { "store": "Nuvelon", "code": "WHALECOUPONS", "discount": "30% off", "category": "Electronics", "slug": "nuvelon", "...": "..." }
  ]
}
```

**Example: store not covered**

```json
// arguments
{ "store": "amazon" }

// content[0].text
"No Whale Coupons code found for \"amazon\". Whale Coupons covers thousands of independent online stores, updated daily; this store isn't one of them yet. All stores: https://whalecoupons.co/stores/"
```

***

## search\_stores

Finds stores with codes for a **product type or category**, such as "running shoes", "skincare" or "coffee". It first matches store names and the products each store lists on its own site, then fills in from the categories those product words point to (headphones → Electronics).

| Parameter  | Type                    | Required | Notes                                       |
| ---------- | ----------------------- | -------- | ------------------------------------------- |
| `query`    | string, up to 200 chars | no\*     | Product type, keyword or partial store name |
| `category` | enum                    | no\*     | One of the 14 categories                    |
| `limit`    | integer 1–25            | no       | Default 10                                  |

\* Give `query`, `category` or both.

**Returns:** `stores` (array), `total` (number of matching stores), `category`, `matched_categories` (categories inferred from the query), `hint` (what to try when nothing matched), `disclosure`.

**Example**

```json
// arguments
{ "query": "running shoes", "limit": 2 }

// structuredContent
{
  "stores": [
    {
      "store": "Saguaro Barefoot Shoes",
      "code": "WHALECOUPONS",
      "discount": "10% off",
      "how_to_apply": "Open the link: the 10% off is applied automatically at checkout. If it doesn't show, enter code WHALECOUPONS.",
      "shop_link": "<store link>",
      "store_page": "https://whalecoupons.co/stores/saguaro-barefoot-shoes/",
      "category": "Fashion",
      "slug": "saguaro-barefoot-shoes"
    },
    {
      "store": "Manzonni",
      "code": "WHALECOUPONS",
      "discount": "10% off",
      "shop_link": "<store link>",
      "store_page": "https://whalecoupons.co/stores/manzonni/",
      "category": "Sports & outdoors",
      "slug": "manzonni",
      "...": "..."
    }
  ],
  "total": 944,
  "category": null,
  "matched_categories": ["Fashion", "Sports & outdoors"]
}
```

The text summary for this call begins: *"88 stores matched "running shoes" by name or by the products on their own site; showing 2. The closest categories (Fashion, Sports & outdoors) have 856 more stores with codes."*

**No match**

```json
{
  "stores": [],
  "total": 0,
  "category": null,
  "hint": "No store or product type matched \"zzqqxx\". Try search_stores with one of these categories: Automotive, Baby & kids, Beauty, ..."
}
```

***

## get\_store

Returns one store's full details again, using the `slug` from an earlier result. For a store name, domain or URL, use `find_coupons` instead.

| Parameter | Type                | Required | Notes                                                    |
| --------- | ------------------- | -------- | -------------------------------------------------------- |
| `slug`    | string, 1–120 chars | yes      | Exactly as returned before, such as `"airwheel-luggage"` |

**Returns:** `found`, `store` (a store object), `disclosure`.

```json
// arguments
{ "slug": "airwheel-luggage" }

// structuredContent
{
  "found": true,
  "store": {
    "store": "Airwheel Luggage",
    "code": "WHALECOUPONS",
    "discount": "18% off",
    "how_to_apply": "Open the link: the 18% off is applied automatically at checkout. If it doesn't show, enter code WHALECOUPONS.",
    "shop_link": "<store link>",
    "store_page": "https://whalecoupons.co/stores/airwheel-luggage/",
    "category": "Travel",
    "slug": "airwheel-luggage"
  }
}
```

An unknown slug returns `{ "found": false }`.

***

## list\_categories

Lists the store categories, with the number of stores in each and its page on whalecoupons.co. It takes no parameters. You don't need to call it before `search_stores` or `list_largest_discounts`, because their `category` parameter already lists the valid names.

**Returns:** `categories` (array of `name`, `stores`, `page`) and `total_stores`.

```json
// structuredContent (trimmed to 3 of 14)
{
  "categories": [
    { "name": "Beauty", "stores": 384, "page": "https://whalecoupons.co/categories/beauty/" },
    { "name": "Fashion", "stores": 694, "page": "https://whalecoupons.co/categories/fashion/" },
    { "name": "Pets", "stores": 83, "page": "https://whalecoupons.co/categories/pets/" }
  ]
}
```

***

## list\_largest\_discounts

Lists stores whose code gives at least `min_discount` percent off, largest first. Fixed-amount discounts (such as "$30 off") are left out, because they can't be ranked by percentage.

| Parameter      | Type         | Required | Notes                           |
| -------------- | ------------ | -------- | ------------------------------- |
| `min_discount` | number 0–100 | no       | Minimum percent off. Default 15 |
| `category`     | enum         | no       | One of the 14 categories        |
| `limit`        | integer 1–25 | no       | Default 10                      |

**Returns:** `stores`, `total`, `category`, `disclosure` (and `hint` when nothing matched).

```json
// arguments
{ "min_discount": 30, "category": "Pets", "limit": 2 }

// structuredContent
{
  "stores": [
    {
      "store": "PetJoy",
      "code": "WHALECOUPONS",
      "discount": "35% off",
      "how_to_apply": "Open the link: the 35% off is applied automatically at checkout. If it doesn't show, enter code WHALECOUPONS.",
      "shop_link": "<store link>",
      "store_page": "https://whalecoupons.co/stores/petjoy/",
      "category": "Pets",
      "slug": "petjoy"
    },
    {
      "store": "Pawfect Bandanas",
      "code": "WHALECOUPONS",
      "discount": "30% off",
      "shop_link": "<store link>",
      "store_page": "https://whalecoupons.co/stores/pawfect-bandanas/",
      "category": "Pets",
      "slug": "pawfect-bandanas",
      "...": "..."
    }
  ],
  "total": 2,
  "category": "Pets"
}
```

***

## Server instructions

When a client connects, the server sends these instructions to the model:

> Use find\_coupons for a named store, brand, domain or product URL; search\_stores for a product type or category; list\_largest\_discounts when the user asks which stores have the biggest percentage off. Only state codes the tools return. Shop links are affiliate links: mention that Whale Coupons may earn a commission, and that the total should be confirmed at checkout.
