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.

Input 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 29, 2026

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

Changed5 schema fields changedOct 29, 2026

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

Changed9 schema fields changedOct 13, 2026

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

Changed1 schema field changedOct 7, 2026

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

Changed3 schema fields changedOct 6, 2026

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

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?

Beyond the lone destructiveHint=false annotation, the description discloses important behavior: an independent copy is created per venue, the response lists every copy, admin role is required, the benefit is live immediately unless status is hidden, and materialsOrder is reported but never stored. This adds substantial operational context an agent needs before mutating state.

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 description is long but front-loaded and dense with actionable facts. Every sentence addresses creation behavior, prerequisites, or tricky parameter semantics, though the length is near the limit for comfortable scanning.

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 creation tool with no output schema, the description explains the critical side effects, permissions, live-status warning, image workflow, localization shape, activation requirements, and visibility scoping. Some secondary parameters remain undocumented, but the gaps are minor relative to the complexity covered.

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 64% schema description coverage and many nested fields, the description adds meaningful semantics for the most complex parameters: localized text shape, activation validFrom/validUntil/frequency, visibleToStatusCards, productVariantId with materialsOrder, and content.image sourcing. It leaves sortOrder, campaignId, templateId, and orgId largely to the schema, but it covers the parameters most likely to be misunderstood.

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 uses a specific verb and resource ('Create a benefit (member perk)') and immediately distinguishes the operation from list_benefits and update_benefit by explaining that it saves the Partner Hub benefit form and creates an independent copy in each venue. An agent can identify the exact operation without opening the schema.

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 clear usage context: requires admin role on the venues, call import_image first for a new photo, and confirm details with the user before calling because the benefit is live immediately unless hidden. It does not explicitly compare against update_benefit or list_benefits, but the creation context and prerequisites are clear.

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?