@open-loyalty/mcp-server 1.3.7 → 1.5.3

package/dist/tools/points/index.js

@@ -0,0 +1,63 @@
+// Re-export schemas
+export { PointsAddInputSchema, PointsSpendInputSchema, PointsTransferInputSchema, PointsBalanceInputSchema, PointsHistoryInputSchema, PointsHistogramInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { pointsAdd, pointsSpend, pointsTransfer, pointsGetBalance, pointsGetHistory, pointsGetHistogram, } from "./handlers.js";
+// Imports for tool definitions
+import { PointsAddInputSchema, PointsSpendInputSchema, PointsTransferInputSchema, PointsBalanceInputSchema, PointsHistoryInputSchema, PointsHistogramInputSchema, } from "./schemas.js";
+import { pointsAdd, pointsSpend, pointsTransfer, pointsGetBalance, pointsGetHistory, pointsGetHistogram, } from "./handlers.js";
+// Tool definitions
+export const pointsToolDefinitions = [
+    {
+        name: "ol_points_add",
+        title: "Add Points to Member",
+        description: "Add points to a member's wallet manually. " +
+            "BUSINESS IMPACT: Manual point additions bypass campaign rules and limits -- there is no automated undo. " +
+            "Confirm amount and reason with user before proceeding. " +
+            "Use for welcome bonuses, goodwill adjustments, or compensation. Returns transferId.",
+        readOnly: false,
+        inputSchema: PointsAddInputSchema,
+        handler: pointsAdd,
+    }, {
+        name: "ol_points_spend",
+        title: "Spend Member Points",
+        description: "Deduct points from member wallet. Fails if insufficient balance. " +
+            "WORKFLOW: Use ol_points_get_balance first to verify available (activeUnits) points before spending. " +
+            "Returns transferId.",
+        readOnly: false,
+        inputSchema: PointsSpendInputSchema,
+        handler: pointsSpend,
+    }, {
+        name: "ol_points_transfer",
+        title: "Transfer Points Between Members",
+        description: "Transfer points from one member to another (P2P transfer). " +
+            "Sender must have sufficient balance. Returns transferId.",
+        readOnly: false,
+        inputSchema: PointsTransferInputSchema,
+        handler: pointsTransfer,
+    }, {
+        name: "ol_points_get_balance",
+        title: "Check Points Balance",
+        description: "Get member points balance breakdown. activeUnits is available for spending. " +
+            "earnedUnits shows lifetime earnings, lockedUnits shows pending points.",
+        readOnly: true,
+        inputSchema: PointsBalanceInputSchema,
+        handler: pointsGetBalance,
+    }, {
+        name: "ol_points_get_history",
+        title: "View Points History",
+        description: "Get points transaction history for a member. Filter by type: adding, spending, " +
+            "p2p_spending, p2p_adding, blocked, expired. Returns paginated list of transfers. " +
+            "Supports cursor pagination: provide 'cursor' from previous response to get next page.",
+        readOnly: true,
+        inputSchema: PointsHistoryInputSchema,
+        handler: pointsGetHistory,
+    }, {
+        name: "ol_points_get_histogram",
+        title: "View Points Trends",
+        description: "Get points histogram data for visualization. Shows earning and spending patterns over time. " +
+            "Use interval (day/week/month) to aggregate data and dateFrom/dateTo to filter range.",
+        readOnly: true,
+        inputSchema: PointsHistogramInputSchema,
+        handler: pointsGetHistogram,
+    },
+];

package/dist/tools/points/schemas.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export declare const PointsAddInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    memberId: z.ZodString;
+    points: z.ZodNumber;
+    walletCode: z.ZodOptional<z.ZodString>;
+    comment: z.ZodOptional<z.ZodString>;
+    expiresInDays: z.ZodOptional<z.ZodNumber>;
+    lockedUntilDays: z.ZodOptional<z.ZodNumber>;
+};
+export declare const PointsSpendInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    memberId: z.ZodString;
+    points: z.ZodNumber;
+    walletCode: z.ZodOptional<z.ZodString>;
+    comment: z.ZodOptional<z.ZodString>;
+};
+export declare const PointsTransferInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    senderId: z.ZodString;
+    receiverId: z.ZodString;
+    points: z.ZodNumber;
+};
+export declare const PointsBalanceInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    memberId: z.ZodString;
+    walletCode: z.ZodOptional<z.ZodString>;
+};
+export declare const PointsHistoryInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    memberId: z.ZodString;
+    cursor: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodOptional<z.ZodEnum<["adding", "spending", "p2p_spending", "p2p_adding", "blocked", "expired"]>>;
+};
+export declare const PointsHistogramInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    memberId: z.ZodString;
+    pointType: z.ZodEnum<["spent", "earned", "expired", "pending"]>;
+    walletCode: z.ZodOptional<z.ZodString>;
+    interval: z.ZodOptional<z.ZodEnum<["day", "week", "month"]>>;
+    dateFrom: z.ZodOptional<z.ZodString>;
+    dateTo: z.ZodOptional<z.ZodString>;
+};

