TLD Bench

Promotions and coupons

list_coupons

Read-onlyIdempotent

Use this when the user asks for promo codes, coupons, deals or first-year discounts. Returns coupon codes as each registrar's own API or promotions page lists them (code, operation, extensions, discount, limits, end date, last seen at the source, an example price with the code), and running promotional prices anyone gets without a code. Codes are seen at the source, not tested at checkout; quote the list price and renewal too.

Input Schema

Name	Required	Description
`tld`	No	an extension: com, .io, co.uk or рф
`limit`	No
`currency`	No	ISO 4217 currency for prices (default USD); converted at the ECB's daily rate, disclosed in `fx`
`operation`	No
`registrar`	No
`active_only`	No	false: also coupons that expired in the last 30 days

Output Schema

Name	Required	Description
`fx`	Yes	How converted prices were converted; null when nothing needed converting.
`note`	Yes
`as_of`	Yes
`coupons`	Yes	coupon codes seen at the registrars' own sources, by registrar
`currency`	Yes	ISO 4217
`promotions`	Yes	running promotional prices, cheapest first

Schema Changelog

Changes observed during successful MCP inspections.

Changed34 schema fields changedNov 6, 2026

addedInput schema / properties / active_only

Added value: +{
+  "default": true,
+  "description": "false: also coupons that expired in the last 30 days",
+  "type": "boolean"
+}

changedOutput schema / properties / coupons / description

Previous value: -"coupon codes seen at their source (none collected yet)"New value: +"coupon codes seen at the registrars' own sources, by registrar"

addedOutput schema / properties / coupons / items / description

Added value: +"A coupon code as the registrar's own API, price list or promotions page shows it. Seen at the source, never tested at checkout."

addedOutput schema / properties / coupons / items / properties / all_tlds

Added value: +{
+  "description": "the source says the code applies to every extension",
+  "type": "boolean"
+}

addedOutput schema / properties / coupons / items / properties / code / examples
```
Added value: +[
+  "AWESOMENESS"
+]
```
changedOutput schema / properties / coupons / items / properties / code / type
```
Previous value: -[
-  "string",
-  "null"
-]New value: +"string"
```

addedOutput schema / properties / coupons / items / properties / description / examples

Added value: +[
+  "1.00 USD off a registration, first year only, 1 per customer"
+]

addedOutput schema / properties / coupons / items / properties / discount

