@open-loyalty/mcp-server 1.3.7 → 1.5.3

package/dist/tools/achievement/schemas.js

@@ -40,8 +40,9 @@ const AchievementRuleInputSchema = z.object({
     completeRule: z.object({
         periodGoal: z.union([z.number(), z.string()]).describe("Goal value to reach (e.g., 5 for 5 purchases, 100 for 100 points)."),
         period: z.object({
-            type: AchievementPeriodTypeEnum.describe("Period type. For ONE-TIME achievements: use 'day'. For STREAKS: use 'calendarDays'. " +
-                "Options: 'day' (all-time), 'last_day' (rolling), 'calendarDays/Weeks/Months/Years' (calendar-based)."),
+            type: AchievementPeriodTypeEnum.describe("Period type. BUSINESS DECISION: 'day' with consecutive=1 = all-time tracking (for one-time badges). " +
+                "'calendarDays' with consecutive=N = streak tracking (for N consecutive days). " +
+                "BUSINESS IMPACT: Using streak settings for a one-time badge means members must act on consecutive days to earn it -- nobody will."),
             value: z.number().optional().describe("Period value (e.g., 7 for 'last 7 days' when type='last_day'). Usually omit for simple achievements."),
             consecutive: z.number().min(1).describe("⭐ CONSECUTIVE PERIODS: For ONE-TIME achievements (first purchase): use consecutive=1. " +
                 "For STREAKS (7 consecutive days): use consecutive=7 with type='calendarDays'. " +
@@ -54,26 +55,28 @@ const AchievementRuleInputSchema = z.object({
     aggregation: z.object({
         type: AchievementAggregationTypeEnum.describe("How to aggregate: 'quantity' (count events). NOTE: Only 'quantity' is supported by the API."),
     }).describe("Value aggregation. Use type='quantity' for event counting. NOTE: 'sum', 'average', 'min', 'max' are NOT supported by the API."),
-    conditions: z.array(z.record(z.unknown())).optional().describe("Conditions that must be met."),
+    conditions: z.array(z.record(z.unknown())).optional().describe("Conditions that must be met for rule progress. Same structure as campaign conditions: " +
+        "{ operator: 'is_greater_or_equal', attribute: 'transaction.grossValue', data: 100 }. " +
+        "For labels: { operator: 'has_at_least_one_label', attribute: 'transaction.labels', data: [{key: 'category', value: 'electronics'}] }."),
     limit: z.object({
         value: z.number().optional().describe("Max events per interval (e.g., 1 for once-per-day limit)."),
         interval: z.object({
-            type: z.string().describe("Interval type: 'calendarDays', 'calendarWeeks', etc."),
-            value: z.number().optional().describe("Interval value."),
+            type: z.string().describe("Interval type. Valid values: 'calendarDays' (NOT 'days'), 'calendarWeeks' (NOT 'weeks'), 'calendarMonths', 'calendarYears'."),
+            value: z.number().optional().describe("Interval length (e.g., 1 for every 1 calendar day)."),
         }).optional().describe("Time interval for the limit."),
-    }).optional().describe("⚠️ RULE LIMIT - ONLY for STREAKS. For ONE-TIME achievements, DO NOT set rule limit. " +
-        "For STREAKS: use { value: 1, interval: { type: 'calendarDays', value: 1 } } to count max 1 event per day."),
+    }).optional().describe("Only for streak achievements -- DO NOT set for one-time badges. " +
+        "BUSINESS IMPACT: Controls how events are counted per period. For streaks: { value: 1, interval: { type: 'calendarDays', value: 1 } } ensures max 1 event per day counts toward the streak."),
     uniqueReferee: z.boolean().optional().describe("Whether referee must be unique (for referral achievements)."),
 });
 export const AchievementListInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 10)."),
     active: z.boolean().optional().describe("Filter by active status."),
     name: z.string().optional().describe("Filter by achievement name."),
 };
 export const AchievementCreateInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     translations: z.record(z.string(), z.object({
         name: z.string(),
         description: z.string().optional(),
@@ -87,47 +90,48 @@ export const AchievementCreateInputSchema = {
     limit: z.object({
         value: z.number().optional().describe("Maximum completions (e.g., 1 for one-time badges)."),
         interval: z.object({
-            type: z.string(),
-            value: z.number().optional(),
-        }).optional(),
-    }).optional().describe("⭐ ACHIEVEMENT LIMIT: How many times a member can earn this achievement. " +
-        "For ONE-TIME badges (like 'First Purchase'): set limit.value=1 with NO interval. " +
-        "For repeatable achievements: omit limit or set higher value. " +
-        "IMPORTANT: Without limit.value=1, members can earn the badge unlimited times!"),
+            type: z.string().describe("Interval type. Valid values: 'calendarDays', 'calendarWeeks', 'calendarMonths', 'calendarYears'."),
+            value: z.number().optional().describe("Interval length (e.g., 1 for every 1 calendar period)."),
+        }).optional().describe("Interval for repeatable achievements (omit for one-time badges)."),
+    }).optional().describe("How many times a member can earn this achievement. " +
+        "BUSINESS DECISION: For one-time badges ('First Purchase'): set value=1 with NO interval. For repeatable challenges: omit or set higher. " +
+        "BUSINESS IMPACT: Without limit.value=1, members earn the badge unlimited times -- this defeats milestone purpose and can trigger unlimited achievement-based rewards."),
     rules: z.array(AchievementRuleInputSchema).describe("Achievement rules defining completion criteria."),
     badgeTypeId: z.string().optional().describe("Badge type ID to award upon completion. " +
         "NOTE: This field may cause 'extra fields' validation errors in some API versions. " +
         "If creation fails, try without badgeTypeId - the system will assign a default badge."),
 };
 export const AchievementGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     achievementId: z.string().describe("The achievement ID (UUID) to retrieve."),
 };
 export const AchievementUpdateInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     achievementId: z.string().describe("The achievement ID (UUID) to update."),
     translations: z.record(z.string(), z.object({
         name: z.string(),
         description: z.string().optional(),
-    })).describe("Achievement name and description."),
+    })).describe("Achievement name and description. At least 'en' key required."),
     active: z.boolean().optional().describe("Whether achievement is active."),
     activity: z.object({
-        startsAt: z.string().optional(),
-        endsAt: z.string().optional(),
-        operator: z.string().optional(),
+        startsAt: z.string().optional().describe("ISO datetime when achievement becomes active (e.g., '2026-01-01T00:00:00+00:00')."),
+        endsAt: z.string().optional().describe("ISO datetime when achievement ends."),
+        operator: z.string().optional().describe("Activity condition operator: 'between' (both dates) or 'from' (start only) or 'to' (end only)."),
     }).optional().describe("Time period configuration."),
     limit: z.object({
-        value: z.number().optional(),
+        value: z.number().optional().describe("Maximum completions (e.g., 1 for one-time badges)."),
         interval: z.object({
-            type: z.string(),
-            value: z.number().optional(),
-        }).optional(),
-    }).optional().describe("Limit configuration."),
-    rules: z.array(AchievementRuleInputSchema).describe("Achievement rules."),
-    badgeTypeId: z.string().optional().describe("Badge type ID to award."),
+            type: z.string().describe("Interval type. Valid values: 'calendarDays', 'calendarWeeks', 'calendarMonths', 'calendarYears'."),
+            value: z.number().optional().describe("Interval length (e.g., 1 for every 1 calendar period)."),
+        }).optional().describe("Interval for repeatable achievements (omit for one-time badges)."),
+    }).optional().describe("Achievement limit. For ONE-TIME badges: { value: 1 } with NO interval. " +
+        "For repeatable: omit or set higher value."),
+    rules: z.array(AchievementRuleInputSchema).describe("Achievement rules. Use achievement_get first to retrieve current rules and include achievementRuleId for existing rules."),
+    badgeTypeId: z.string().optional().describe("Badge type ID to award. Use ol_badge_list() to find valid IDs. " +
+        "May cause 'extra fields' errors in some API versions - try without if creation fails."),
 };
 export const AchievementPatchInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     achievementId: z.string().describe("The achievement ID (UUID) to patch."),
     active: z.boolean().optional().describe("Whether achievement is active."),
     translations: z.record(z.string(), z.object({
@@ -136,12 +140,12 @@ export const AchievementPatchInputSchema = {
     })).optional().describe("Partial translation updates."),
 };
 export const AchievementGetMemberProgressInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     memberId: z.string().describe("The member ID (UUID)."),
     achievementId: z.string().describe("The achievement ID (UUID)."),
 };
 export const AchievementListMemberAchievementsInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     memberId: z.string().describe("The member ID (UUID)."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),

