Skip to main content
Glama

Create a loyalty card

create_card

Saves a loyalty card design and its rewards to a Leal store, ready for customers to add to Apple Wallet or Google Wallet. Takes the same design fields as preview_card_designs. Logos and strip photos are fetched from their URLs; if the store has no logo yet, the card's logo becomes the store logo. Needs a Leal account: the person is asked to sign in or create one.

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": {
      "name": "<name>",
      "rewards": "<rewards>"
    },
    "name": "create_card"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesInternal name for the card, e.g. "Coffee card". Shown in Leal, not on the pass.
intentNoOptional. One short sentence on what the person asked you to do, e.g. "Set up a stamp card for Ground Up Café". Leal shows it in the person's activity log under Settings → AI agents, so they can see what was done for them. Leave out customer details.
rewardsYesRewards customers can redeem, e.g. [{name: "Free coffee", stamps_required: 10}]. The free plan allows one reward per card.
logo_urlNoPublic https URL of the wide logo shown top-left of the Apple pass (PNG, JPEG, WebP, GIF or SVG; transparent PNG works best). Ideally a version that reads on card_color.
qr_styleNoWhat the pass QR holds. link (default for new cards): a phone camera opens the store's sign-up page with this customer as referrer, and the store scanner still reads it. code: the bare card code only. Passes showing the old QR keep scanning.
store_idNoStore id from list_stores. Optional when the login has one store.
card_colorNoPass background colour, hex (#RRGGBB). Fills the whole screen in Google Wallet, so avoid neon, fully saturated colours such as #00ff00.
stamp_iconNoIcon shown in each collected stamp.
strip_typeNoBackground of the stamp strip: a flat colour, one of Leal's preset photos, or an image from strip_image_url.
text_colorNoColour of all text on the Apple pass, hex. Must read clearly on card_color (4.5:1 contrast or better). Google Wallet ignores it and picks black or white itself.
header_textNoText at the top of the pass. Defaults to the store name. Wallet apps truncate long headers, so keep it short.
stamp_colorNoColour of the icon inside a collected stamp, hex. Must read clearly on stamp_background_color.
strip_colorNoStrip colour, hex. Also shows behind preset and image strips when strip_opacity is below 100.
strip_presetNoPreset strip photo, used when strip_type is preset.
strip_opacityNoOpacity of the strip colour or image over the card colour. 100 shows it exactly; 60–85 tints a photo with the card colour so stamps stand out.
initial_stampsNoStamps a new customer starts with (a head start). Must be less than stamps_required.
referee_stampsNoStamps the invited friend gets on their first stamped visit. Less than stamps_required. Default 1.
referrer_stampsNoStamps the inviting customer gets when their friend's first visit is stamped. Less than stamps_required. Default 1.
square_logo_urlNoPublic https URL of a square logo or icon, used as the round logo on Google Wallet.
stamps_requiredNoStamps needed to fill the card. 6, 8 or 10 are common.
strip_image_urlNoPublic https URL of a wide photo for the strip (strip_type image), e.g. a hero image from the brand's website. Cropped to 375×144 on Apple Wallet; Google Wallet shows the middle of it in its nearly square hero unless google_hero_image_url is given.
auxiliary_fieldsNoUp to two extra front-of-pass fields, e.g. {label: "Perk", value: "10% off pastries"}.
google_logo_styleNoHow the logo sits on Google Wallet. round (default): square_logo_url in a circle with the store name. wide: logo_url in place of the circle and store name, best for wordmarks.
referrals_enabledNoLet customers invite friends from the back of their pass. Both get stamps once the store first stamps the friend's card on a visit, never just for signing up. Default false.
show_member_fieldNoShow the customer's name on the front of the pass. Default true.
google_hero_image_urlNoPublic https URL of a nearly square photo (1032×812, about 5:4) for Google Wallet's hero image, with no text in it. The stamps are drawn on top. Optional: without it the hero uses the strip background.
stamp_background_colorNoFill colour of a collected stamp circle, hex. Empty stamp slots use a translucent version of it, so it should stand out from the strip.
show_stamps_to_reward_fieldNoShow how many stamps until the next reward. Default true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / card_color / description
      Previous value: -"Pass background colour, hex (#RRGGBB)."New value: +"Pass background colour, hex (#RRGGBB). Fills the whole screen in Google Wallet, so avoid neon, fully saturated colours such as #00ff00."
    • addedInput schema / properties / google_hero_image_url
      Added value: +{
      +  "description": "Public https URL of a nearly square photo (1032×812, about 5:4) for Google Wallet's hero image, with no text in it. The stamps are drawn on top. Optional: without it the hero uses the strip background.",
      +  "type": "string"
      +}
    • addedInput schema / properties / google_logo_style
      Added value: +{
      +  "description": "How the logo sits on Google Wallet. round (default): square_logo_url in a circle with the store name. wide: logo_url in place of the circle and store name, best for wordmarks.",
      +  "enum": [
      +    "round",
      +    "wide"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / strip_image_url / description
      Previous value: -"Public https URL of a wide photo for the strip (strip_type image), e.g. a hero image from the brand's website. Cropped to 375×144."New value: +"Public https URL of a wide photo for the strip (strip_type image), e.g. a hero image from the brand's website. Cropped to 375×144 on Apple Wallet; Google Wallet shows the middle of it in its nearly square hero unless google_hero_image_url is given."
    • changedInput schema / properties / text_color / description
      Previous value: -"Colour of all text on the pass, hex. Must read clearly on card_color (4.5:1 contrast or better)."New value: +"Colour of all text on the Apple pass, hex. Must read clearly on card_color (4.5:1 contrast or better). Google Wallet ignores it and picks black or white itself."
  2. Changed1 schema field changed
    • addedInput schema / properties / intent
      Added value: +{
      +  "description": "Optional. One short sentence on what the person asked you to do, e.g. \"Set up a stamp card for Ground Up Café\". Leal shows it in the person's activity log under Settings → AI agents, so they can see what was done for them. Leave out customer details.",
      +  "type": "string"
      +}
  3. Changed4 schema fields changed
    • addedInput schema / properties / qr_style
      Added value: +{
      +  "description": "What the pass QR holds. link (default for new cards): a phone camera opens the store's sign-up page with this customer as referrer, and the store scanner still reads it. code: the bare card code only. Passes showing the old QR keep scanning.",
      +  "enum": [
      +    "link",
      +    "code"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / referee_stamps
      Added value: +{
      +  "description": "Stamps the invited friend gets on their first stamped visit. Less than stamps_required. Default 1.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / referrals_enabled
      Added value: +{
      +  "description": "Let customers invite friends from the back of their pass. Both get stamps once the store first stamps the friend's card on a visit, never just for signing up. Default false.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / referrer_stamps
      Added value: +{
      +  "description": "Stamps the inviting customer gets when their friend's first visit is stamped. Less than stamps_required. Default 1.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
  4. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Goes beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false) by disclosing real side effects: logos and strip photos are fetched from their URLs at save time, and if the store has no logo the card's logo becomes the store logo. It also states the auth requirement (a Leal account, with sign-in or account creation). It does not warn that repeat calls create additional cards, which matters given idempotentHint=false.

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?

Four short sentences, each with a distinct job: what it does, the preview relationship, asset side effects, and the auth prerequisite. The core action is front-loaded and there is no filler.

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?

The description opens with a specific verb and resource, explains the wallet outcome, and links itself to preview_card_designs, so the agent knows it creates cards from design fields. Its remaining gaps, the return value and per-parameter syntax, are covered elsewhere or are minor.

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 coverage is 100%, so the baseline is 3 and the schema already documents all 28 fields, including enums and defaults. The description adds only that the design fields mirror preview_card_designs and that image parameters are URL-fetched, which is useful but modest against a fully documented 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 ("Saves a loyalty card design and its rewards") plus the outcome ("ready for customers to add to Apple Wallet or Google Wallet") and scopes it to a Leal store. It also positions itself relative to preview_card_designs, so an agent can tell creation apart from preview.

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?

"Takes the same design fields as preview_card_designs" implies that previewing is the sibling activity, but the description never explicitly says to preview first or when not to call this tool. Nothing distinguishes it from update_card, which is the natural alternative for an existing card.

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