Added value: +{
+  "properties": {
+    "amount": {
+      "anyOf": [
+        {
+          "description": "An amount in major units (12.99), in `currency`.",
+          "properties": {
+            "amount": {
+              "type": "number"
+            },
+            "currency": {
+              "description": "ISO 4217",
+              "examples": [
+                "USD"
+              ],
+              "pattern": "^[A-Z]{3}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "amount",
+            "currency"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "kind": {
+      "description": "amount: `amount` off; percent: `percent`% off; price: the price with the code is `amount`",
+      "enum": [
+        "amount",
+        "percent",
+        "price"
+      ],
+      "type": "string"
+    },
+    "native": {
+      "anyOf": [
+        {
+          "description": "An amount in major units (12.99), in `currency`.",
+          "properties": {
+            "amount": {
+              "type": "number"
+            },
+            "currency": {
+              "description": "ISO 4217",
+              "examples": [
+                "USD"
+              ],
+              "pattern": "^[A-Z]{3}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "amount",
+            "currency"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "`amount` as the source gives it, when it was converted"
+    },
+    "percent": {
+      "type": [
+        "number",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "kind",
+    "percent",
+    "amount",
+    "native"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / coupons / items / properties / ends_at

Added value: +{
+  "anyOf": [
+    {
+      "examples": [
+        "2026-11-06T04:12:00.000Z"
+      ],
+      "format": "date-time",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / coupons / items / properties / example

Added value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "price": {
+          "description": "An amount in major units (12.99), in `currency`.",
+          "properties": {
+            "amount": {
+              "type": "number"
+            },
+            "currency": {
+              "description": "ISO 4217",
+              "examples": [
+                "USD"
+              ],
+              "pattern": "^[A-Z]{3}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "amount",
+            "currency"
+          ],
+          "type": "object"
+        },
+        "tld": {
+          "type": "string"
+        },
+        "with_code": {
+          "description": "An amount in major units (12.99), in `currency`.",
+          "properties": {
+            "amount": {
+              "type": "number"
+            },
+            "currency": {
+              "description": "ISO 4217",
+              "examples": [
+                "USD"
+              ],
+              "pattern": "^[A-Z]{3}$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "amount",
+            "currency"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "tld",
+        "price",
+        "with_code"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "one extension's current price and the price with the code"
+}

addedOutput schema / properties / coupons / items / properties / expired_at

Added value: +{
+  "anyOf": [
+    {
+      "examples": [
+        "2026-11-06T04:12:00.000Z"
+      ],
+      "format": "date-time",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / coupons / items / properties / expired_reason

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "ended",
+        "missing"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "ended: past its end date; missing: its source stopped listing it (2 consecutive collections)"
+}

addedOutput schema / properties / coupons / items / properties / expires_at / description
```
Added value: +"same as ends_at"
```

addedOutput schema / properties / coupons / items / properties / first_seen_at

Added value: +{
+  "examples": [
+    "2026-11-06T04:12:00.000Z"
+  ],
+  "format": "date-time",
+  "type": "string"
+}

addedOutput schema / properties / coupons / items / properties / first_year_only
```
Added value: +{
+  "type": [
+    "boolean",
+    "null"
+  ]
+}
```

addedOutput schema / properties / coupons / items / properties / last_seen_at

Added value: +{
+  "description": "the last collection that saw the code at its source",
+  "examples": [
+    "2026-11-06T04:12:00.000Z"
+  ],
+  "format": "date-time",
+  "type": "string"
+}

addedOutput schema / properties / coupons / items / properties / max_per_customer

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / coupons / items / properties / new_customers_only
```
Added value: +{
+  "type": [
+    "boolean",
+    "null"
+  ]
+}
```
addedOutput schema / properties / coupons / items / properties / observed_at / description
```
Added value: +"same as last_seen_at"
```

addedOutput schema / properties / coupons / items / properties / operation

Added value: +{
+  "description": "register (a new registration, year 1), renew (one more year), transfer (move in; usually adds a year), restore (redeem an expired domain in its redemption period)",
+  "enum": [
+    "register",
+    "renew",
+    "transfer",
+    "restore"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / coupons / items / properties / registrar / properties / note

Added value: +{
+  "anyOf": [
+    {
+      "description": "A short, sourced note about the registrar's prices (not a price we rank by).",
+      "properties": {
+        "checked_on": {
+          "anyOf": [
+            {
+              "examples": [
+                "2026-11-05"
+              ],
+              "format": "date",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "text": {
+          "examples": [
+            "NameSilo's free discount program prices .com at $12.00 (retail $19.99)."
+          ],
+          "type": "string"
+        },
+        "url": {
+          "description": "where the note's facts come from",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "text",
+        "url",
+        "checked_on"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / coupons / items / properties / registrar / properties / pricing_tier

Added value: +{
+  "description": "retail: anyone can buy at these prices; reseller: the prices are a reseller account's tier (eNom's Silver), left out of consumer rankings unless include_resellers=true",
+  "enum": [
+    "retail",
+    "reseller"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / coupons / items / properties / source

Added value: +{
+  "properties": {
+    "id": {
+      "examples": [
+        "porkbun"
+      ],
+      "type": "string"
+    },
+    "kind": {
+      "description": "api: the registrar's own price API; price_list: a file or JSON the registrar publishes; page: its price page; mirror: a third party's copy of the registrar's prices",
+      "enum": [
+        "api",
+        "price_list",
+        "page",
+        "mirror"
+      ],
+      "type": "string"
+    },
+    "url": {
+      "description": "where the price was read",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "kind",
+    "url"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / coupons / items / properties / stale

Added value: +{
+  "description": "its source hasn't been collected for 3x its interval",
+  "type": "boolean"
+}

addedOutput schema / properties / coupons / items / properties / starts_at

Added value: +{
+  "anyOf": [
+    {
+      "examples": [
+        "2026-11-06T04:12:00.000Z"
+      ],
+      "format": "date-time",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / coupons / items / properties / status

Added value: +{
+  "enum": [
+    "active",
+    "expired"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / coupons / items / properties / terms

Added value: +{
+  "description": "the source's terms, as text",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / coupons / items / properties / tlds / description
```
Added value: +"the extensions the code applies to; empty when all_tlds"
```

changedOutput schema / properties / coupons / items / required

Previous value: -[
-  "registrar",
-  "code",
-  "tlds",
-  "description",
-  "expires_at",
-  "observed_at",
-  "source_url"
-]New value: +[
+  "registrar",
+  "code",
+  "operation",
+  "tlds",
+  "all_tlds",
+  "description",
+  "discount",
+  "first_year_only",
+  "new_customers_only",
+  "max_per_customer",
+  "starts_at",
+  "ends_at",
+  "expires_at",
+  "terms",
+  "status",
+  "expired_at",
+  "expired_reason",
+  "first_seen_at",
+  "last_seen_at",
+  "observed_at",
+  "stale",
+  "example",
+  "source",
+  "source_url"
+]

addedOutput schema / properties / fx

Added value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "date": {
+          "description": "the date of the primary rates (ECB reference rates)",
+          "examples": [
+            "2026-11-05"
+          ],
+          "format": "date",
+          "type": "string"
+        },
+        "rates": {
+          "additionalProperties": {
+            "properties": {
+              "date": {
+                "examples": [
+                  "2026-11-05"
+                ],
+                "format": "date",
+                "type": "string"
+              },
+              "rate": {
+                "description": "units of the response currency per unit of this currency",
+                "type": "number"
+              },
+              "source": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "rate",
+              "date",
+              "source"
+            ],
+            "type": "object"
+          },
+          "description": "every rate used in this response, by native currency",
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "source": {
+          "examples": [
+            "European Central Bank euro foreign exchange reference rates"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "date",
+        "source",
+        "rates"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "How converted prices were converted; null when nothing needed converting."
+}

addedOutput schema / properties / promotions / items / properties / promo_limited

Added value: +{
+  "description": "capped per customer or for first-time customers only",
+  "type": "boolean"
+}

addedOutput schema / properties / promotions / items / properties / registrar / properties / note

Added value: +{
+  "anyOf": [
+    {
+      "description": "A short, sourced note about the registrar's prices (not a price we rank by).",
+      "properties": {
+        "checked_on": {
+          "anyOf": [
+            {
+              "examples": [
+                "2026-11-05"
+              ],
+              "format": "date",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "text": {
+          "examples": [
+            "NameSilo's free discount program prices .com at $12.00 (retail $19.99)."
+          ],
+          "type": "string"
+        },
+        "url": {
+          "description": "where the note's facts come from",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "text",
+        "url",
+        "checked_on"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / promotions / items / properties / registrar / properties / pricing_tier

Added value: +{
+  "description": "retail: anyone can buy at these prices; reseller: the prices are a reseller account's tier (eNom's Silver), left out of consumer rankings unless include_resellers=true",
+  "enum": [
+    "retail",
+    "reseller"
+  ],
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "as_of",
-  "currency",
-  "coupons",
-  "promotions",
-  "note"
-]New value: +[
+  "as_of",
+  "currency",
+  "fx",
+  "coupons",
+  "promotions",
+  "note"
+]

First observedNov 6, 2026

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety needs no restating. The description's real value-add is the reliability caveat: codes are 'seen at the source, not tested at checkout,' plus the instruction to quote list price and renewal alongside. That is genuinely useful. It does not mention coverage gaps per registrar or what happens when no coupons exist, so the disclosure is helpful but partial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both front-loaded: trigger first, then return shape and the quoting caveat. It is dense but every clause contributes something (fields, provenance, pricing advice). Minor cost is that the long parenthetical field list reads as a run-on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is optional, and the description still covers provenance and the list-price caveat well. What is missing is how the six optional filters combine and how to interpret an empty result set across registrars. For a six-parameter, multi-source lookup tool, that leaves a real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%: tld, currency and active_only carry schema descriptions, while limit, operation and registrar have none. The description adds no parameter guidance at all, not even that results can be scoped by extension, registrar or operation. With half the parameters undocumented in the schema and nothing compensating in the text, an agent must guess at filtering behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and output: coupon codes as each registrar's API or promotions page lists them, plus code-free promotional prices. It enumerates returned fields (code, operation, extensions, discount, limits, end date, last seen, example price), which sharply separates it from price siblings like cheapest_registrar or compare_tld_prices. It stops short of naming those siblings explicitly, so the differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The opening clause gives an explicit trigger: 'Use this when the user asks for promo codes, coupons, deals or first-year discounts.' That is a clear use context. It does not say when not to use it or name an alternative tool, and it gives no guidance on combining it with list-price tools, so it falls short of a full when/when-not/alternatives statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All TLD Bench tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?