package/dist/tools/points/schemas.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+export const PointsAddInputSchema = {
+    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) to add points to."),
+    points: z.number().describe("Number of points to add (positive number). " +
+        "BUSINESS IMPACT: Manual point additions bypass campaign rules and limits. Confirm amount and reason with user."),
+    walletCode: z.string().optional().describe("Wallet type code (e.g., 'default'). Uses default wallet if not specified."),
+    comment: z.string().optional().describe("Reason for adding points (max 500 chars)."),
+    expiresInDays: z.number().optional().describe("Days until these specific points expire (1-9999). " +
+        "BUSINESS DECISION: Custom expiry for these points. Omit to use wallet default expiry."),
+    lockedUntilDays: z.number().optional().describe("Days until points become available (1-9999)."),
+};
+export const PointsSpendInputSchema = {
+    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) to spend points from."),
+    points: z.number().describe("Number of points to spend (positive number)."),
+    walletCode: z.string().optional().describe("Wallet type code (e.g., 'default'). Uses default wallet if not specified."),
+    comment: z.string().optional().describe("Reason for spending points (max 500 chars)."),
+};
+export const PointsTransferInputSchema = {
+    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."),
+    senderId: z.string().describe("The sender member ID (UUID)."),
+    receiverId: z.string().describe("The receiver member ID (UUID)."),
+    points: z.number().describe("Number of points to transfer."),
+};
+export const PointsBalanceInputSchema = {
+    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) to get balance for."),
+    walletCode: z.string().optional().describe("Wallet type code. Returns all wallets if not specified."),
+};
+export const PointsHistoryInputSchema = {
+    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) to get history for."),
+    cursor: z.string().optional().describe("Pagination cursor from previous response. If provided, page/perPage are ignored."),
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 10)."),
+    type: z.enum(["adding", "spending", "p2p_spending", "p2p_adding", "blocked", "expired"]).optional().describe("Filter by transfer type."),
+};
+export const PointsHistogramInputSchema = {
+    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) to get histogram for."),
+    pointType: z.enum(["spent", "earned", "expired", "pending"]).describe("Filter by point type (required). One of: spent, earned, expired, pending."),
+    walletCode: z.string().optional().describe("Wallet type code. Uses default if not specified."),
+    interval: z.enum(["day", "week", "month"]).optional().describe("Time interval for aggregation (default: month)."),
+    dateFrom: z.string().optional().describe("Start date for histogram (ISO format: YYYY-MM-DD)."),
+    dateTo: z.string().optional().describe("End date for histogram (ISO format: YYYY-MM-DD)."),
+};

package/dist/tools/referral/schemas.js

