Skip to main content
Glama

search_promotions

Read-onlyIdempotent

Search current promotions, coupons, sales, and deals across retailers. Filter by retailer, category, promotion type, coupon availability, or expiry; full-text search over titles/descriptions; cursor pagination via "after". Returns active promotions by default (set active=false to include expired/upcoming).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_promotions"
  }
}

Input Schema

NameRequiredDescriptionDefault
afterNoSigned pagination cursor from the previous response (next_cursor). Omit for the first page.
limitNoMax promotions per page (1-100, default 25). Paginate via next_cursor for more.
activeNoWhen true (default), only return promotions currently within their active date window. Set false to include expired/upcoming promotions.
sort_byNoSort order. Omit for the default ordering. Must be consistent across paginated requests.
categoryNoFilter by category (exact match, e.g. "Apparel").
retailer_idNoFilter to one or more retailers. Comma-separated retailer IDs (e.g. "kohls,macys"). Use list_retailers to get valid IDs. Omit to search all retailers.
search_queryNoFull-text search over the promotion title and description.
promotion_typeNoFilter by promotion type (e.g. "coupon", "percentage-off", "free-shipping").
advertiser_nameNoFilter by the brand or merchant name (exact match).
has_coupon_codeNoIf true, only return promotions that include a coupon code.
expiring_within_daysNoOnly return promotions ending within this many days from now.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / advertiser_name / description
      Previous value: -"Filter by the advertiser/brand name (exact match)."New value: +"Filter by the brand or merchant name (exact match)."
  2. Added

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, open-world, non-destructive semantics, so the bar is lower. The description adds genuinely useful behavior beyond them: active-only default with the active=false escape hatch, and cursor pagination via 'after'. It does not discuss result volume or empty-result behavior, keeping it short of a 5.

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

Conciseness5/5

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

Two sentences, both front-loaded: capability and filter scope first, defaults and pagination second. No filler clauses and no repetition of the title.

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

Completeness5/5

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

For a read-only search tool with 11 optional parameters, a fully described schema, and no output schema, the description covers the essentials an agent needs: what it searches, how to filter, the active-by-default semantic, and how to paginate. Nothing material is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 11 parameters, including the sort consistency constraint and the list_retailers cross-reference. The description restates the filter categories and pagination at a high level without adding syntax or format detail, so the baseline 3 applies.

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

Purpose5/5

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

The opening sentence names a specific verb (Search) and resource (promotions, coupons, sales, deals) plus the scope (across retailers). This cleanly separates it from product-oriented siblings such as search_retailer_products and get_retailer_product, so an agent can route correctly without opening a schema.

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

Usage Guidelines3/5

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

The description enumerates the available filter axes and states the default active-only behavior, which implies when to use it, but it never names an alternative tool or states an explicit when-not condition. Usage is inferable rather than instructed.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources