Skip to main content
Glama

Update a loyalty card

update_card
DestructiveIdempotent

Changes a saved card's design. Only the fields passed change; the rest stay as they are. Customers' passes in Apple Wallet and Google Wallet update automatically.

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": {
      "card_id": "<card_id>"
    },
    "name": "update_card"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoInternal 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.
card_idYesCard id from list_cards.
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.
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

A3.7/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing merge semantics (unspecified fields are preserved) and the downstream propagation that Wallet passes update automatically, which an agent cannot infer from annotations alone. It does not say whether changes are reversible or require a publish step, keeping it short of 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.

Conciseness5/5

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

Three short sentences, front-loaded with the action, then the merge rule, then the propagation effect. No filler or repetition of schema content.

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

Completeness3/5

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

For a 27-parameter mutation tool this is thin: it never signals that non-design settings (referrals, stamp counts, member field) are editable, and gives no hint about what the call returns or how to verify the result. The fully documented schema offsets much of this, but the description's framing as "design only" leaves a real gap.

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 100% with detailed per-field descriptions including enums, contrast rules, and defaults, so the schema carries parameter meaning. The description adds nothing about any of the 27 parameters, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Changes a saved card's design" gives a clear verb and resource, and "saved" distinguishes it from create_card. However, it narrows the scope to "design" when the schema also exposes referral settings, initial/referee stamps, and member-field visibility, so an agent could wrongly assume it cannot edit those.

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?

The partial-update rule ("Only the fields passed change") is genuinely useful usage context, but there is no explicit when-to-use vs. create_card/update_reward guidance and no prerequisites or exclusions. Usage is implied rather than stated.

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