@@ -7,7 +7,7 @@ export const ReferralCreateInputSchema = {
     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."),
+        .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()
         .uuid()
@@ -25,7 +25,7 @@ export const ReferralListInputSchema = {
     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."),
+        .describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
     referralId: z.string().uuid().optional().describe("Filter by specific referral ID"),
     referrerId: z.string().uuid().optional().describe("Filter by referrer member ID"),
     referrerName: z.string().max(255).optional().describe("Filter by referrer name"),
@@ -44,7 +44,7 @@ export const ReferralDeleteInputSchema = {
     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."),
+        .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()
         .uuid()

package/dist/tools/reward/handlers.d.ts

@@ -35,6 +35,8 @@ export declare function rewardCreate(input: {
         from: string;
         to: string;
     };
+    usageLimitPerUser?: number;
+    usageLimitGeneral?: number;
     costInPoints?: number;
     usageInstruction?: string;
     active?: boolean;

package/dist/tools/reward/handlers.js

@@ -46,16 +46,22 @@ export async function rewardList(input) {
 }
 export async function rewardCreate(input) {
     const storeCode = getStoreCode(input.storeCode);
-    // API requires: translations (name only), reward (type), activity, visibility
-    // NOTE: usageLimit is NOT supported at creation time - API rejects it as "extra fields"
-    // Use reward_update after creation to set usageLimit
+    // API requires: translations (name only), reward (type), activity, visibility, usageLimit
     // NOTE: description is NOT supported by the API at creation time
+    // CRITICAL: usageLimit shape depends on reward TYPE:
+    //   - material/fortune_wheel: require BOTH perUser AND general
+    //   - static_coupon/dynamic_coupon/conversion_coupon: require ONLY perUser (general is rejected as "extra fields")
+    const isCouponType = ["static_coupon", "dynamic_coupon", "conversion_coupon"].includes(input.reward);
+    const usageLimit = { perUser: input.usageLimitPerUser ?? 0 };
+    if (!isCouponType) {
+        usageLimit.general = input.usageLimitGeneral ?? 0;
+    }
     const payload = omitUndefined({
         translations: input.translations,
         reward: input.reward,
         activity: input.activity,
         visibility: input.visibility,
-        // usageLimit: NOT SUPPORTED at creation - use update after creation
+        usageLimit,
         costInPoints: input.costInPoints,
         usageInstruction: input.usageInstruction,
         active: input.active,
@@ -76,6 +82,31 @@ export async function rewardCreate(input) {
         };
     }
     catch (error) {
+        // Check for invalid reward type
+        const axiosError = error;
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const rewardTypeError = apiErrors.find(e => e.path === "reward" && e.message.includes("selected choice is invalid"));
+        if (rewardTypeError) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_REWARD_TYPE",
+                message: `Reward type '${input.reward}' is not valid`,
+                hint: "Valid reward types: 'material' (physical goods), 'static_coupon' (fixed discount code), " +
+                    "'dynamic_coupon' (variable value coupon), 'conversion_coupon' (points-to-coupon conversion), " +
+                    "'fortune_wheel' (gamified reward). NOTE: 'discount_code' is NOT a valid type - use 'static_coupon' instead.",
+                relatedTool: "ol_reward_create",
+            });
+        }
+        // Detect missing couponValue for coupon-type rewards
+        const allErrorMessages = apiErrors.map(e => `${e.path || ""}: ${e.message}`).join(" ").toLowerCase();
+        if ((allErrorMessages.includes("coupon") || allErrorMessages.includes("couponvalue")) &&
+            ["static_coupon", "dynamic_coupon", "conversion_coupon"].includes(input.reward)) {
+            throw new OpenLoyaltyError({
+                code: "MISSING_COUPON_VALUE",
+                message: `Reward type '${input.reward}' requires couponValue`,
+                hint: `For coupon-type rewards, you MUST provide couponValue (e.g., couponValue: 10 for a $10 coupon). Add couponValue to your request and retry.`,
+                relatedTool: "ol_reward_create",
+            });
+        }
         throw formatApiError(error, "ol_reward_create");
     }
 }
@@ -164,9 +195,35 @@ export async function rewardUpdate(input) {
         payload.levels = input.levels;
     if (input.segments !== undefined)
         payload.segments = input.segments;
-    // usageLimit - only pass perUser (API rejects 'general' as extra field)
+    // usageLimit handling depends on reward type:
+    //   - material/fortune_wheel: require BOTH perUser AND general
+    //   - coupon types: only accept perUser (general is rejected as "extra fields")
+    const existingRewardType = existing.reward;
+    const isCouponType = ["static_coupon", "dynamic_coupon", "conversion_coupon"].includes(existingRewardType || "");
+    const existingUsageLimit = existing.usageLimit;
     if (input.usageLimitPerUser !== undefined) {
-        payload.usageLimit = { perUser: input.usageLimitPerUser };
+        // User explicitly setting usageLimitPerUser
+        if (isCouponType) {
+            payload.usageLimit = { perUser: input.usageLimitPerUser };
+        }
+        else {
+            payload.usageLimit = {
+                perUser: input.usageLimitPerUser,
+                general: existingUsageLimit?.general ?? 0,
+            };
+        }
+    }
+    else if (existingUsageLimit) {
+        // Preserve existing usageLimit (API requires it on PUT for material type)
+        if (isCouponType) {
+            payload.usageLimit = { perUser: existingUsageLimit.perUser ?? 0 };
+        }
+        else {
+            payload.usageLimit = {
+                perUser: existingUsageLimit.perUser ?? 0,
+                general: existingUsageLimit.general ?? 0,
+            };
+        }
     }
     try {
         await apiPut(`/${storeCode}/reward/${input.rewardId}`, { reward: payload });
@@ -230,6 +287,22 @@ export async function rewardBuy(input) {
                 relatedTool: "ol_reward_buy",
             });
         }
+        if (allMessages.includes("not active") || allMessages.includes("inactive") || allMessages.includes("reward is not active")) {
+            throw new OpenLoyaltyError({
+                code: "REWARD_NOT_ACTIVE",
+                message: "This reward is not active and cannot be purchased",
+                hint: `Use ol_reward_activate(rewardId: "${input.rewardId}") to activate the reward first, or use ol_reward_get(rewardId: "${input.rewardId}") to check its status.`,
+                relatedTool: "ol_reward_buy",
+            });
+        }
+        if (allMessages.includes("usage limit") || allMessages.includes("limit reached") || allMessages.includes("limit exceeded")) {
+            throw new OpenLoyaltyError({
+                code: "USAGE_LIMIT_REACHED",
+                message: "The usage limit for this reward has been reached",
+                hint: `Use ol_reward_get(rewardId: "${input.rewardId}") to check usageLimit settings. To increase limits, use ol_reward_update(rewardId: "${input.rewardId}", usageLimitPerUser: N).`,
+                relatedTool: "ol_reward_buy",
+            });
+        }
         throw formatApiError(error, "ol_reward_buy");
     }
 }

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

