Skip to main content
Glama

Cluby MCP

Create benefit

create_benefit

Create a benefit (member perk), the same as saving the Partner Hub's benefit form. An independent copy is created in each venue of venueIds (public ids from list_venues) and the response lists every copy. Requires the admin role on those venues. For a new photo, call import_image first and pass its image as content.image. Text fields are localized strings: { default: "…" } plus optional per-locale translations such as fi or en. activation needs validFrom (ISO datetime; the current time for a benefit available right away), validUntil (null for no end date) and frequency (how often one member can activate it). visibleToStatusCards (ids from list_status_cards) limits it to holders of those membership cards; omit it for every member. For a benefit created from the partner product catalogue (productVariantId), materialsOrder gives the shipping contact's name, email and phone for the free marketing materials sent to the venue. The benefit is live for members at once unless status is hidden, so confirm the details with the user before calling this.

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": {
      "venueIds": "<venueIds>",
      "content": "<content>",
      "activation": "<activation>"
    },
    "name": "create_benefit"
  }
}

Input Schema

NameRequiredDescriptionDefault
orgIdNoOrganization public id, the `id` field from list_orgs. Omit it when the API key reaches exactly one organization.
statusNoEffective hidden state: the venue's own hide toggle OR the campaign layer (see hiddenByCampaignAt) OR the partner-catalogue layer (see hiddenByProductAt)active
contentYes
venueIdsYesVenue IDs where this benefit is available
sortOrderNo
activationYes
campaignIdNo
templateIdNoTemplate ID used to create this benefit
materialsOrderNoMarketing-materials order, sent when the benefit is created from the partner product catalogue. Stored as a materials order per venue; ignored for a benefit not linked to a catalogue product.
productVariantIdNoPartner product variant this benefit was created from
visibleToStatusCardsNoMembership tier IDs. Undefined/empty = public benefit

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / materialsOrder / description
      Previous value: -"Marketing-materials order, sent when the benefit is created from the partner product catalogue. Reported, never stored."New value: +"Marketing-materials order, sent when the benefit is created from the partner product catalogue. Stored as a materials order per venue; ignored for a benefit not linked to a catalogue product."
  2. Changed1 schema field changed
    • changedInput schema / properties / activation / properties / resetTime / description
      Previous value: -"Time of day in UTC (HH:MM) when the per-member quota resets. Only the hour is kept."New value: +"Time of day on the venue's clock (HH:MM) when the per-member quota resets; 06:00 when omitted on create. Only the hour is kept."
  3. Changed5 schema fields changed
    • addedInput schema / properties / content / properties / image
      Added value: +{
      +  "anyOf": [
      +    {
      +      "properties": {
      +        "attribution": {
      +          "anyOf": [
      +            {
      +              "description": "Attribution metadata for images sourced from third-party providers (Unsplash, Pexels, Wikimedia Commons). Stored on each image variant so attribution travels with the image data wherever it's persisted. Wikimedia images under a CC BY or CC BY-SA license must be displayed with the photographer, license and source link.",
      +              "properties": {
      +                "license": {
      +                  "description": "Wikimedia only, e.g. \"CC BY-SA 4.0\"",
      +                  "type": "string"
      +                },
      +                "licenseUrl": {
      +                  "format": "uri",
      +                  "type": "string"
      +                },
      +                "photoId": {
      +                  "type": "string"
      +                },
      +                "photographerName": {
      +                  "type": "string"
      +                },
      +                "photographerProfileUrl": {
      +                  "format": "uri",
      +                  "type": "string"
      +                },
      +                "source": {
      +                  "enum": [
      +                    "unsplash",
      +                    "pexels",
      +                    "wikimedia"
      +                  ],
      +                  "type": "string"
      +                },
      +                "sourceUrl": {
      +                  "format": "uri",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "source",
      +                "photoId",
      +                "photographerName",
      +                "sourceUrl"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ]
      +        },
      +        "url": {
      +          "format": "uri",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "url"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "The photo: `{ url }` with an image upload's `originalUrl`. Omit to keep the current one, null to remove it."
      +}
    • removedInput schema / properties / content / properties / images / default
      Removed value: -[]
    • addedInput schema / properties / content / properties / images / description
      Added value: +"Refused: send content.image"
    • removedInput schema / properties / content / properties / images / items
      Removed value: -{
      -  "description": "An image source with URL, format, type, and optional dimensions for building responsive srcset",
      -  "properties": {
      -    "attribution": {
      -      "description": "Attribution metadata for images sourced from third-party providers (Unsplash, Pexels, Wikimedia Commons). Stored on each image variant so attribution travels with the image data wherever it's persisted. Wikimedia images under a CC BY or CC BY-SA license must be displayed with the photographer, license and source link.",
      -      "properties": {
      -        "license": {
      -          "description": "Wikimedia only, e.g. \"CC BY-SA 4.0\"",
      -          "type": "string"
      -        },
      -        "licenseUrl": {
      -          "format": "uri",
      -          "type": "string"
      -        },
      -        "photoId": {
      -          "type": "string"
      -        },
      -        "photographerName": {
      -          "type": "string"
      -        },
      -        "photographerProfileUrl": {
      -          "format": "uri",
      -          "type": "string"
      -        },
      -        "source": {
      -          "enum": [
      -            "unsplash",
      -            "pexels",
      -            "wikimedia"
      -          ],
      -          "type": "string"
      -        },
      -        "sourceUrl": {
      -          "format": "uri",
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "source",
      -        "photoId",
      -        "photographerName",
      -        "sourceUrl"
      -      ],
      -      "type": "object"
      -    },
      -    "format": {
      -      "enum": [
      -        "original",
      -        "raw",
      -        "jpg",
      -        "webp",
      -        "avif",
      -        "heif"
      -      ],
      -      "type": "string"
      -    },
      -    "height": {
      -      "type": "number"
      -    },
      -    "type": {
      -      "type": "string"
      -    },
      -    "url": {
      -      "type": "string"
      -    },
      -    "width": {
      -      "type": "number"
      -    }
      -  },
      -  "required": [
      -    "url",
      -    "format",
      -    "type"
      -  ],
      -  "type": "object"
      -}
    • removedInput schema / properties / content / properties / images / type
      Removed value: -"array"
  4. Changed9 schema fields changed
    • addedInput schema / properties / content / properties / size / anyOf
      Added value: +[
      +  {
      +    "description": "Optional numeric size of the benefit (e.g. 0.33, 500). Stored as DECIMAL(10,3) — at most 3 decimal places.",
      +    "exclusiveMinimum": 0,
      +    "maximum": 9999999.999,
      +    "type": "number"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / content / properties / size / description
      Previous value: -"Optional numeric size of the benefit (e.g. 0.33, 500). Stored as DECIMAL(10,3) — at most 3 decimal places."New value: +"null clears the size"
    • removedInput schema / properties / content / properties / size / exclusiveMinimum
      Removed value: -0
    • removedInput schema / properties / content / properties / size / maximum
      Removed value: -9999999.999
    • removedInput schema / properties / content / properties / size / type
      Removed value: -"number"
    • addedInput schema / properties / content / properties / sizeUnits / anyOf
      Added value: +[
      +  {
      +    "description": "Optional unit of measurement for `size`",
      +    "enum": [
      +      "MILLILITER",
      +      "CENTILITER",
      +      "LITER",
      +      "PINT"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / content / properties / sizeUnits / description
      Previous value: -"Optional unit of measurement for `size`"New value: +"null clears the size unit"
    • removedInput schema / properties / content / properties / sizeUnits / enum
      Removed value: -[
      -  "MILLILITER",
      -  "CENTILITER",
      -  "LITER",
      -  "PINT"
      -]
    • removedInput schema / properties / content / properties / sizeUnits / type
      Removed value: -"string"
  5. Changed1 schema field changed
    • changedInput schema / properties / activation / properties / resetTime / description
      Previous value: -"Time when benefit resets in venue's local timezone (HH:MM format)"New value: +"Time of day in UTC (HH:MM) when the per-member quota resets. Only the hour is kept."
  6. Changed3 schema fields changed
    • addedInput schema / properties / materialsOrder / properties / declined / const
      Added value: +false
    • changedInput schema / properties / materialsOrder / properties / declined / description
      Previous value: -"The merchant opted out of the free marketing materials"New value: +"Deprecated: the materials can no longer be declined"
    • changedInput schema / properties / materialsOrder / required
      Previous value: -[
      -  "declined"
      -]New value: +[
      +  "contactName",
      +  "contactEmail",
      +  "contactPhone"
      +]
  7. Changed1 schema field changed
    • removedInput schema / properties / content / properties / icon
      Removed value: -{
      -  "default": {
      -    "name": "star",
      -    "variant": "solid"
      -  },
      -  "properties": {
      -    "name": {
      -      "default": "star",
      -      "type": "string"
      -    },
      -    "variant": {
      -      "default": "solid",
      -      "enum": [
      -        "solid",
      -        "regular",
      -        "light"
      -      ],
      -      "type": "string"
      -    }
      -  },
      -  "type": "object"
      -}
  8. Changed6 schema fields changed
    • changedInput schema / properties / content / properties / images / items / properties / attribution / description
      Previous value: -"Attribution metadata for images sourced from third-party providers (e.g. Unsplash). Stored on each image variant so attribution travels with the image data wherever it's persisted."New value: +"Attribution metadata for images sourced from third-party providers (Unsplash, Pexels, Wikimedia Commons). Stored on each image variant so attribution travels with the image data wherever it's persisted. Wikimedia images under a CC BY or CC BY-SA license must be displayed with the photographer, license and source link."
    • addedInput schema / properties / content / properties / images / items / properties / attribution / properties / license
      Added value: +{
      +  "description": "Wikimedia only, e.g. \"CC BY-SA 4.0\"",
      +  "type": "string"
      +}
    • addedInput schema / properties / content / properties / images / items / properties / attribution / properties / licenseUrl
      Added value: +{
      +  "format": "uri",
      +  "type": "string"
      +}
    • removedInput schema / properties / content / properties / images / items / properties / attribution / properties / source / const
      Removed value: -"unsplash"
    • addedInput schema / properties / content / properties / images / items / properties / attribution / properties / source / enum
      Added value: +[
      +  "unsplash",
      +  "pexels",
      +  "wikimedia"
      +]
    • changedInput schema / properties / content / properties / images / items / properties / attribution / required
      Previous value: -[
      -  "source",
      -  "photoId",
      -  "photographerName",
      -  "photographerProfileUrl",
      -  "sourceUrl"
      -]New value: +[
      +  "source",
      +  "photoId",
      +  "photographerName",
      +  "sourceUrl"
      +]
  9. Changed10 schema fields changed
    • addedInput schema / properties / content / properties / description / anyOf
      Added value: +[
      +  {
      +    "description": "A localized string with a required default value and optional locale-specific translations",
      +    "properties": {
      +      "cs": {
      +        "type": "string"
      +      },
      +      "da": {
      +        "type": "string"
      +      },
      +      "de": {
      +        "type": "string"
      +      },
      +      "default": {
      +        "type": "string"
      +      },
      +      "en": {
      +        "type": "string"
      +      },
      +      "es": {
      +        "type": "string"
      +      },
      +      "et": {
      +        "type": "string"
      +      },
      +      "fi": {
      +        "type": "string"
      +      },
      +      "fr": {
      +        "type": "string"
      +      },
      +      "it": {
      +        "type": "string"
      +      },
      +      "ka": {
      +        "type": "string"
      +      },
      +      "lt": {
      +        "type": "string"
      +      },
      +      "lv": {
      +        "type": "string"
      +      },
      +      "nb": {
      +        "type": "string"
      +      },
      +      "nl": {
      +        "type": "string"
      +      },
      +      "pl": {
      +        "type": "string"
      +      },
      +      "pt": {
      +        "type": "string"
      +      },
      +      "ru": {
      +        "type": "string"
      +      },
      +      "sk": {
      +        "type": "string"
      +      },
      +      "sv": {
      +        "type": "string"
      +      },
      +      "uk": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "default"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / content / properties / description / description
      Previous value: -"A localized string with a required default value and optional locale-specific translations"New value: +"null clears the description"
    • removedInput schema / properties / content / properties / description / properties
      Removed value: -{
      -  "cs": {
      -    "type": "string"
      -  },
      -  "da": {
      -    "type": "string"
      -  },
      -  "de": {
      -    "type": "string"
      -  },
      -  "default": {
      -    "type": "string"
      -  },
      -  "en": {
      -    "type": "string"
      -  },
      -  "es": {
      -    "type": "string"
      -  },
      -  "et": {
      -    "type": "string"
      -  },
      -  "fi": {
      -    "type": "string"
      -  },
      -  "fr": {
      -    "type": "string"
      -  },
      -  "it": {
      -    "type": "string"
      -  },
      -  "ka": {
      -    "type": "string"
      -  },
      -  "lt": {
      -    "type": "string"
      -  },
      -  "lv": {
      -    "type": "string"
      -  },
      -  "nb": {
      -    "type": "string"
      -  },
      -  "nl": {
      -    "type": "string"
      -  },
      -  "pl": {
      -    "type": "string"
      -  },
      -  "pt": {
      -    "type": "string"
      -  },
      -  "ru": {
      -    "type": "string"
      -  },
      -  "sk": {
      -    "type": "string"
      -  },
      -  "sv": {
      -    "type": "string"
      -  },
      -  "uk": {
      -    "type": "string"
      -  }
      -}
    • removedInput schema / properties / content / properties / description / required
      Removed value: -[
      -  "default"
      -]
    • removedInput schema / properties / content / properties / description / type
      Removed value: -"object"
    • addedInput schema / properties / content / properties / offer
      Added value: +{
      +  "anyOf": [
      +    {
      +      "properties": {
      +        "type": {
      +          "enum": [
      +            "price",
      +            "percent_off"
      +          ],
      +          "type": "string"
      +        },
      +        "value": {
      +          "description": "For `price`: the amount in the minor unit of the organization's currency (500 = 5.00 EUR; 0 = free). For `percent_off`: basis points (2000 = 20 % off), at most 10000.",
      +          "maximum": 2147483647,
      +          "minimum": 0,
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "type",
      +        "value"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "The benefit's value: a price or a percentage off. null or absent for a benefit with no value shown."
      +}
    • changedInput schema / properties / content / properties / valueDisplay / description
      Previous value: -"A localized string with a required default value and optional locale-specific translations"New value: +"Read-only and refused: send content.offer"
    • removedInput schema / properties / content / properties / valueDisplay / properties
      Removed value: -{
      -  "cs": {
      -    "type": "string"
      -  },
      -  "da": {
      -    "type": "string"
      -  },
      -  "de": {
      -    "type": "string"
      -  },
      -  "default": {
      -    "type": "string"
      -  },
      -  "en": {
      -    "type": "string"
      -  },
      -  "es": {
      -    "type": "string"
      -  },
      -  "et": {
      -    "type": "string"
      -  },
      -  "fi": {
      -    "type": "string"
      -  },
      -  "fr": {
      -    "type": "string"
      -  },
      -  "it": {
      -    "type": "string"
      -  },
      -  "ka": {
      -    "type": "string"
      -  },
      -  "lt": {
      -    "type": "string"
      -  },
      -  "lv": {
      -    "type": "string"
      -  },
      -  "nb": {
      -    "type": "string"
      -  },
      -  "nl": {
      -    "type": "string"
      -  },
      -  "pl": {
      -    "type": "string"
      -  },
      -  "pt": {
      -    "type": "string"
      -  },
      -  "ru": {
      -    "type": "string"
      -  },
      -  "sk": {
      -    "type": "string"
      -  },
      -  "sv": {
      -    "type": "string"
      -  },
      -  "uk": {
      -    "type": "string"
      -  }
      -}
    • removedInput schema / properties / content / properties / valueDisplay / required
      Removed value: -[
      -  "default"
      -]
    • removedInput schema / properties / content / properties / valueDisplay / type
      Removed value: -"object"
  10. Added

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only declare destructiveHint=false, so the description carries the real burden and does: admin-role requirement on the venues, immediate live state, fan-out copy creation, response shape, plus refusals (`images` refused, use `content.image`; `valueDisplay` read-only) and no-op semantics (validFrom/validUntil ignored when schedules exist, materialsOrder ignored without a catalogue product). This is behavior an agent cannot infer from structured fields.

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 action and the multi-venue fan-out, then prerequisites, then field semantics, then a safety warning at the end. Dense but nearly every clause carries information; the activation/date sentence is somewhat long but earns its place.

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 an 11-parameter creation tool with nested objects and no output schema, the description covers the risky and non-obvious parts, including the return ('the response lists every copy') and the confirmation requirement. Remaining gaps are low-risk fields like sortOrder and templateId.

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 schema coverage at 64%, the description compensates well: it explains localized-string shape `{ default, fi, en }`, what `activation` requires (validFrom/validUntil/frequency), that omitting `visibleToStatusCards` means every member, that `venueIds` are public ids from list_venues, and what `materialsOrder` is for. Minor params (sortOrder, orgId, campaignId, templateId) are left to the 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 ('Create a benefit (member perk)') and immediately pins down the non-obvious semantics: an independent copy is created in each venue of `venueIds` and the response lists every copy. The Partner Hub form analogy and the mention of related tools (list_venues, list_status_cards) let an agent place it precisely against create/update siblings.

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?

Gives explicit prerequisites and sequencing: call import_image first for a new photo, confirm details with the user before calling because the benefit goes live at once unless `status` is `hidden`. It does not explicitly route to update_benefit for later edits, which is the only gap.

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