Skip to main content
Glama

bulk_create_coupon

Idempotent

Create the SAME discount code across many apps in one call: the portfolio-promo shortcut (e.g. a summer sale on every owned app). WRITE, human-gated: a real create requires an elicitation-capable client; the human enters the coupon terms ONCE in a form (overriding the arguments here) and that one approval covers the whole batch. Clients without elicitation are refused UNLESS the deployment sets SPARK_PAY_MCP_ALLOW_UNELICITED_WRITES=1 and the call passes confirm_write:true, which is how Claude Code and cron reach these writes; dry_run still works anywhere. Runs each app through the same fully-guarded create as create_coupon. Unlike a single call it does NOT fail the batch when an app already has the code: that app is reported skipped and the rest are still created. Returns a per-app outcome matrix plus created/skipped/failed counts. Use dry_run:true first to see which apps would create vs skip. Pass explicit app_ids (from list_apps). There is deliberately no 'all apps' shortcut, so a discount can't hit an app you didn't name.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "app_ids": "<app_ids>",
      "code": "<code>",
      "discount_percent": "<discount_percent>"
    },
    "name": "bulk_create_coupon"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeYes
listedNo
app_idsYes
dry_runNo
max_usesNo
expires_atNo
descriptionNo
confirm_writeNo
applies_to_tiersNo
discount_percentYes
confirm_high_discountNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / confirm_write
      Added value: +{
      +  "default": false,
      +  "type": "boolean"
      +}
  2. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare non-readOnly, openWorld and idempotent, so the bar is lower, but the description goes well beyond them: human-gated elicitation, form override of arguments, the SPARK_PAY_MCP_ALLOW_UNELICITED_WRITES=1 plus confirm_write escape hatch, and refusal for non-elicitation clients. It also discloses partial-failure semantics (per-app skipped instead of batch failure) and the returned count matrix. It does not explain behavior of several guard parameters such as confirm_high_discount, which keeps it off 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.

Conciseness4/5

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

Front-loaded with the core purpose and the safety model, and every clause carries information (batch semantics, elicitation requirement, dry-run advice, app_ids constraint). The dense run-on middle sentence packing env var, flag name and dry_run exception is harder to parse than it needs to be, but there is little dead weight.

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

Completeness4/5

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

For a write tool with no output schema and no annotation beyond hints, the description covers gating, prerequisites, failure semantics and a return-value sketch (per-app outcome matrix plus created/skipped/failed counts). The remaining gap is per-parameter meaning for roughly half the schema, which the description never addresses.

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 0% across 11 parameters, so the description must compensate and only partly does: it gives real meaning for app_ids (sourced from list_apps, no all-apps option), dry_run, confirm_write, and implies code/discount_percent via 'summer sale' and 'same discount code'. listed, max_uses, expires_at, description, applies_to_tiers and confirm_high_discount carry no semantic explanation, and confirm_high_discount in particular is a guard an agent could trip on.

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?

Opens with a specific verb, resource and scope: 'Create the SAME discount code across many apps in one call', and names the distinguishing behavior versus create_coupon (batch does not fail on duplicate codes). An agent can separate this from create_coupon and bulk_delete_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?

Explicit routing: use this for portfolio-wide promos, pass explicit app_ids from list_apps, and there is 'deliberately no all apps shortcut'. It also prescribes the workflow ('Use dry_run:true first to see which apps would create vs skip') and states the eligibility condition for unelicited clients, so when-to-use and when-not are both covered.

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