@@ -68,6 +68,8 @@ export declare const rewardToolDefinitions: readonly [{
             from: string;
             to: string;
         }>;
+        usageLimitPerUser: import("zod").ZodOptional<import("zod").ZodNumber>;
+        usageLimitGeneral: import("zod").ZodOptional<import("zod").ZodNumber>;
         costInPoints: import("zod").ZodOptional<import("zod").ZodNumber>;
         usageInstruction: import("zod").ZodOptional<import("zod").ZodString>;
         active: import("zod").ZodOptional<import("zod").ZodBoolean>;

package/dist/tools/reward/index.js

@@ -20,15 +20,13 @@ export const rewardToolDefinitions = [
         name: "ol_reward_create",
         title: "Create New Reward",
         description: "Create a new reward that members can redeem with points. " +
-            "⚠️ REQUIRED FIELDS (will fail without these): " +
-            "1. translations: { en: { name: 'Reward Name' } }, " +
-            "2. reward: 'material' or 'static_coupon' or 'dynamic_coupon', " +
-            "3. activity: { from: '2026-01-01 00:00', to: '2027-12-31 23:59' }, " +
-            "4. visibility: { from: '2026-01-01 00:00', to: '2027-12-31 23:59' }. " +
-            "Types: material (physical goods), static_coupon (fixed discount - requires couponValue), dynamic_coupon (variable value). " +
-            "For coupons: add couponValue (required!), couponValueType ('money' or 'percentage'), daysValid. " +
-            "For tier targeting: set target='level' and levels=['tier-uuid-1', 'tier-uuid-2']. " +
-            "⚠️ usageLimit is NOT supported at creation - use reward_update after creation to set limits.",
+            "KEY DECISIONS (confirm with user if not specified): " +
+            "1. Reward type -- material (physical item), static_coupon (discount code), dynamic_coupon, conversion_coupon, fortune_wheel " +
+            "2. Cost in points -- how many points to redeem? (this is the program's exchange rate) " +
+            "3. Usage limits -- how many redemptions per member? How many total? (0 = unlimited, creates uncapped liability) " +
+            "4. Targeting -- all members, or restricted to specific tiers/segments? " +
+            "REQUIRED: translations.en.name, reward type, activity period, visibility period. " +
+            "For static_coupon: couponValue is also required.",
         readOnly: false,
         inputSchema: RewardCreateInputSchema,
         handler: rewardCreate,
@@ -45,7 +43,9 @@ export const rewardToolDefinitions = [
         name: "ol_reward_update",
         title: "Update Reward",
         description: "Update reward configuration. Cannot change reward type after creation. " +
-            "Use usageLimitPerUser to set maximum redemptions per member (this is NOT supported at creation time).",
+            "Uses GET-then-PUT pattern (fetches existing reward, merges changes, sends full object). " +
+            "usageLimitPerUser can be set here or at creation time. " +
+            "For material rewards, usageLimit.general is preserved from existing data on update.",
         readOnly: false,
         inputSchema: RewardUpdateInputSchema,
         handler: rewardUpdate,

package/dist/tools/reward/schemas.d.ts

@@ -55,6 +55,8 @@ export declare const RewardCreateInputSchema: {
         from: string;
         to: string;
     }>;
+    usageLimitPerUser: z.ZodOptional<z.ZodNumber>;
+    usageLimitGeneral: z.ZodOptional<z.ZodNumber>;
     costInPoints: z.ZodOptional<z.ZodNumber>;
     usageInstruction: z.ZodOptional<z.ZodString>;
     active: z.ZodOptional<z.ZodBoolean>;

package/dist/tools/reward/schemas.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export const RewardListInputSchema = {
-    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."),
@@ -26,49 +26,68 @@ const RewardVisibilityInputSchema = z.object({
     from: z.string().describe("Visibility start datetime (format: 'YYYY-MM-DD HH:mm'). REQUIRED."),
     to: z.string().describe("Visibility end datetime (format: 'YYYY-MM-DD HH:mm'). REQUIRED."),
 });
-// NOTE: usageLimit is NOT supported at creation time - API rejects it as "extra fields"
-// Use reward_update with usageLimitPerUser after creation instead
+// NOTE: usageLimit shape depends on reward TYPE:
+//   - material/fortune_wheel: require BOTH perUser AND general
+//   - coupon types (static_coupon, dynamic_coupon, conversion_coupon): only accept perUser
+// Handler automatically sends the correct shape based on reward type.
 export const RewardCreateInputSchema = {
-    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: RewardTranslationsInputSchema.describe("Reward name translations. At least 'en' key with { name } is REQUIRED."),
-    reward: z.enum(["static_coupon", "dynamic_coupon", "conversion_coupon", "material", "fortune_wheel"]).describe("Reward type: static_coupon (fixed discount), dynamic_coupon (variable value), " +
-        "conversion_coupon (converts points to coupon), material (physical goods), fortune_wheel (gamified)."),
+    reward: z.enum(["static_coupon", "dynamic_coupon", "conversion_coupon", "material", "fortune_wheel"]).describe("Reward fulfillment type. " +
+        "'material' = physical goods/experiences, 'static_coupon' = fixed discount code (requires couponValue), " +
+        "'dynamic_coupon' = variable value coupon, 'conversion_coupon' = points-to-credit (requires unitsConversion), " +
+        "'fortune_wheel' = gamified spin-to-win. " +
+        "BUSINESS DECISION: Each type has different cost structures and operational requirements. " +
+        "NOTE: 'discount_code' is NOT valid -- use 'static_coupon'."),
     activity: RewardActivityInputSchema.describe("Activity period when reward can be purchased. Use datetime format 'YYYY-MM-DD HH:mm'. REQUIRED."),
     visibility: RewardVisibilityInputSchema.describe("Visibility period when reward is shown. Use datetime format 'YYYY-MM-DD HH:mm'. REQUIRED."),
-    // usageLimit: NOT SUPPORTED at creation - removed. Use reward_update after creation.
-    costInPoints: z.number().optional().describe("Points required to redeem this reward."),
+    usageLimitPerUser: z.number().optional().describe("Max redemptions per member (0 = unlimited). " +
+        "BUSINESS IMPACT: Unlimited allows a single member to exhaust entire reward stock. " +
+        "Typical values: 1 (exclusive/one-time), 3-5 (promotional), 10+ (evergreen). " +
+        "BUSINESS DECISION: Confirm with user -- this directly controls reward budget exposure."),
+    usageLimitGeneral: z.number().optional().describe("Max total redemptions across all members (0 = unlimited). " +
+        "ONLY for 'material' and 'fortune_wheel' types -- API rejects this for coupon types. " +
+        "BUSINESS IMPACT: This is the total inventory cap. Running out unexpectedly damages member trust."),
+    costInPoints: z.number().optional().describe("Points required to redeem this reward. " +
+        "BUSINESS IMPACT: This is the program's points-to-value exchange rate. " +
+        "Too low = members drain value too fast. Too high = rewards feel unattainable. " +
+        "Typical values: if earn rate is 10 pts/$1 spent, a $10 reward should cost 500-2000 points."),
     usageInstruction: z.string().optional().describe("Instructions for using the reward."),
     active: z.boolean().optional().describe("Whether reward is active (default: false)."),
-    categories: z.array(z.string()).optional().describe("Array of category UUIDs."),
-    levels: z.array(z.string()).optional().describe("Array of tier level UUIDs that can see/redeem."),
-    segments: z.array(z.string()).optional().describe("Array of segment UUIDs that can see/redeem."),
-    target: z.enum(["level", "segment"]).nullable().optional().describe("Target type for visibility: level (tier-based), segment (segment-based), or null (all)."),
-    couponValue: z.number().optional().describe("Coupon value (required for static_coupon)."),
-    couponValueType: z.enum(["money", "percentage"]).optional().describe("Coupon value type: 'money' or 'percentage' (lowercase)."),
+    categories: z.array(z.string()).optional().describe("Array of category UUIDs. Use ol_reward_category_list() to find valid categoryId values."),
+    levels: z.array(z.string()).optional().describe("Array of tier level UUIDs that can see/redeem. Use ol_tierset_get_tiers(tierSetId) to find valid levelId values."),
+    segments: z.array(z.string()).optional().describe("Array of segment UUIDs that can see/redeem. Use ol_segment_list() to find valid segmentId values."),
+    target: z.enum(["level", "segment"]).nullable().optional().describe("Targeting: 'level' = specific tiers, 'segment' = specific segments, null = all members. " +
+        "BUSINESS DECISION: Untargeted rewards reach everyone but dilute exclusivity. " +
+        "Tier-targeted rewards drive tier progression motivation."),
+    couponValue: z.number().optional().describe("Coupon value (required for static_coupon). " +
+        "BUSINESS DECISION: Dollar/percentage value of the discount. Direct revenue impact."),
+    couponValueType: z.enum(["money", "percentage"]).optional().describe("Coupon value type: 'money' or 'percentage' (lowercase). " +
+        "BUSINESS DECISION: Money vs percentage completely changes the economics."),
     daysValid: z.number().optional().describe("Days the coupon remains valid after purchase."),
 };
 export const RewardGetInputSchema = {
-    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."),
     rewardId: z.string().describe("The reward ID (UUID) to retrieve."),
 };
 export const RewardUpdateInputSchema = {
-    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."),
     rewardId: z.string().describe("The reward ID (UUID) to update."),
     name: z.string().optional().describe("Reward name."),
     costInPoints: z.number().optional().describe("Points required to redeem."),
     description: z.string().optional().describe("Reward description."),
     active: z.boolean().optional().describe("Whether reward is active."),
-    categories: z.array(z.string()).optional().describe("Array of category UUIDs."),
-    levels: z.array(z.string()).optional().describe("Array of tier level UUIDs."),
-    segments: z.array(z.string()).optional().describe("Array of segment UUIDs."),
+    categories: z.array(z.string()).optional().describe("Array of category UUIDs. Use ol_reward_category_list() to find valid categoryId values."),
+    levels: z.array(z.string()).optional().describe("Array of tier level UUIDs. Use ol_tierset_get_tiers(tierSetId) to find valid levelId values."),
+    segments: z.array(z.string()).optional().describe("Array of segment UUIDs. Use ol_segment_list() to find valid segmentId values."),
     usageLimitPerUser: z.number().optional().describe("Maximum redemptions per member. Set this after creation to limit usage."),
 };
 export const RewardIdInputSchema = {
-    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."),
     rewardId: z.string().describe("The reward ID (UUID)."),
 };
 export const RewardBuyInputSchema = {
-    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."),
     rewardId: z.string().describe("The reward ID (UUID) to purchase."),
     memberId: z.string().describe("The member ID (UUID) purchasing the reward."),
     quantity: z.number().optional().describe("Number of rewards to purchase (1-32, default: 1)."),
@@ -76,12 +95,12 @@ export const RewardBuyInputSchema = {
     withoutPoints: z.boolean().optional().describe("Admin only: skip points deduction."),
 };
 export const RewardRedeemInputSchema = {
-    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) redeeming the coupon."),
     couponCode: z.string().describe("The coupon code to redeem."),
 };
 export const RewardCategoryListInputSchema = {
-    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."),

package/dist/tools/segment/index.js

@@ -18,11 +18,13 @@ export const segmentToolDefinitions = [
     {
         name: "ol_segment_create",
         title: "Create Segment",
-        description: "Create segment to group members. " +
-            "⚠️ ONLY 'transaction_count' criterion type works reliably. 'tier' and 'points_balance' are REJECTED by the API. " +
-            "REQUIRED: name, parts array with criteria. " +
-            "Example for 5+ purchases: { name: 'Frequent Buyers', parts: [{ criteria: [{ type: 'transaction_count', min: 5 }] }], active: true }. " +
-            "Parts use OR logic (ANY part matches), criteria within parts use AND logic (ALL criteria must match).",
+        description: "Create a segment to group members by behavior or attributes for campaign targeting and analytics. " +
+            "KEY DECISIONS (confirm with user if not specified): " +
+            "1. Criteria type -- what defines this segment? transaction_count, purchase_in_period, average_transaction_value, bought_skus, bought_labels, etc. " +
+            "2. Threshold values -- min/max boundaries? (e.g., min=5 transactions captures frequent buyers; min=2 captures nearly everyone) " +
+            "3. Intended use -- campaign targeting (activate immediately) or analytics only (can stay inactive)? " +
+            "REQUIRED: name, parts array with criteria. Parts use OR logic, criteria within parts use AND logic. " +
+            "NOTE: 'tier' and 'points_balance' types are REJECTED by the API despite being documented.",
         readOnly: false,
         inputSchema: SegmentCreateInputSchema,
         handler: segmentCreate,

package/dist/tools/segment/schemas.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 // Input Schemas
 export const SegmentListInputSchema = {
-    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."),
@@ -18,8 +18,8 @@ const SegmentCriterionInputSchema = z.object({
     days: z.number().optional().describe("Days for time-based criteria."),
     fromDate: z.string().optional().describe("Start date (ISO format)."),
     toDate: z.string().optional().describe("End date (ISO format)."),
-    min: z.number().optional().describe("Minimum value."),
-    max: z.number().optional().describe("Maximum value."),
+    min: z.number().optional().describe("Minimum value. BUSINESS IMPACT: Too low a threshold (e.g., min=2 transactions) captures most members -- segment becomes too broad, wasting campaign budget."),
+    max: z.number().optional().describe("Maximum value. BUSINESS IMPACT: Too narrow a range (e.g., max=3 with min=3) captures very few members -- limited campaign impact."),
     posIds: z.array(z.string()).optional().describe("POS IDs."),
     skus: z.array(z.string()).optional().describe("SKU codes."),
     makers: z.array(z.string()).optional().describe("Maker/brand names."),
@@ -37,18 +37,18 @@ const SegmentPartInputSchema = z.object({
     criteria: z.array(SegmentCriterionInputSchema).describe("Criteria for this part (AND logic)."),
 });
 export const SegmentCreateInputSchema = {
-    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."),
     name: z.string().describe("Segment name (required)."),
     description: z.string().optional().describe("Segment description."),
     active: z.boolean().optional().describe("Whether segment is active (default: false)."),
     parts: z.array(SegmentPartInputSchema).describe("Segment parts. Parts use OR logic (ANY part matches), criteria within parts use AND logic (ALL criteria must match)."),
 };
 export const SegmentGetInputSchema = {
-    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."),
     segmentId: z.string().describe("The segment ID (UUID) to retrieve."),
 };
 export const SegmentUpdateInputSchema = {
-    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."),
     segmentId: z.string().describe("The segment ID (UUID) to update."),
     name: z.string().describe("Segment name."),
     description: z.string().optional().describe("Segment description."),
@@ -56,24 +56,24 @@ export const SegmentUpdateInputSchema = {
     parts: z.array(SegmentPartInputSchema).describe("Segment parts."),
 };
 export const SegmentDeleteInputSchema = {
-    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."),
     segmentId: z.string().describe("The segment ID (UUID) to delete."),
 };
 export const SegmentGetMembersInputSchema = {
-    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."),
     segmentId: z.string().describe("The segment ID (UUID) to get members for."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),
 };
 export const SegmentActivateInputSchema = {
-    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."),
     segmentId: z.string().describe("The segment ID (UUID) to activate."),
 };
 export const SegmentDeactivateInputSchema = {
-    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."),
     segmentId: z.string().describe("The segment ID (UUID) to deactivate."),
 };
 export const SegmentGetResourcesInputSchema = {
-    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."),
     segmentId: z.string().describe("The segment ID (UUID) to get associated resources for."),
 };