Tool reference
Tools are what the assistant calls behind the scenes. You don't need to name them — just ask. The names help when you read logs or set tool permissions in your AI tool.
On the local server, the loyalty page and Redeem in Cart tools need @joy-loyalty/mcp
0.4.0 or later.
Read — always available
| Tool | What it returns |
|---|---|
joy_get_loyalty_overview | Store name, domain, plan, currency, timezone and loyalty settings |
joy_list_earning_rules | Every way customers earn points, including per-tier rates |
joy_list_redemption_rules | Every way customers spend points, with costs and limits |
joy_list_tiers | VIP tiers with thresholds, multipliers, benefits and member counts |
joy_get_referral_program | Whether referrals are on, and what the referrer and friend get |
joy_find_member | One member by email or customer ID: balance, tier, stats, progress to next tier |
joy_list_members | Members sorted by points, signup or activity, filterable by tier; total count |
joy_get_member_activity | One member's point history, with balance before and after |
joy_get_member_rewards | Coupons a member has redeemed: code, program, status, expiry |
joy_get_member_store_credit | A member's Shopify store credit balance (money, not points) |
joy_explain_order_points | Why an order did or didn't earn points, naming the rule that decided it |
joy_get_loyalty_health_check | A health score out of 100 against the previous period, with flags |
joy_list_activities | Which members earned, redeemed, expired, changed tier or joined in a period |
joy_investigate_member_risk | Abuse checks on one member: lookalike emails, shared device or IP, prior orders |
joy_get_tier_upgrade_candidates | Members closest to the next tier, and how little they need |
joy_get_retention_risk_members | Members whose points expire soon or who may drop a tier |
joy_get_analytics_report | Any Joy Analytics report: members, tiers, points, rewards, coupons, referrals, revenue |
joy_get_loyalty_revenue_report | Sales, AOV and returning rate on loyalty orders, from Shopify's sales data |
joy_get_tier_performance_breakdown | Shopify sales, AOV and orders per customer by VIP tier |
joy_get_referral_performance | How many referral coupons were used in a period |
joy_get_member_referrals | One member's referral results and recent referrals |
joy_get_loyalty_page_design | Your loyalty page's colors, fonts and sections, and whether it's live in your theme |
joy_get_loyalty_page_text | Your loyalty page's text in one language |
joy_check_theme_setup | Whether the Joy widget, app embeds and blocks are on in your live theme |
joy_scan_brand_design | Your storefront's colors, fonts and button style |
joy_get_widget_fields | The widget settings that can be changed, with current values |
joy_get_redeem_in_cart | Your Redeem in Cart settings and design |
Changes — Full access
| Tool | What it does | Safeguard |
|---|---|---|
joy_award_points | Gives points to a member | Reason required; safe to retry after a timeout |
joy_deduct_points | Removes points | Reason required; previews first over 1,000 points or below zero |
joy_adjust_points | Corrects a balance by a set amount | Previews first by default; reason required |
joy_redeem_reward | Spends points on a reward and returns the coupon code | Can take up to 30 seconds; don't retry blindly |
joy_refund_coupon | Cancels a point-redeemed coupon and returns the points | Reason required; don't retry blindly |
joy_set_member_tier | Moves a member to a tier; may trigger that tier's rewards | Reason required |
joy_create_referral_invite | Returns a member's referral link | Creates a customer for a non-member email |
joy_enable_analytics_v2 | Switches your store to the new Joy Analytics and imports history | Assistant confirms with you first |
joy_update_loyalty_page_design | Changes your loyalty page design | Draft unless you publish; icons go live right away |
joy_update_loyalty_page_text | Changes your loyalty page text | Goes live right away; re-translates other languages |
joy_revert_loyalty_page_design | Undoes the most recent loyalty page change | Restores to your draft; restored icons go live |
Settings changes — local server, opt-in
All of these need a reason and are built to preview first. None of them are recorded in your activity log, and repeating one can create a duplicate.
| Tool | What it does |
|---|---|
joy_configure_earning_program | Creates or edits an earning rule (orders, sign-up, birthday, reviews, social follows…) |
joy_configure_redemption_program | Creates or edits a reward: amount off, % off, free shipping, free gift |
joy_configure_tier | Creates or edits a VIP tier |
joy_configure_tier_reward | Adds or changes a tier reward |
joy_configure_tier_perks | Replaces a tier's list of perks |
joy_configure_tier_settings | Tier calculation, demotion, reset, tags and notifications |
joy_configure_shop_settings | A set of shop-wide settings such as language, date format and earning limits |
joy_add_translation_language | Adds a storefront language and translates your content |
joy_configure_referral_program | Referrer and friend rewards |
joy_configure_referral_widget | The live referral popup |
joy_configure_widget_draft | Applies branding to the widget; draft by default, a live save can't be undone |
joy_set_widget_fields | Changes widget settings; draft by default, a live save can't be undone |
joy_configure_redeem_in_cart | Redeem in Cart behavior and position |
joy_configure_redeem_in_cart_design | Redeem in Cart style and colors |
joy_upload_image | Uploads an image to your Shopify Files |
Changes to tier thresholds wait until you relaunch tiers in the Joy admin. Changes to how tier progress is counted or when the program starts apply to new activity right away; existing members keep their tier points until you relaunch.