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 images as content.images. 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 says whether the venue wants the free marketing materials; unless declined is true it needs the shipping contact's name, email and phone. The benefit is live for members at once unless status is hidden, so confirm the details with the user before calling this.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`orgId`	No	Organization public id, the `id` field from list_orgs. Omit it when the API key reaches exactly one organization.
`status`	No	Effective hidden state: the venue's own hide toggle OR the campaign layer (see hiddenByCampaignAt) OR the partner-catalogue layer (see hiddenByProductAt)	active
`content`	Yes
`venueIds`	Yes	Venue IDs where this benefit is available
`sortOrder`	No
`activation`	Yes
`campaignId`	No
`templateId`	No	Template ID used to create this benefit
`materialsOrder`	No	Marketing-materials order, sent when the benefit is created from the partner product catalogue. Reported, never stored.
`productVariantId`	No	Partner product variant this benefit was created from
`visibleToStatusCards`	No	Membership tier IDs. Undefined/empty = public benefit

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 2, 2026

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

Changed6 schema fields changedSep 28, 2026

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"
+]

Changed10 schema fields changedSep 28, 2026

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"
```

AddedSep 25, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With only destructiveHint=false in annotations, the description carries real weight and delivers: admin-role requirement, one independent copy per venue, immediate member visibility unless `status` is `hidden`, `visibleToStatusCards` scoping, and that `materialsOrder` is 'reported, never stored'. These are substantive traits beyond the annotations.

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?

Dense but front-loaded: creation scope and permission come first, then image, localization, activation, and materials-order guidance in a logical order. It is long, but most sentences carry non-obvious rules rather than padding.

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 nested create tool with no output schema, the description covers the high-risk semantics (permission, immediacy, per-venue duplication, response shape, localization, activation, materialsOrder). It omits details of `schedules` and `content.offer`, but those are documented in the schema, so the gap is minor.

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?

At 64% schema coverage the description adds genuine meaning: the localized-string shape `{ default: "…", fi: … }`, the required `activation` trio with `validFrom`/`validUntil`/`frequency` semantics, sourcing `venueIds` from `list_venues` and `visibleToStatusCards` from `list_status_cards`, and the `declined`/contact requirement for `materialsOrder`. It leaves `schedules`, `offer`, and `sortOrder` largely 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 clarifies the fan-out scope: an independent copy in each venue of `venueIds`, with the response listing every copy. This distinguishes it clearly from `update_benefit` and `list_benefits`.

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 concrete pre-conditions and routing: requires the admin role, call `import_image` first for a new photo and pass its `images`, and 'confirm the details with the user before calling this' since the benefit goes live at once. It does not explicitly contrast with `update_benefit`, so it falls short of a full when/when-not map.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Cluby MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?