Skip to main content
Glama

Adicionar cupom

add_coupon
Idempotent

Cadastra (ou atualiza) cupons no bot. Para UM cupom, informe "code" (o código) OU "url" (cupom resgatável no link, sem código); para VÁRIOS, mande a lista em "coupons" (até 50 por chamada, cada item com os mesmos campos) numa chamada só, em vez de uma chamada por cupom. Opcionalmente loja (site/site_id), descrição, validade, início de vigência e os campos DETALHADOS do desconto (discount_type/discount_value/min_purchase/max_discount/is_cashback). O upsert deduplica por loja+code (ou loja+url quando sem código): não precisa de list_coupons antes para evitar duplicata na mesma loja. Com convert_url:true, a "url" vira link de afiliado antes de salvar (no lote, cada link distinto é convertido uma vez); se a conversão falhar, o cupom não é salvo. No lote, a resposta traz "results" com o que entrou e o que falhou por item (index, code, ok, error). Requer o módulo de Cupons ativo no bot.

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

Input Schema

NameRequiredDescriptionDefault
urlNoLink do cupom. Use sem "code" para um cupom resgatável direto no link.
codeNoCódigo do cupom (ex.: BLACK10). Opcional se informar "url".
siteNoLoja ou marketplace do cupom (ex.: Shopee). Sem nome/ID, identifica pelo domínio mapeado do link.
couponsNoLote de cupons (até 50), cada um com code OU url e os demais campos. convert_url no topo vale para todos os itens que não disserem o contrário.
site_idNoID do site obtido em list_coupon_categories. Tem prioridade sobre o nome e a identificação automática.
raw_textNoOpcional. Texto original do cupom (trilha de auditoria da ingestão).
starts_atNoInício de vigência — data ISO ou epoch. Antes dessa data o cupom não aparece como ativo. NUNCA use DD/MM/AAAA. Opcional.
expires_atNoValidade. Prefira data ISO com hora e fuso, ex.: "2026-12-31T23:59:59-03:00" (fim do dia no horário de Brasília). Data solta ("2026-12-31") é interpretada como meia-noite UTC — o cupom expira às 21h do dia ANTERIOR no Brasil. Também aceita epoch Unix em segundos ou milissegundos. NUNCA use DD/MM/AAAA. Opcional.
convert_urlNoSe true, converte a "url" em link de afiliado antes de cadastrar. Se a conversão falhar, o cupom NÃO é salvo (nunca se publica a URL crua). Padrão: false.
descriptionNoDescrição/condições do cupom.
is_cashbackNoOpcional. true = o cupom é cashback (não desconto direto no carrinho).
is_sold_outNoOpcional. true = marca o cupom como ESGOTADO (o bot exibe o selo "Esgotado" em vez do botão de resgate); false = volta a disponível. Como o cadastro é upsert (dedup por loja+code ou loja+url), repita o mesmo code/url do cupom já cadastrado para atualizar só esse estado.
max_discountNoOpcional. Teto do desconto (em reais). SÓ se aplica a discount_type="percent" — em "amount" (ou sem tipo) é ignorado/limpo automaticamente.
min_purchaseNoOpcional. Valor mínimo da compra (em reais) para o cupom valer.
discount_typeNoOpcional. Tipo de desconto: "percent" (em %) ou "amount" (em reais). Combine com discount_value.
discount_valueNoOpcional. Valor do desconto — em % quando discount_type="percent", em reais quando "amount" (ex.: 15 = 15% ou R$15).

Output Schema

NameRequiredDescriptionDefault
addedNoLote: quantos entraram.
couponNoO cupom salvo (um cupom).
failedNoLote: quantos falharam.
resultsNoLote: um por item, com index, code, ok, coupon ou error e hint.
successNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses the upsert dedup key (loja+code or loja+url), the convert_url failure policy (coupon is not saved, raw URL never published), the batch response shape ('results' with index, code, ok, error), and the required module. These are exactly the side effects and failure modes an agent cannot infer from readOnlyHint/idempotentHint.

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?

Front-loaded with the primary decision (single vs batch) and then layered with progressively finer detail. It is a dense single paragraph that is longer than typical, but nearly every clause carries distinct operational information; only the trailing module requirement could have been placed earlier.

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 16-parameter mutation tool, the description covers the critical ambiguities: mutual exclusivity of code/url, batch limits, upsert semantics, conversion failure behavior, and an activation precondition. Return values are covered by the output schema, and the description still previews the batch 'results' payload.

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 the baseline is 3; the description still adds value by framing the code/url exclusivity, the 50-item batch cap, and grouping the discount fields (discount_type/discount_value/min_purchase/max_discount/is_cashback) as an optional detailed block. It does not restate per-field formats, but it doesn't need to.

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 description opens with a specific verb and resource ('Cadastra (ou atualiza) cupons no bot') and immediately disambiguates the two shapes of the operation: single coupon via code/url vs. bulk via 'coupons'. It is clearly distinguishable from siblings like list_coupons or remove_coupon without opening any schema.

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?

Gives explicit selection rules (one coupon → code OU url; many → 'coupons' up to 50 in a single call, explicitly instead of one call per coupon) and a strong precondition ('Requer o módulo de Cupons ativo no bot'). It also preempts an alternative workflow by stating that list_coupons is unnecessary before an upsert because of store+code/url dedup.

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