Skip to main content
Glama

Listar cupons

list_coupons
Read-only

Lista os cupons cadastrados no bot (código, descrição, link, validade e os campos detalhados do desconto: discountType, discountValue, minPurchase, maxDiscount, isCashback e isSoldOut). Por padrão retorna só os vigentes (status="active"); use status="expired" para os vencidos (reativáveis com activate_coupon) ou status="all" para todos. Filtre com "q" (código/descrição/URL) e a loja com "site" (nome, slug ou domínio, sem precisar de ID) ou "site_id" (ID de list_coupon_categories). A resposta traz "total", "has_more" e "next_offset": com has_more true, repita a chamada com offset = next_offset.

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": "list_coupons"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoFiltro por código, descrição ou URL (opcional).
siteNoOpcional. Nome, slug ou domínio da loja (sem caixa), alternativa ao site_id. Ex.: "shopee".
limitNoMáximo de cupons (1 a 200; padrão 50).
offsetNoDeslocamento para paginação (0 = início). Para a próxima página, use o next_offset da resposta.
statusNoFiltro de status: "active" (padrão, só vigentes), "expired" (expirados por data — úteis para reativar com activate_coupon) ou "all" (todos).active
site_idNoOpcional. ID da loja (de list_coupon_categories).

Output Schema

NameRequiredDescriptionDefault
itemsNoCupons: id, code, description, url, validade e desconto.
totalNoQuantos casaram com o filtro (todas as páginas).
successNo
has_moreNotrue quando há mais itens depois desta página.
next_offsetNooffset da próxima página; null na última.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the default status filter, the exact pagination contract (has_more/next_offset), and the reactivation workflow hook. Minor deduction for restating the return field list, which the output schema already provides.

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?

Dense but front-loaded, with the default scope stated first and pagination last. Nearly every clause carries actionable information, though the parenthetical field enumeration overlaps with the output schema and could be trimmed.

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?

With an output schema, full annotation coverage, and 100% parameter description coverage, the description fills the remaining gaps (default filtering, pagination loop, site-vs-site_id relationship). An agent has everything needed to invoke it correctly.

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

Parameters4/5

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

Schema coverage is 100%, so a baseline of 3 applies. The description still earns extra credit by clarifying that "site" accepts nome/slug/domínio as an alternative to site_id and pointing site_id to list_coupon_categories, adding relational meaning beyond the schema.

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?

States a specific verb and resource ("Lista os cupons cadastrados no bot") and immediately enumerates the fields returned (código, descrição, link, validade, discountType, etc.), making its scope unmistakable. It is clearly distinguishable from siblings like add_coupon, remove_coupon and list_coupon_categories.

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

Usage Guidelines5/5

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

Explicitly describes the default behavior (only active coupons) and the alternatives (status="expired" for reactivation with activate_coupon, status="all" for everything). It also explains filtering by q/site/site_id and the pagination loop using has_more and next_offset, leaving nothing to inference.

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