Skip to main content
Glama

sales_code

Make a discount code for a post or video in the owner's connected store, with the store's default discount (set on the Sales page, 10% off unless changed), or register a code they already have (existing true: nothing is made in the store). Each order with the code counts for that post on the Sales page: on TikTok and Instagram, where captions have no clickable links, a code said in the video or written in the caption is the surest way to count sales. No credits. It creates a real discount in the merchant's store: use it only when the owner asks for a code, and say what it gives. Clients that can ask their user ask before it runs; otherwise get a clear yes first. Pass the post's "id" (list your posts) when the post exists. For a video not posted yet, leave postId out: the code is tied to the first post saved with it in its text. Without a code, a random one is made (prefix puts letters before it, e.g. the brand). Only workspace admins make codes in the app. A store that cannot make codes from Hookbird (a website with the pixel) takes existing codes only.

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

Input Schema

NameRequiredDescriptionDefault
codeNoThe code, 3 to 40 letters, digits, - or _ (default: a random one)
postIdNoThe "id" of the post the code is for (leave it out for a video not posted yet)
prefixNoLetters before a random code, e.g. the brand ("GLOW" gives GLOW7KQ2M)
storeIdNoA store id from sales_overview (default: the first connected store that can make codes)
existingNotrue: the code already exists in the store, it is only tied to the post

Output Schema

NameRequiredDescriptionDefault
codeNo
errorNo
storeNo
postIdNo
existingNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description discloses the real-world consequence of the write ('It creates a real discount in the merchant's store'), that no credits are consumed, that existing=true makes nothing, that codes are admin-only in the app, and that confirmation should be obtained before running. It also explains the attribution behavior on TikTok/Instagram, which is genuine operational context an annotation cannot carry.

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?

The core action is front-loaded in the first clause and the follow-on sentences each carry operative information (discount default, credits, confirmation, postId handling, admin constraint). It is on the long side with a slightly expansive rationale about captions lacking clickable links, but that sentence justifies the tool's existence rather than padding.

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 zero-required-parameter mutation with an output schema (so return values needn't be explained), the description covers the decision-relevant surface: creation vs. registration, credit cost, permission constraints, store capability limits, confirmation expectation, and default behaviors for code, prefix, and store selection. An agent can call this correctly and safely without further inference.

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?

With 100% schema description coverage, the schema already covers each parameter, so the baseline is 3. The description still adds meaning: the discount magnitude ('the store's default discount... 10% off unless changed'), the prefix behavior ('prefix puts letters before it, e.g. the brand'), and the non-obvious postId semantics ('the code is tied to the first post saved with it in its text') clarify defaults and side effects the schema only hints at.

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 ('Make a discount code for a post or video') and immediately splits the operation into two distinct modes: creating the store's default discount versus registering an already-existing code via 'existing true' where 'nothing is made in the store'. This distinguishes it from read-only siblings like sales_overview or sales_post without ambiguity.

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?

It gives explicit preconditions and exclusions: 'use it only when the owner asks for a code', 'Clients that can ask their user ask before it runs; otherwise get a clear yes first', and 'A store that cannot make codes from Hookbird (a website with the pixel) takes existing codes only'. It also routes the postId decision ('Pass the post's id when the post exists... For a video not posted yet, leave postId out'). What's absent is any explicit direction to a named sibling tool for adjacent needs (e.g. viewing sales vs. creating codes), so it falls just short of a 5.

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