package/dist/tools/analytics.js

@@ -4,29 +4,29 @@ import { formatApiError } from "../utils/errors.js";
 import { getStoreCode } from "../config.js";
 // Input Schemas
 export const AnalyticsTiersInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
 };
 export const AnalyticsMembersInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     withTransaction: z.boolean().optional().describe("Filter: true for members with transactions, false for members without, omit for all."),
 };
 export const AnalyticsPointsInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
 };
 export const AnalyticsTransactionsInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
 };
 export const AnalyticsReferralsInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
 };
 export const AnalyticsCampaignsInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),
     executedAt: z.string().optional().describe("Filter by execution date (ISO format)."),
 };
 export const AnalyticsDashboardInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     dataType: z.enum([
         "registeredMembers", "activeMembers", "revenue", "avgSpending",
         "transactions", "avgTransactionValue", "avgNumberOfTransactions"
@@ -36,7 +36,7 @@ export const AnalyticsDashboardInputSchema = {
     intervalEndDate: z.string().optional().describe("End date (YYYY-MM-DD format)."),
 };
 export const AnalyticsUnitsInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     walletTypeCode: z.string().describe("Wallet type code (e.g., 'default' or 'points')."),
     dataType: z.enum([
         "unitsIssued", "unitsSpent", "unitsExpired", "unitsPending", "unitsActive"
@@ -46,7 +46,7 @@ export const AnalyticsUnitsInputSchema = {
     intervalEndDate: z.string().optional().describe("End date (YYYY-MM-DD format)."),
 };
 export const AnalyticsCampaignDetailInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     campaignId: z.string().describe("The campaign ID to get analytics for."),
 };
 // Handler functions

package/dist/tools/badge.js

@@ -4,18 +4,18 @@ import { formatApiError } from "../utils/errors.js";
 import { getStoreCode } from "../config.js";
 // Input Schemas
 export const BadgeListInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 10)."),
     name: z.string().optional().describe("Filter by badge name."),
     badgeTypeId: z.string().optional().describe("Filter by specific badge type ID."),
 };
 export const BadgeGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     badgeTypeId: z.string().describe("The badge type ID (UUID) to retrieve."),
 };
 export const BadgeUpdateInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     badgeTypeId: z.string().describe("The badge type ID (UUID) to update."),
     name: z.string().describe("Badge name (REQUIRED). API requires name as a direct field."),
     translations: z.record(z.string(), z.object({
@@ -26,7 +26,7 @@ export const BadgeUpdateInputSchema = {
     active: z.boolean().optional().describe("Whether badge type is active."),
 };
 export const BadgeGetMemberBadgesInputSchema = {
-    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     memberId: z.string().describe("The member ID (UUID)."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 10)."),

package/dist/tools/campaign/handlers.js

@@ -1,5 +1,5 @@
 import { apiGet, apiPost, apiPut, apiPatch, apiDelete } from "../../client/http.js";
-import { formatApiError } from "../../utils/errors.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
 import { getStoreCode } from "../../config.js";
 // Core CRUD handlers
 export async function campaignList(input) {
@@ -95,6 +95,40 @@ export async function campaignCreate(input) {
         return { campaignId: response.campaignId };
     }
     catch (error) {
+        const axiosError = error;
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [
+            error instanceof Error ? error.message : "",
+            axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => `${e.path || ""}: ${e.message}`)
+        ].join(" ").toLowerCase();
+        if (allMessages.includes("trigger") && allMessages.includes("choice")) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_TRIGGER",
+                message: "Invalid campaign trigger type",
+                hint: "Valid trigger values: 'transaction', 'custom_event', 'geolocation', 'time', 'achievement'. For custom_event, also set event='your_event_type'. For achievement, set achievementId='uuid'.",
+                relatedTool: "ol_campaign_create",
+            });
+        }
+        if (allMessages.includes("operator") || (allMessages.includes("condition") && allMessages.includes("choice"))) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_CONDITION",
+                message: "Invalid rule condition in campaign",
+                hint: "Use full operator names: 'is_greater_or_equal' (NOT 'gte'), 'is_less_or_equal' (NOT 'lte'). " +
+                    "Use full attribute paths: 'transaction.grossValue' (NOT 'grossValue'). " +
+                    "Example: { operator: 'is_greater_or_equal', attribute: 'transaction.grossValue', data: 100 }.",
+                relatedTool: "ol_campaign_create",
+            });
+        }
+        if (input.trigger === "custom_event" && !input.event && allMessages.includes("event")) {
+            throw new OpenLoyaltyError({
+                code: "MISSING_EVENT",
+                message: "Missing event field for custom_event trigger",
+                hint: "For trigger='custom_event', you MUST also set event='your_event_code'. " +
+                    "Use ol_custom_event_schema_list() to find valid event codes.",
+                relatedTool: "ol_campaign_create",
+            });
+        }
         throw formatApiError(error, "ol_campaign_create");
     }
 }

package/dist/tools/campaign/index.d.ts

@@ -150,11 +150,11 @@ export declare const campaignToolDefinitions: readonly [{
             tiers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
             segments: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
         }, "strip", import("zod").ZodTypeAny, {
-            target: "all" | "segment" | "tier";
+            target: "all" | "tier" | "segment";
             tiers?: string[] | undefined;
             segments?: string[] | undefined;
         }, {
-            target: "all" | "segment" | "tier";
+            target: "all" | "tier" | "segment";
             tiers?: string[] | undefined;
             segments?: string[] | undefined;
         }>>;
@@ -163,11 +163,11 @@ export declare const campaignToolDefinitions: readonly [{
             tiers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
             segments: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
         }, "strip", import("zod").ZodTypeAny, {
-            target: "segment" | "tier";
+            target: "tier" | "segment";
             tiers?: string[] | undefined;
             segments?: string[] | undefined;
         }, {
-            target: "segment" | "tier";
+            target: "tier" | "segment";
             tiers?: string[] | undefined;
             segments?: string[] | undefined;
         }>>;
@@ -377,17 +377,17 @@ export declare const campaignToolDefinitions: readonly [{
             description: import("zod").ZodOptional<import("zod").ZodString>;
             target: import("zod").ZodOptional<import("zod").ZodEnum<["self", "referrer"]>>;
             effects: import("zod").ZodArray<import("zod").ZodObject<{
-                effect: import("zod").ZodString;
+                effect: import("zod").ZodEnum<["give_points", "give_reward", "deduct_unit", "assign_member_custom_attribute", "remove_member_custom_attribute"]>;
                 pointsRule: import("zod").ZodOptional<import("zod").ZodString>;
                 walletCode: import("zod").ZodOptional<import("zod").ZodString>;
                 rewardId: import("zod").ZodOptional<import("zod").ZodString>;
             }, "strip", import("zod").ZodTypeAny, {
-                effect: string;
+                effect: "give_points" | "give_reward" | "deduct_unit" | "assign_member_custom_attribute" | "remove_member_custom_attribute";
                 walletCode?: string | undefined;
                 rewardId?: string | undefined;
                 pointsRule?: string | undefined;
             }, {
-                effect: string;
+                effect: "give_points" | "give_reward" | "deduct_unit" | "assign_member_custom_attribute" | "remove_member_custom_attribute";
                 walletCode?: string | undefined;
                 rewardId?: string | undefined;
                 pointsRule?: string | undefined;
@@ -395,20 +395,20 @@ export declare const campaignToolDefinitions: readonly [{
             conditions: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
                 operator: import("zod").ZodString;
                 attribute: import("zod").ZodString;
-                data: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+                data: import("zod").ZodUnknown;
             }, "strip", import("zod").ZodTypeAny, {
                 attribute: string;
                 operator: string;
-                data?: Record<string, unknown> | undefined;
+                data?: unknown;
             }, {
                 attribute: string;
                 operator: string;
-                data?: Record<string, unknown> | undefined;
+                data?: unknown;
             }>, "many">>;
         }, "strip", import("zod").ZodTypeAny, {
             name: string;
             effects: {
-                effect: string;
+                effect: "give_points" | "give_reward" | "deduct_unit" | "assign_member_custom_attribute" | "remove_member_custom_attribute";
                 walletCode?: string | undefined;
                 rewardId?: string | undefined;
                 pointsRule?: string | undefined;
@@ -417,13 +417,13 @@ export declare const campaignToolDefinitions: readonly [{
             conditions?: {
                 attribute: string;
                 operator: string;
-                data?: Record<string, unknown> | undefined;
+                data?: unknown;
             }[] | undefined;
             target?: "self" | "referrer" | undefined;
         }, {
             name: string;
             effects: {
-                effect: string;
+                effect: "give_points" | "give_reward" | "deduct_unit" | "assign_member_custom_attribute" | "remove_member_custom_attribute";
                 walletCode?: string | undefined;
                 rewardId?: string | undefined;
                 pointsRule?: string | undefined;
@@ -432,7 +432,7 @@ export declare const campaignToolDefinitions: readonly [{
             conditions?: {
                 attribute: string;
                 operator: string;
-                data?: Record<string, unknown> | undefined;
+                data?: unknown;
             }[] | undefined;
             target?: "self" | "referrer" | undefined;
         }>, "many">;
@@ -441,11 +441,11 @@ export declare const campaignToolDefinitions: readonly [{
             tiers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
             segments: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
         }, "strip", import("zod").ZodTypeAny, {
-            target: "all" | "segment" | "tier";
+            target: "all" | "tier" | "segment";
             tiers?: string[] | undefined;
             segments?: string[] | undefined;
         }, {
-            target: "all" | "segment" | "tier";
+            target: "all" | "tier" | "segment";
             tiers?: string[] | undefined;
             segments?: string[] | undefined;
         }>>;
@@ -454,70 +454,133 @@ export declare const campaignToolDefinitions: readonly [{
             tiers: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
             segments: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
         }, "strip", import("zod").ZodTypeAny, {
-            target: "segment" | "tier";
+            target: "tier" | "segment";
             tiers?: string[] | undefined;
             segments?: string[] | undefined;
         }, {
-            target: "segment" | "tier";
+            target: "tier" | "segment";
             tiers?: string[] | undefined;
             segments?: string[] | undefined;
         }>>;
         limits: import("zod").ZodOptional<import("zod").ZodObject<{
             points: import("zod").ZodOptional<import("zod").ZodObject<{
                 value: import("zod").ZodNumber;
-                interval: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+                interval: import("zod").ZodOptional<import("zod").ZodObject<{
+                    type: import("zod").ZodEnum<["calendarDays", "calendarWeeks", "calendarMonths", "calendarYears"]>;
+                    value: import("zod").ZodOptional<import("zod").ZodNumber>;
+                }, "strip", import("zod").ZodTypeAny, {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                }, {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                }>>;
             }, "strip", import("zod").ZodTypeAny, {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             }, {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             }>>;
             pointsPerMember: import("zod").ZodOptional<import("zod").ZodObject<{
                 value: import("zod").ZodNumber;
-                interval: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+                interval: import("zod").ZodOptional<import("zod").ZodObject<{
+                    type: import("zod").ZodEnum<["calendarDays", "calendarWeeks", "calendarMonths", "calendarYears"]>;
+                    value: import("zod").ZodOptional<import("zod").ZodNumber>;
+                }, "strip", import("zod").ZodTypeAny, {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                }, {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                }>>;
             }, "strip", import("zod").ZodTypeAny, {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             }, {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             }>>;
             executionsPerMember: import("zod").ZodOptional<import("zod").ZodObject<{
                 value: import("zod").ZodNumber;
-                interval: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+                interval: import("zod").ZodOptional<import("zod").ZodObject<{
+                    type: import("zod").ZodEnum<["calendarDays", "calendarWeeks", "calendarMonths", "calendarYears"]>;
+                    value: import("zod").ZodOptional<import("zod").ZodNumber>;
+                }, "strip", import("zod").ZodTypeAny, {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                }, {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                }>>;
             }, "strip", import("zod").ZodTypeAny, {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             }, {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             }>>;
         }, "strip", import("zod").ZodTypeAny, {
             points?: {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             } | undefined;
             pointsPerMember?: {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             } | undefined;
             executionsPerMember?: {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             } | undefined;
         }, {
             points?: {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             } | undefined;
             pointsPerMember?: {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             } | undefined;
             executionsPerMember?: {
                 value: number;
-                interval?: Record<string, unknown> | undefined;
+                interval?: {
+                    type: "calendarDays" | "calendarWeeks" | "calendarMonths" | "calendarYears";
+                    value?: number | undefined;
+                } | undefined;
             } | undefined;
         }>>;
         active: import("zod").ZodOptional<import("zod").ZodBoolean>;
@@ -561,7 +624,7 @@ export declare const campaignToolDefinitions: readonly [{
 }, {
     readonly name: "ol_campaign_simulate";
     readonly title: "Simulate Campaign Effects";
-    readonly description: "Simulate campaign effects without executing them. Use to preview what points/rewards a transaction would earn. Provide trigger type, transaction/event data, and customer. Returns simulated effects grouped by campaign.";
+    readonly description: string;
     readonly readOnly: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;

package/dist/tools/campaign/index.js

@@ -20,17 +20,14 @@ export const campaignToolDefinitions = [
     {
         name: "ol_campaign_create",
         title: "Create Campaign",
-        description: "Create campaign to automate engagement (earning rules). " +
-            "⚠️ REQUIRED FIELDS: " +
-            "1. type: 'direct', " +
-            "2. trigger: 'transaction', " +
-            "3. translations: { en: { name: 'Campaign Name' } }, " +
-            "4. activity: { startsAt: '2026-01-01 00:00+00:00' }, " +
-            "5. rules: [{ name: 'Rule Name', effects: [{ effect: 'give_points', pointsRule: 'transaction.grossValue * 10' }] }]. " +
-            "pointsRule is a STRING expression. Examples: '100' (fixed), 'transaction.grossValue * 10' (dynamic). " +
-            "CONDITIONS: Use operator='is_greater_or_equal' (NOT 'gte'), attribute='transaction.grossValue', data=100. " +
-            "For labels: operator='has_at_least_one_label', attribute='transaction.labels', data=[{key:'name',value:'val'}]. " +
-            "To target ALL members, OMIT the audience parameter entirely.",
+        description: "Create a campaign (earning rule) that automatically awards points or rewards when triggered. " +
+            "KEY DECISIONS (confirm with user if not specified): " +
+            "1. Points formula -- fixed ('100') or dynamic ('transaction.grossValue * 10')? This determines cost per transaction. " +
+            "2. Budget caps -- total points limit and per-member limit? Without limits, the campaign has uncapped financial exposure. " +
+            "3. Audience -- all members, or specific tiers/segments? " +
+            "4. End date -- campaigns without endsAt run forever, which is a budget commitment. " +
+            "REQUIRED: type, trigger, translations.en.name, activity.startsAt, rules with effects. " +
+            "In effects array, use key 'effect' (NOT 'type'). pointsRule is a STRING: '100' not 100.",
         readOnly: false,
         inputSchema: CampaignCreateInputSchema,
         handler: campaignCreate,
@@ -71,7 +68,12 @@ export const campaignToolDefinitions = [
     {
         name: "ol_campaign_simulate",
         title: "Simulate Campaign Effects",
-        description: "Simulate campaign effects without executing them. Use to preview what points/rewards a transaction would earn. Provide trigger type, transaction/event data, and customer. Returns simulated effects grouped by campaign.",
+        description: "Simulate campaign effects without executing them. Use to preview what points/rewards a transaction would earn. " +
+            "Example for transaction trigger: { trigger: 'transaction', " +
+            "transaction: { grossValue: 100, documentNumber: 'SIM-001', purchasedAt: '2026-01-01T10:00:00Z', " +
+            "items: [{ sku: 'SKU-1', name: 'Product', grossValue: 100, qty: 1 }] }, " +
+            "customer: { customerId: 'member-uuid' } }. " +
+            "Returns simulated effects grouped by campaign.",
         readOnly: true,
         inputSchema: CampaignSimulateInputSchema,
         handler: campaignSimulate,