@carrierllc/mcp 0.1.0 → 0.2.1

package/dist/intelligence.js

@@ -1,13 +1,15 @@
-/**
- * Carrier MCP stdio — Intelligence tools (8 composites).
- *
- * These tools chain multiple OCS read methods to produce structured insights.
- * Stdio variant: no scope enforcement, no audit hook, no Sentry.
- */
 import { z } from "zod";
-async function safeCall(client, method, params = {}) {
+import { mccToIso } from "@carrier/ocs-spec/mcc-iso";
+import { OcsClient } from "./client.js";
+import { getDefaultResellerId } from "./tools.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function safeCall(env, token, method, params = {}) {
     try {
-        return { data: await client.call(method, params), error: null };
+        const client = new OcsClient(env.CARRIER_OCS_BASE_URL, token);
+        const data = await client.call(method, params);
+        return { data, error: null };
     }
     catch (err) {
         return { data: null, error: err instanceof Error ? err.message : String(err) };
@@ -21,7 +23,9 @@ function formatBytes(bytes) {
     return `${(bytes / Math.pow(1024, i)).toFixed(2)} ${units[i]}`;
 }
 function daysUntil(dateStr) {
-    return Math.ceil((new Date(dateStr).getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+    const now = new Date();
+    const target = new Date(dateStr);
+    return Math.ceil((target.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
 }
 function toISODate(d) {
     return d.toISOString().split("T")[0];
@@ -29,60 +33,60 @@ function toISODate(d) {
 function result(text, isError = false) {
     return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) };
 }
-function makeIntelHandler(_client, fn) {
-    return async (args) => {
-        try {
-            return await fn(args);
-        }
-        catch (err) {
-            return result(`Error: ${err instanceof Error ? err.message : String(err)}`, true);
-        }
-    };
-}
-export function registerAllIntelligenceTools(server, client) {
-    // -------------------------------------------------------------------------
-    // 1. DIAGNOSE SUBSCRIBER
-    // -------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// 1. DIAGNOSE SUBSCRIBER — "why is this subscriber offline?"
+// ---------------------------------------------------------------------------
+export function registerIntelligenceTools(server, ctx) {
     server.registerTool("diagnose_subscriber", {
         title: "Diagnose Subscriber Issues",
-        description: "Smart diagnostic that chains multiple API calls to analyse why a subscriber may be offline, throttled, or having connectivity issues.",
-        inputSchema: { iccid: z.string().describe("The subscriber ICCID to diagnose") },
+        description: "Smart diagnostic that chains multiple API calls to analyze why a subscriber " +
+            "may be offline, throttled, or having connectivity issues. Returns a structured " +
+            "diagnosis with root cause analysis and recommended actions.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID to diagnose"),
+        },
         annotations: { readOnlyHint: true },
-    }, makeIntelHandler(client, async ({ iccid }) => {
+    }, async ({ iccid }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
         const findings = [];
         const actions = [];
         let severity = "healthy";
-        const sub = await safeCall(client, "getSingleSubscriber", { iccid });
+        // 1. Get subscriber details
+        const sub = await safeCall(ctx.env, token, "getSingleSubscriber", { iccid });
         if (sub.error)
             return result(`Failed to fetch subscriber: ${sub.error}`, true);
         if (!sub.data)
             return result("Subscriber not found", true);
         const status = String(sub.data.status ?? "").toUpperCase();
         const balance = Number(sub.data.balance ?? 0);
+        // Check OCS status
         if (status !== "ACTIVE") {
             findings.push(`OCS status is ${status} (not ACTIVE)`);
-            actions.push("Reactivate subscriber via modify_subscriber_status");
+            actions.push(`Reactivate subscriber via modify_subscriber_status`);
             severity = "critical";
         }
+        // Check balance
         if (balance <= 0) {
             findings.push(`Balance is ${balance} — subscriber may be blocked from usage`);
-            actions.push("Top up balance via modify_subscriber_balance");
+            actions.push(`Top up balance via modify_subscriber_balance`);
             if (severity !== "critical")
                 severity = "warning";
         }
-        const simIdForStatus = sub.data.simId ?? sub.data.sim_id ?? sub.data.id;
-        const sim = simIdForStatus !== undefined
-            ? await safeCall(client, "getSimProviderStatus", Number(simIdForStatus))
+        // 2. Check SIM provider status — OCS expects bare simId (Long), resolve from subscriber record
+        const simId = sub.data.simId ?? sub.data.sim_id ?? sub.data.id;
+        const sim = simId !== undefined
+            ? await safeCall(ctx.env, token, "getSimProviderStatus", Number(simId))
             : { data: null, error: null };
         if (sim.data) {
             const simStatus = String(sim.data.simStatus ?? sim.data.status ?? "").toUpperCase();
             if (simStatus && !["ENABLED", "ACTIVE", "ACTIVATED"].includes(simStatus)) {
                 findings.push(`SIM provider status is ${simStatus} — SIM may be disabled at network level`);
-                actions.push("Enable SIM via change_sim_status");
+                actions.push(`Enable SIM via change_sim_status`);
                 severity = "critical";
             }
         }
-        const pkgs = await safeCall(client, "listSubscriberPrepaidPackages", { iccid });
+        // 3. Check packages
+        const pkgs = await safeCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid });
         if (pkgs.data && Array.isArray(pkgs.data)) {
             const activePkgs = pkgs.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
             if (activePkgs.length === 0) {
@@ -91,15 +95,18 @@ export function registerAllIntelligenceTools(server, client) {
                 severity = "critical";
             }
             else {
+                // Check for depleted packages
                 for (const pkg of activePkgs) {
                     const dataUsed = Number(pkg.dataUsed ?? pkg.dataConsumed ?? 0);
                     const dataLimit = Number(pkg.dataLimit ?? pkg.dataAllowance ?? 0);
                     if (dataLimit > 0 && dataUsed >= dataLimit) {
-                        findings.push(`Package "${pkg.name ?? pkg.packageTemplateId}" data depleted: ${formatBytes(dataUsed)} / ${formatBytes(dataLimit)}`);
+                        findings.push(`Package "${pkg.name ?? pkg.packageTemplateId}" data depleted: ` +
+                            `${formatBytes(dataUsed)} / ${formatBytes(dataLimit)}`);
                         actions.push("Assign additional package or increase limits via modify_package_limits");
                         if (severity !== "critical")
                             severity = "warning";
                     }
+                    // Check expiry
                     const expiry = String(pkg.expirationDate ?? pkg.endDate ?? "");
                     if (expiry) {
                         const days = daysUntil(expiry);
@@ -119,9 +126,13 @@ export function registerAllIntelligenceTools(server, client) {
                 }
             }
         }
+        // 4. Check recent network events (last 2 days)
         const now = new Date();
         const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000);
-        const events = await safeCall(client, "subscriberNetworkEventsOverPeriod", { subscriber: { iccid }, period: { start: toISODate(twoDaysAgo), end: toISODate(now) } });
+        const events = await safeCall(ctx.env, token, "subscriberNetworkEventsOverPeriod", {
+            subscriber: { iccid },
+            period: { start: toISODate(twoDaysAgo), end: toISODate(now) },
+        });
         if (events.data && Array.isArray(events.data)) {
             if (events.data.length === 0) {
                 findings.push("No network events in last 48 hours — device may be powered off or out of coverage");
@@ -134,9 +145,10 @@ export function registerAllIntelligenceTools(server, client) {
                 findings.push(`Last network event: ${lastType} at ${lastEvent.timestamp ?? lastEvent.date ?? "unknown"}`);
             }
         }
+        // 5. Check HLR bitrate — OCS expects { imsi }, resolve from subscriber record
         const imsiForBitrate = typeof sub.data.imsi === "string" ? sub.data.imsi : null;
         const bitrate = imsiForBitrate
-            ? await safeCall(client, "hlrGetBitrate", { imsi: imsiForBitrate })
+            ? await safeCall(ctx.env, token, "hlrGetBitrate", { imsi: imsiForBitrate })
             : { data: null, error: null };
         if (bitrate.data) {
             const rate = Number(bitrate.data.bitrate ?? bitrate.data.maxBitrate ?? 0);
@@ -147,12 +159,11 @@ export function registerAllIntelligenceTools(server, client) {
                     severity = "info";
             }
         }
-        if (findings.length === 0)
+        // Build report
+        if (findings.length === 0) {
             findings.push("No issues detected — subscriber appears healthy");
-        const activeCount = pkgs.data && Array.isArray(pkgs.data)
-            ? pkgs.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE").length
-            : "unknown";
-        return result([
+        }
+        const report = [
             `# Subscriber Diagnosis: ${iccid}`,
             ``,
             `## Severity: ${severity.toUpperCase()}`,
@@ -160,30 +171,39 @@ export function registerAllIntelligenceTools(server, client) {
             `## Findings`,
             ...findings.map((f, i) => `${i + 1}. ${f}`),
             ``,
-            ...(actions.length > 0 ? [`## Recommended Actions`, ...actions.map((a, i) => `${i + 1}. ${a}`)] : []),
+            ...(actions.length > 0 ? [
+                `## Recommended Actions`,
+                ...actions.map((a, i) => `${i + 1}. ${a}`),
+            ] : []),
             ``,
             `## Raw Status`,
             `- OCS Status: ${status}`,
             `- Balance: ${balance}`,
-            `- Active Packages: ${activeCount}`,
-        ].join("\n"));
-    }));
-    // -------------------------------------------------------------------------
-    // 2. FLEET HEALTH
-    // -------------------------------------------------------------------------
+            `- Active Packages: ${pkgs.data && Array.isArray(pkgs.data) ? pkgs.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE").length : "unknown"}`,
+        ].join("\n");
+        return result(report);
+    });
+    // ---------------------------------------------------------------------------
+    // 2. FLEET HEALTH — single-call fleet overview
+    // ---------------------------------------------------------------------------
     server.registerTool("fleet_health", {
         title: "Fleet Health Dashboard",
-        description: "Aggregates eSIM status counts, low-balance accounts, and provides a fleet-wide health summary in a single call.",
+        description: "Aggregates eSIM status counts, low-balance accounts, and provides a " +
+            "fleet-wide health summary in a single call. Identifies accounts that " +
+            "need attention.",
         inputSchema: {
             accountId: z.number().optional().describe("Filter to a specific account (omit for all)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeIntelHandler(client, async ({ accountId }) => {
+    }, async ({ accountId }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        // Parallel fetch
         const [statusResult, accountsResult] = await Promise.all([
-            safeCall(client, "esimStatusPerAccount", accountId !== undefined ? { accountId } : {}),
-            safeCall(client, "listResellerAccount", {}),
+            safeCall(ctx.env, token, "esimStatusPerAccount", accountId !== undefined ? { accountId } : {}),
+            safeCall(ctx.env, token, "listResellerAccount", {}),
         ]);
         const sections = ["# Fleet Health Dashboard\n"];
+        // eSIM status breakdown
         if (statusResult.data && Array.isArray(statusResult.data)) {
             let totalActive = 0, totalSuspended = 0, totalInventory = 0, totalOther = 0;
             for (const account of statusResult.data) {
@@ -204,9 +224,10 @@ export function registerAllIntelligenceTools(server, client) {
             sections.push(`| **Total** | **${total}** | |`);
             sections.push(`\n**Fleet Utilization: ${utilization}%**`);
             if (totalSuspended > totalActive * 0.1) {
-                sections.push(`\nHigh suspension rate (${totalSuspended} suspended vs ${totalActive} active)`);
+                sections.push(`\n⚠ High suspension rate (${totalSuspended} suspended vs ${totalActive} active)`);
             }
         }
+        // Account balances
         if (accountsResult.data && Array.isArray(accountsResult.data)) {
             const lowBalance = accountsResult.data.filter((a) => Number(a.balance ?? 0) < 10);
             if (lowBalance.length > 0) {
@@ -222,41 +243,54 @@ export function registerAllIntelligenceTools(server, client) {
             sections.push(`- Low balance (< 10): ${lowBalance.length}`);
         }
         return result(sections.join("\n"));
-    }));
-    // -------------------------------------------------------------------------
-    // 3. DETECT USAGE ANOMALIES
-    // -------------------------------------------------------------------------
+    });
+    // ---------------------------------------------------------------------------
+    // 3. USAGE ANOMALY DETECTION
+    // ---------------------------------------------------------------------------
     server.registerTool("detect_usage_anomalies", {
         title: "Detect Usage Anomalies",
-        description: "Analyses recent usage to detect anomalies: spikes, off-hours activity, or consumption exhausting the package before expiry.",
-        inputSchema: { iccid: z.string().describe("The subscriber ICCID to analyse") },
+        description: "Analyzes a subscriber's recent usage patterns over the last 7 days to detect " +
+            "anomalies: sudden spikes, unusual off-hours activity, or consumption rates that " +
+            "would exhaust the package before expiry.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID to analyze"),
+        },
         annotations: { readOnlyHint: true },
-    }, makeIntelHandler(client, async ({ iccid }) => {
+    }, async ({ iccid }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
         const now = new Date();
         const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
         const [usageResult, pkgResult] = await Promise.all([
-            safeCall(client, "subscriberUsageOverPeriod", { subscriber: { iccid }, period: { start: toISODate(weekAgo), end: toISODate(now) } }),
-            safeCall(client, "listSubscriberPrepaidPackages", { iccid }),
+            safeCall(ctx.env, token, "subscriberUsageOverPeriod", {
+                subscriber: { iccid },
+                period: { start: toISODate(weekAgo), end: toISODate(now) },
+            }),
+            safeCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid }),
         ]);
         if (usageResult.error)
             return result(`Failed to fetch usage: ${usageResult.error}`, true);
         const sections = [`# Usage Anomaly Report: ${iccid}\n`];
         const anomalies = [];
         if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length > 0) {
-            const dailyData = usageResult.data.map((entry) => ({
-                date: String(entry.date ?? entry.day ?? "?"),
-                bytes: Number(entry.dataBytes ?? entry.dataVolume ?? entry.totalData ?? 0),
-            }));
+            // Extract daily data volumes
+            const dailyData = [];
+            for (const entry of usageResult.data) {
+                const bytes = Number(entry.dataBytes ?? entry.dataVolume ?? entry.totalData ?? 0);
+                const date = String(entry.date ?? entry.day ?? "?");
+                dailyData.push({ date, bytes });
+            }
             if (dailyData.length >= 2) {
-                const volumes = dailyData.map((d) => d.bytes);
+                // Calculate stats
+                const volumes = dailyData.map(d => d.bytes);
                 const mean = volumes.reduce((a, b) => a + b, 0) / volumes.length;
                 const stdDev = Math.sqrt(volumes.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / volumes.length);
                 sections.push(`## Daily Usage (Last 7 Days)`);
                 sections.push(`| Date | Data | vs Average |`);
                 sections.push(`|------|------|-----------|`);
                 for (const d of dailyData) {
-                    const deviation = mean > 0 ? (((d.bytes - mean) / mean) * 100).toFixed(0) : "0";
-                    const flag = d.bytes > mean + 2 * stdDev ? " SPIKE" : d.bytes > mean + stdDev ? " HIGH" : "";
+                    const deviation = mean > 0 ? ((d.bytes - mean) / mean * 100).toFixed(0) : "0";
+                    const flag = d.bytes > mean + 2 * stdDev ? " SPIKE" :
+                        d.bytes > mean + stdDev ? " HIGH" : "";
                     sections.push(`| ${d.date} | ${formatBytes(d.bytes)} | ${deviation}%${flag} |`);
                     if (d.bytes > mean + 2 * stdDev) {
                         anomalies.push(`Spike on ${d.date}: ${formatBytes(d.bytes)} (${deviation}% above average)`);
@@ -264,6 +298,7 @@ export function registerAllIntelligenceTools(server, client) {
                 }
                 sections.push(`\n**Average daily usage: ${formatBytes(mean)}**`);
                 sections.push(`**Std deviation: ${formatBytes(stdDev)}**`);
+                // Burn rate analysis against active packages
                 if (pkgResult.data && Array.isArray(pkgResult.data)) {
                     const activePkgs = pkgResult.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
                     for (const pkg of activePkgs) {
@@ -279,7 +314,8 @@ export function registerAllIntelligenceTools(server, client) {
                             sections.push(`- Days until expiry: ${daysLeft}`);
                             sections.push(`- At current rate, data exhausts in: ${daysToExhaust.toFixed(1)} days`);
                             if (daysToExhaust < daysLeft * 0.5) {
-                                anomalies.push(`Package "${pkg.name ?? pkg.packageTemplateId}" will run out ${(daysLeft - daysToExhaust).toFixed(0)} days before expiry at current consumption`);
+                                anomalies.push(`Package "${pkg.name ?? pkg.packageTemplateId}" will run out ` +
+                                    `${(daysLeft - daysToExhaust).toFixed(0)} days before expiry at current consumption`);
                             }
                         }
                     }
@@ -297,24 +333,33 @@ export function registerAllIntelligenceTools(server, client) {
             sections.push(`\n## No anomalies detected — usage appears normal.`);
         }
         return result(sections.join("\n"));
-    }));
-    // -------------------------------------------------------------------------
-    // 4. OPTIMIZE PACKAGE
-    // -------------------------------------------------------------------------
+    });
+    // ---------------------------------------------------------------------------
+    // 4. PACKAGE OPTIMIZER — recommend better-fit packages
+    // ---------------------------------------------------------------------------
     server.registerTool("optimize_package", {
         title: "Package Optimization Advisor",
-        description: "Compares a subscriber's usage against their current package and all available templates; recommends better-fit packages.",
-        inputSchema: { iccid: z.string().describe("The subscriber ICCID to optimise") },
+        description: "Compares a subscriber's actual usage against their current package and all " +
+            "available templates. Recommends better-fit packages to reduce waste or prevent " +
+            "overages. Calculates potential savings.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID to optimize"),
+        },
         annotations: { readOnlyHint: true },
-    }, makeIntelHandler(client, async ({ iccid }) => {
+    }, async ({ iccid }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
         const now = new Date();
         const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
         const [usageResult, pkgResult, templatesResult] = await Promise.all([
-            safeCall(client, "subscriberUsageOverPeriod", { subscriber: { iccid }, period: { start: toISODate(weekAgo), end: toISODate(now) } }),
-            safeCall(client, "listSubscriberPrepaidPackages", { iccid }),
-            safeCall(client, "listPrepaidPackageTemplate", {}),
+            safeCall(ctx.env, token, "subscriberUsageOverPeriod", {
+                subscriber: { iccid },
+                period: { start: toISODate(weekAgo), end: toISODate(now) },
+            }),
+            safeCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid }),
+            safeCall(ctx.env, token, "listPrepaidPackageTemplate", {}),
         ]);
         const sections = [`# Package Optimization: ${iccid}\n`];
+        // Calculate average daily usage
         let avgDailyData = 0;
         if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length > 0) {
             const totalData = usageResult.data.reduce((sum, e) => sum + Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0), 0);
@@ -323,6 +368,7 @@ export function registerAllIntelligenceTools(server, client) {
             sections.push(`- Average daily data: ${formatBytes(avgDailyData)}`);
             sections.push(`- Projected monthly: ${formatBytes(avgDailyData * 30)}`);
         }
+        // Current packages
         if (pkgResult.data && Array.isArray(pkgResult.data)) {
             const activePkgs = pkgResult.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
             if (activePkgs.length > 0) {
@@ -339,6 +385,7 @@ export function registerAllIntelligenceTools(server, client) {
                     const expiry = String(pkg.expirationDate ?? pkg.endDate ?? "");
                     if (expiry)
                         sections.push(`- Expires: ${expiry} (${daysUntil(expiry)} days)`);
+                    // Flag waste
                     if (dataLimit > 0 && Number(utilization) < 30) {
                         sections.push(`- LOW UTILIZATION — subscriber is using less than 30% of allowance`);
                     }
@@ -348,16 +395,21 @@ export function registerAllIntelligenceTools(server, client) {
                 }
             }
         }
+        // Recommend templates
         if (templatesResult.data && Array.isArray(templatesResult.data) && avgDailyData > 0) {
+            // Score templates by fit
             const scored = templatesResult.data
                 .map((t) => {
                 const limit = Number(t.dataLimit ?? t.dataAllowance ?? 0);
                 const validity = Number(t.validityDays ?? t.duration ?? 30);
                 const price = Number(t.price ?? t.cost ?? 0);
                 const projectedUsage = avgDailyData * validity;
+                // Fit score: penalize both waste (too much data) and shortage (too little)
                 const ratio = limit > 0 ? projectedUsage / limit : 0;
-                const fitScore = 1 - Math.abs(1 - ratio);
-                return { name: String(t.name ?? t.templateId ?? "?"), limit, validity, price, projectedUsage, fitScore };
+                const fitScore = 1 - Math.abs(1 - ratio); // 1.0 = perfect fit, 0 = terrible
+                const costPerGB = limit > 0 && price > 0 ? price / (limit / (1024 * 1024 * 1024)) : Infinity;
+                const name = String(t.name ?? t.templateId ?? "?");
+                return { name, limit, validity, price, projectedUsage, fitScore, costPerGB, ratio };
             })
                 .filter((t) => t.fitScore > 0.3 && t.limit > 0)
                 .sort((a, b) => b.fitScore - a.fitScore)
@@ -368,7 +420,9 @@ export function registerAllIntelligenceTools(server, client) {
                 sections.push(`|----------|------|----------|-------|-----|--------------|`);
                 for (const t of scored) {
                     const fitLabel = t.fitScore > 0.8 ? "GREAT" : t.fitScore > 0.6 ? "GOOD" : "OK";
-                    sections.push(`| ${t.name} | ${formatBytes(t.limit)} | ${t.validity}d | ${t.price > 0 ? t.price.toFixed(2) : "?"} | ${fitLabel} (${(t.fitScore * 100).toFixed(0)}%) | ${formatBytes(t.projectedUsage)} |`);
+                    sections.push(`| ${t.name} | ${formatBytes(t.limit)} | ` +
+                        `${t.validity}d | ${t.price > 0 ? t.price.toFixed(2) : "?"} | ` +
+                        `${fitLabel} (${(t.fitScore * 100).toFixed(0)}%) | ${formatBytes(t.projectedUsage)} |`);
                 }
             }
         }
@@ -376,26 +430,35 @@ export function registerAllIntelligenceTools(server, client) {
             sections.push(`\n*No usage data available — cannot recommend packages without usage history.*`);
         }
         return result(sections.join("\n"));
-    }));
-    // -------------------------------------------------------------------------
-    // 5. CHURN RISK
-    // -------------------------------------------------------------------------
+    });
+    // ---------------------------------------------------------------------------
+    // 5. CHURN RISK SCORING
+    // ---------------------------------------------------------------------------
     server.registerTool("churn_risk", {
         title: "Churn Risk Assessment",
-        description: "Analyses usage trends, package status, balance, and activity to produce a churn risk score (0-100) with retention recommendations.",
-        inputSchema: { iccid: z.string().describe("The subscriber ICCID to assess") },
+        description: "Analyzes a subscriber's usage trends, package status, balance, and activity " +
+            "to produce a churn risk score (0-100) with contributing factors and retention " +
+            "recommendations.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID to assess"),
+        },
         annotations: { readOnlyHint: true },
-    }, makeIntelHandler(client, async ({ iccid }) => {
+    }, async ({ iccid }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
         const now = new Date();
         const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
         const [subResult, usageResult, pkgResult, activeResult] = await Promise.all([
-            safeCall(client, "getSingleSubscriber", { iccid }),
-            safeCall(client, "subscriberUsageOverPeriod", { subscriber: { iccid }, period: { start: toISODate(weekAgo), end: toISODate(now) } }),
-            safeCall(client, "listSubscriberPrepaidPackages", { iccid }),
-            safeCall(client, "getSubscriberActivePeriod", { iccid }),
+            safeCall(ctx.env, token, "getSingleSubscriber", { iccid }),
+            safeCall(ctx.env, token, "subscriberUsageOverPeriod", {
+                subscriber: { iccid },
+                period: { start: toISODate(weekAgo), end: toISODate(now) },
+            }),
+            safeCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid }),
+            safeCall(ctx.env, token, "getSubscriberActivePeriod", { iccid }),
         ]);
         let riskScore = 0;
         const factors = [];
+        // Factor 1: Usage trend (declining usage = higher risk)
         if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length >= 3) {
             const volumes = usageResult.data.map((e) => Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0));
             const firstHalf = volumes.slice(0, Math.floor(volumes.length / 2));
@@ -405,12 +468,14 @@ export function registerAllIntelligenceTools(server, client) {
             if (avgFirst > 0) {
                 const trend = (avgSecond - avgFirst) / avgFirst;
                 if (trend < -0.5) {
-                    riskScore += 30;
-                    factors.push({ factor: "Declining usage", impact: 30, detail: `Usage dropped ${Math.abs(trend * 100).toFixed(0)}% week-over-week` });
+                    const impact = 30;
+                    riskScore += impact;
+                    factors.push({ factor: "Declining usage", impact, detail: `Usage dropped ${Math.abs(trend * 100).toFixed(0)}% week-over-week` });
                 }
                 else if (trend < -0.2) {
-                    riskScore += 15;
-                    factors.push({ factor: "Moderately declining usage", impact: 15, detail: `Usage dropped ${Math.abs(trend * 100).toFixed(0)}%` });
+                    const impact = 15;
+                    riskScore += impact;
+                    factors.push({ factor: "Moderately declining usage", impact, detail: `Usage dropped ${Math.abs(trend * 100).toFixed(0)}%` });
                 }
             }
         }
@@ -418,6 +483,7 @@ export function registerAllIntelligenceTools(server, client) {
             riskScore += 25;
             factors.push({ factor: "No recent usage", impact: 25, detail: "Zero data activity in last 7 days" });
         }
+        // Factor 2: Package status
         if (pkgResult.data && Array.isArray(pkgResult.data)) {
             const activePkgs = pkgResult.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
             if (activePkgs.length === 0) {
@@ -425,6 +491,7 @@ export function registerAllIntelligenceTools(server, client) {
                 factors.push({ factor: "No active packages", impact: 20, detail: "Subscriber has no active data packages" });
             }
             else {
+                // Check if all packages are near expiry
                 const allExpiringSoon = activePkgs.every((p) => {
                     const expiry = String(p.expirationDate ?? p.endDate ?? "");
                     return expiry && daysUntil(expiry) <= 5;
@@ -433,6 +500,7 @@ export function registerAllIntelligenceTools(server, client) {
                     riskScore += 15;
                     factors.push({ factor: "All packages expiring soon", impact: 15, detail: "No package renewal in sight" });
                 }
+                // Check if no recurring packages
                 const hasRecurring = activePkgs.some((p) => p.recurring === true || p.isRecurring === true);
                 if (!hasRecurring) {
                     riskScore += 10;
@@ -440,6 +508,7 @@ export function registerAllIntelligenceTools(server, client) {
                 }
             }
         }
+        // Factor 3: Balance
         if (subResult.data) {
             const balance = Number(subResult.data.balance ?? 0);
             if (balance <= 0) {
@@ -447,6 +516,7 @@ export function registerAllIntelligenceTools(server, client) {
                 factors.push({ factor: "Zero balance", impact: 15, detail: "Cannot purchase new packages" });
             }
         }
+        // Factor 4: Subscriber age (newer = higher risk)
         if (activeResult.data) {
             const firstUse = String(activeResult.data.firstUseDate ?? activeResult.data.activationDate ?? "");
             if (firstUse) {
@@ -457,14 +527,17 @@ export function registerAllIntelligenceTools(server, client) {
                 }
             }
         }
+        // Cap at 100
         riskScore = Math.min(riskScore, 100);
+        // Risk level
         const level = riskScore >= 70 ? "HIGH" : riskScore >= 40 ? "MEDIUM" : "LOW";
+        // Build report
         const sections = [
             `# Churn Risk Assessment: ${iccid}`,
             ``,
             `## Risk Score: ${riskScore}/100 (${level})`,
             ``,
-            `${"#".repeat(Math.floor(riskScore / 5))}${"-".repeat(20 - Math.floor(riskScore / 5))}`,
+            `${"█".repeat(Math.floor(riskScore / 5))}${"░".repeat(20 - Math.floor(riskScore / 5))}`,
             ``,
         ];
         if (factors.length > 0) {
@@ -476,9 +549,10 @@ export function registerAllIntelligenceTools(server, client) {
                 sections.push(`| ${f.factor} | +${f.impact} | ${f.detail} |`);
             }
         }
+        // Retention recommendations
         sections.push(`\n## Retention Recommendations`);
         if (riskScore >= 70) {
-            sections.push("1. Immediate outreach — contact subscriber with special offer");
+            sections.push("1. **Immediate outreach** — contact subscriber with special offer");
             sections.push("2. Assign a complimentary small data package to re-engage");
             sections.push("3. Set up a recurring package to reduce renewal friction");
         }
@@ -492,56 +566,74 @@ export function registerAllIntelligenceTools(server, client) {
             sections.push("2. Continue monitoring via regular fleet_health checks");
         }
         return result(sections.join("\n"));
-    }));
-    // -------------------------------------------------------------------------
-    // 6. AUDIT NETWORK COVERAGE
-    // -------------------------------------------------------------------------
+    });
+    // ---------------------------------------------------------------------------
+    // 6. NETWORK COVERAGE AUDIT — "am I on the right networks?"
+    // ---------------------------------------------------------------------------
     server.registerTool("audit_network_coverage", {
         title: "Network Coverage Audit",
-        description: "Analyses which networks subscribers connect to vs steering lists; flags expensive/non-preferred network roaming.",
+        description: "Analyzes which networks your subscribers are actually connecting to in a given " +
+            "country or across all countries. Compares against your steering lists to identify " +
+            "mismatches — subscribers roaming on expensive or non-preferred networks. " +
+            "Use this to answer: 'Am I using the right networks in country X?'",
         inputSchema: {
             accountId: z.number().optional().describe("Filter to a specific account"),
             limit: z.number().optional().describe("Max subscribers to sample (default 50)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeIntelHandler(client, async ({ accountId, limit: sampleLimit }) => {
+    }, async ({ accountId, limit: sampleLimit }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
         const maxSample = sampleLimit ?? 50;
-        const subParams = { limit: maxSample, status: "ACTIVE" };
+        // Fetch subscribers and steering lists in parallel
+        const subParams = { status: "ACTIVE" };
         if (accountId !== undefined)
             subParams.accountId = accountId;
-        const [subsResult, steeringResult] = await Promise.all([
-            safeCall(client, "listSubscriber", subParams),
-            safeCall(client, "listSteeringList", {}),
+        const [subsResult, resellerId] = await Promise.all([
+            safeCall(ctx.env, token, "listSubscriber", subParams),
+            getDefaultResellerId(ctx.env, token),
         ]);
+        const steeringResult = await safeCall(ctx.env, token, "listSteeringList", resellerId);
         if (subsResult.error)
             return result(`Failed to fetch subscribers: ${subsResult.error}`, true);
         const sections = [`# Network Coverage Audit\n`];
+        // Build steering list lookup
+        const steeringMap = new Map();
         if (steeringResult.data && Array.isArray(steeringResult.data)) {
-            sections.push(`## Steering Lists: ${steeringResult.data.length} configured`);
+            for (const sl of steeringResult.data) {
+                steeringMap.set(Number(sl.steeringListId ?? sl.id), sl);
+            }
+            sections.push(`## Steering Lists: ${steeringMap.size} configured`);
         }
+        // Sample subscriber locations and networks
         const countryStats = new Map();
         if (subsResult.data && Array.isArray(subsResult.data)) {
-            sections.push(`## Sampling ${subsResult.data.length} active subscribers\n`);
             const subs = subsResult.data.slice(0, maxSample);
+            sections.push(`## Sampling ${subs.length} active subscribers\n`);
+            // Fetch locations in batches of 10
             const batchSize = 10;
             for (let i = 0; i < subs.length; i += batchSize) {
                 const batch = subs.slice(i, i + batchSize);
-                const locations = await Promise.all(batch.map((s) => safeCall(client, "getSubscriberLocation", { iccid: String(s.iccid ?? "") })));
+                const locations = await Promise.all(batch.map((s) => safeCall(ctx.env, token, "getSubscriberLocation", {
+                    iccid: String(s.iccid ?? ""),
+                })));
                 for (let j = 0; j < batch.length; j++) {
                     const loc = locations[j];
                     if (loc.data) {
                         const country = String(loc.data.country ?? loc.data.countryCode ?? "Unknown");
                         const network = String(loc.data.network ?? loc.data.operator ?? loc.data.mccMnc ?? "Unknown");
+                        const iccid = String(batch[j].iccid ?? "");
                         if (!countryStats.has(country)) {
-                            countryStats.set(country, { count: 0, networks: new Map() });
+                            countryStats.set(country, { count: 0, networks: new Map(), subscribers: [] });
                         }
                         const stat = countryStats.get(country);
                         stat.count++;
                         stat.networks.set(network, (stat.networks.get(network) ?? 0) + 1);
+                        stat.subscribers.push(iccid);
                     }
                 }
             }
         }
+        // Report by country
         if (countryStats.size > 0) {
             sections.push(`## Network Distribution by Country`);
             const sorted = [...countryStats.entries()].sort((a, b) => b[1].count - a[1].count);
@@ -562,44 +654,56 @@ export function registerAllIntelligenceTools(server, client) {
             sections.push("No location data available for sampled subscribers.");
         }
         return result(sections.join("\n"));
-    }));
-    // -------------------------------------------------------------------------
-    // 7. MARKETING INTELLIGENCE
-    // -------------------------------------------------------------------------
+    });
+    // ---------------------------------------------------------------------------
+    // 7. MARKETING INTELLIGENCE — "which countries should I target?"
+    // ---------------------------------------------------------------------------
     server.registerTool("marketing_intelligence", {
         title: "Marketing Intelligence Report",
-        description: "Identifies high-growth markets, underserved regions, and revenue concentration. Answers 'where should I target marketing?'",
+        description: "Analyzes your subscriber base to identify high-growth markets, underserved regions, " +
+            "and revenue concentration. Answers: 'Which countries should I target with marketing?' " +
+            "and 'Where are my most valuable subscribers?'",
         inputSchema: {
             accountId: z.number().optional().describe("Filter to a specific account"),
         },
         annotations: { readOnlyHint: true },
-    }, makeIntelHandler(client, async ({ accountId }) => {
-        const params = { limit: 200 };
+    }, async ({ accountId }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        const params = {};
         if (accountId !== undefined)
             params.accountId = accountId;
-        const [subsResult, templatesResult] = await Promise.all([
-            safeCall(client, "listSubscriber", params),
-            safeCall(client, "listPrepaidPackageTemplate", {}),
+        const [subsResult, templatesResult, resellerId] = await Promise.all([
+            safeCall(ctx.env, token, "listSubscriber", params),
+            safeCall(ctx.env, token, "listPrepaidPackageTemplate", {}),
+            getDefaultResellerId(ctx.env, token),
         ]);
+        const zonesResult = await safeCall(ctx.env, token, "listDetailedLocationZone", resellerId);
         const sections = [`# Marketing Intelligence Report\n`];
+        // Subscriber distribution by location
         if (subsResult.data && Array.isArray(subsResult.data)) {
             const total = subsResult.data.length;
             sections.push(`## Fleet Size: ${total} subscribers sampled\n`);
+            // Get locations for a sample
             const sample = subsResult.data.slice(0, 100);
             const countryData = new Map();
             const batchSize = 10;
             for (let i = 0; i < sample.length; i += batchSize) {
                 const batch = sample.slice(i, i + batchSize);
-                const locations = await Promise.all(batch.map((s) => safeCall(client, "getSubscriberLocation", { iccid: String(s.iccid ?? "") })));
+                const locations = await Promise.all(batch.map((s) => safeCall(ctx.env, token, "getSubscriberLocation", {
+                    iccid: String(s.iccid ?? ""),
+                })));
                 for (let j = 0; j < batch.length; j++) {
                     const loc = locations[j];
-                    const subItem = batch[j];
-                    const country = loc.data ? String(loc.data.country ?? loc.data.countryCode ?? "Unknown") : "Unknown";
-                    if (!countryData.has(country))
-                        countryData.set(country, { subscribers: 0, totalBalance: 0 });
+                    const sub = batch[j];
+                    const country = loc.data
+                        ? String(loc.data.country ?? loc.data.countryCode ?? "Unknown")
+                        : "Unknown";
+                    if (!countryData.has(country)) {
+                        countryData.set(country, { subscribers: 0, activePackages: 0, totalBalance: 0 });
+                    }
                     const cd = countryData.get(country);
                     cd.subscribers++;
-                    cd.totalBalance += Number(subItem.balance ?? 0);
+                    cd.totalBalance += Number(sub.balance ?? 0);
                 }
             }
             if (countryData.size > 0) {
@@ -612,29 +716,55 @@ export function registerAllIntelligenceTools(server, client) {
                     const avgBal = (data.totalBalance / data.subscribers).toFixed(2);
                     sections.push(`| ${country} | ${data.subscribers} | ${pct}% | ${avgBal} |`);
                 }
+                // Insights
                 sections.push(`\n## Market Insights`);
+                // Top market
                 const topMarket = sorted[0];
                 if (topMarket) {
-                    sections.push(`- Strongest market: ${topMarket[0]} (${topMarket[1].subscribers} subscribers)`);
+                    sections.push(`- **Strongest market**: ${topMarket[0]} (${topMarket[1].subscribers} subscribers)`);
                     if (topMarket[1].subscribers / sample.length > 0.5) {
                         sections.push(`  Revenue concentration risk — >50% of fleet in one market`);
                     }
                 }
+                // High-value markets (high avg balance)
+                const highValue = sorted
+                    .filter(([, d]) => d.subscribers >= 3)
+                    .sort((a, b) => (b[1].totalBalance / b[1].subscribers) - (a[1].totalBalance / a[1].subscribers))
+                    .slice(0, 3);
+                if (highValue.length > 0) {
+                    sections.push(`\n### High-Value Markets (by avg balance)`);
+                    for (const [country, data] of highValue) {
+                        sections.push(`- **${country}**: avg balance ${(data.totalBalance / data.subscribers).toFixed(2)} (${data.subscribers} subs)`);
+                    }
+                }
+                // Underserved (1-2 subscribers — early traction)
                 const emerging = sorted.filter(([, d]) => d.subscribers >= 1 && d.subscribers <= 3);
                 if (emerging.length > 0) {
-                    sections.push(`\n### Emerging Markets (1-3 subscribers)`);
+                    sections.push(`\n### Emerging Markets (early traction, 1-3 subscribers)`);
+                    sections.push(`These markets show initial demand — consider targeted campaigns:`);
                     for (const [country, data] of emerging) {
                         sections.push(`- ${country}: ${data.subscribers} subscriber(s)`);
                     }
                 }
             }
         }
+        // Available coverage vs actual usage
+        if (zonesResult.data && Array.isArray(zonesResult.data)) {
+            sections.push(`\n## Coverage Catalog`);
+            sections.push(`- Location zones available: ${zonesResult.data.length}`);
+        }
         if (templatesResult.data && Array.isArray(templatesResult.data)) {
-            sections.push(`\n## Package Templates Available: ${templatesResult.data.length}`);
-            const prices = templatesResult.data.map((t) => Number(t.price ?? t.cost ?? 0)).filter((p) => p > 0);
+            sections.push(`- Package templates available: ${templatesResult.data.length}`);
+            // Price analysis
+            const prices = templatesResult.data
+                .map((t) => Number(t.price ?? t.cost ?? 0))
+                .filter((p) => p > 0);
             if (prices.length > 0) {
                 const avgPrice = prices.reduce((a, b) => a + b, 0) / prices.length;
-                sections.push(`- Pricing range: ${Math.min(...prices).toFixed(2)} – ${Math.max(...prices).toFixed(2)} (avg ${avgPrice.toFixed(2)})`);
+                const minPrice = Math.min(...prices);
+                const maxPrice = Math.max(...prices);
+                sections.push(`\n### Pricing Range`);
+                sections.push(`- Min: ${minPrice.toFixed(2)} | Avg: ${avgPrice.toFixed(2)} | Max: ${maxPrice.toFixed(2)}`);
             }
         }
         sections.push(`\n## Recommended Actions`);
@@ -642,26 +772,29 @@ export function registerAllIntelligenceTools(server, client) {
         sections.push(`2. Run \`high_cost_subscribers\` to identify margin pressure`);
         sections.push(`3. Consider creating regional package templates for emerging markets`);
         return result(sections.join("\n"));
-    }));
-    // -------------------------------------------------------------------------
-    // 8. HIGH COST SUBSCRIBERS
-    // -------------------------------------------------------------------------
+    });
+    // ---------------------------------------------------------------------------
+    // 8. HIGH COST SUBSCRIBERS — "who's costing me money?"
+    // ---------------------------------------------------------------------------
     server.registerTool("high_cost_subscribers", {
         title: "High Cost Subscriber Report",
-        description: "Identifies subscribers with disproportionately high data consumption relative to package value.",
+        description: "Identifies subscribers with disproportionately high data consumption relative " +
+            "to their package value. Finds subscribers burning through data at rates that " +
+            "erode margins. Answers: 'Which subscribers are costing me money?'",
         inputSchema: {
             accountId: z.number().optional().describe("Filter to a specific account"),
-            limit: z.number().optional().describe("Max subscribers to analyse (default 100)"),
+            limit: z.number().optional().describe("Max subscribers to analyze (default 100)"),
             thresholdPct: z.number().optional().describe("Usage % threshold to flag (default 80)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeIntelHandler(client, async ({ accountId, limit: maxLimit, thresholdPct }) => {
+    }, async ({ accountId, limit: maxLimit, thresholdPct }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
         const sampleSize = maxLimit ?? 100;
         const threshold = thresholdPct ?? 80;
-        const subParams = { limit: sampleSize, status: "ACTIVE" };
+        const subParams = { status: "ACTIVE" };
         if (accountId !== undefined)
             subParams.accountId = accountId;
-        const subsResult = await safeCall(client, "listSubscriber", subParams);
+        const subsResult = await safeCall(ctx.env, token, "listSubscriber", subParams);
         if (subsResult.error)
             return result(`Failed to fetch subscribers: ${subsResult.error}`, true);
         if (!subsResult.data || !Array.isArray(subsResult.data))
@@ -670,6 +803,7 @@ export function registerAllIntelligenceTools(server, client) {
         const now = new Date();
         const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
         const highCostSubs = [];
+        // Analyze in batches
         const batchSize = 5;
         const subs = subsResult.data.slice(0, sampleSize);
         for (let i = 0; i < subs.length; i += batchSize) {
@@ -677,15 +811,20 @@ export function registerAllIntelligenceTools(server, client) {
             await Promise.all(batch.map(async (sub) => {
                 const iccid = String(sub.iccid ?? "");
                 const [usage, pkgs, loc] = await Promise.all([
-                    safeCall(client, "subscriberUsageOverPeriod", { subscriber: { iccid }, period: { start: toISODate(weekAgo), end: toISODate(now) } }),
-                    safeCall(client, "listSubscriberPrepaidPackages", { iccid }),
-                    safeCall(client, "getSubscriberLocation", { iccid }),
+                    safeCall(ctx.env, token, "subscriberUsageOverPeriod", {
+                        subscriber: { iccid },
+                        period: { start: toISODate(weekAgo), end: toISODate(now) },
+                    }),
+                    safeCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid }),
+                    safeCall(ctx.env, token, "getSubscriberLocation", { iccid }),
                 ]);
+                // Calculate daily avg
                 let dailyAvgBytes = 0;
                 if (usage.data && Array.isArray(usage.data) && usage.data.length > 0) {
                     const totalBytes = usage.data.reduce((sum, e) => sum + Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0), 0);
                     dailyAvgBytes = totalBytes / usage.data.length;
                 }
+                // Get active package info
                 if (pkgs.data && Array.isArray(pkgs.data)) {
                     const activePkg = pkgs.data.find((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
                     if (activePkg && dailyAvgBytes > 0) {
@@ -695,17 +834,31 @@ export function registerAllIntelligenceTools(server, client) {
                         const utilizationPct = dataLimit > 0 ? (dataUsed / dataLimit) * 100 : 0;
                         const remaining = dataLimit - dataUsed;
                         const daysToExhaust = dailyAvgBytes > 0 ? remaining / dailyAvgBytes : Infinity;
-                        const costPerGB = price > 0 && dataUsed > 0 ? price / (dataUsed / (1024 * 1024 * 1024)) : 0;
-                        const country = loc.data ? String(loc.data.country ?? loc.data.countryCode ?? "?") : "?";
+                        const costPerGB = price > 0 && dataUsed > 0
+                            ? price / (dataUsed / (1024 * 1024 * 1024))
+                            : 0;
+                        const country = loc.data
+                            ? String(loc.data.country ?? loc.data.countryCode ?? "?")
+                            : "?";
                         if (utilizationPct >= threshold || daysToExhaust < 3) {
-                            highCostSubs.push({ iccid, dailyAvgBytes, packageDataLimit: dataLimit, packagePrice: price, utilizationPct, costPerGB, daysToExhaust, country });
+                            highCostSubs.push({
+                                iccid,
+                                dailyAvgBytes,
+                                packageDataLimit: dataLimit,
+                                packagePrice: price,
+                                utilizationPct,
+                                costPerGB,
+                                daysToExhaust,
+                                country,
+                            });
                         }
                     }
                 }
             }));
         }
+        // Sort by utilization (highest first)
         highCostSubs.sort((a, b) => b.utilizationPct - a.utilizationPct);
-        sections.push(`Analysed ${subs.length} active subscribers (threshold: ${threshold}% usage)\n`);
+        sections.push(`Analyzed ${subs.length} active subscribers (threshold: ${threshold}% usage)\n`);
         if (highCostSubs.length === 0) {
             sections.push(`No subscribers above ${threshold}% package utilization. Fleet margins look healthy.`);
         }
@@ -716,17 +869,109 @@ export function registerAllIntelligenceTools(server, client) {
             let totalDailyBytes = 0;
             for (const s of highCostSubs) {
                 totalDailyBytes += s.dailyAvgBytes;
-                sections.push(`| ${s.iccid.slice(-8)}... | ${s.country} | ${formatBytes(s.dailyAvgBytes)} | ${s.utilizationPct.toFixed(0)}% | ${s.daysToExhaust === Infinity ? "inf" : s.daysToExhaust.toFixed(1)} | ${s.costPerGB > 0 ? s.costPerGB.toFixed(2) : "?"} |`);
+                sections.push(`| ${s.iccid.slice(-8)}... | ${s.country} | ${formatBytes(s.dailyAvgBytes)} | ` +
+                    `${s.utilizationPct.toFixed(0)}% | ${s.daysToExhaust === Infinity ? "inf" : s.daysToExhaust.toFixed(1)} | ` +
+                    `${s.costPerGB > 0 ? s.costPerGB.toFixed(2) : "?"} |`);
             }
             sections.push(`\n## Summary`);
             sections.push(`- High-cost subscribers: ${highCostSubs.length} / ${subs.length} (${((highCostSubs.length / subs.length) * 100).toFixed(1)}%)`);
             sections.push(`- Combined daily data burn: ${formatBytes(totalDailyBytes)}`);
+            // Country breakdown
+            const byCountry = new Map();
+            for (const s of highCostSubs) {
+                byCountry.set(s.country, (byCountry.get(s.country) ?? 0) + 1);
+            }
+            const countrySorted = [...byCountry.entries()].sort((a, b) => b[1] - a[1]);
+            if (countrySorted.length > 0) {
+                sections.push(`\n### By Country`);
+                for (const [country, count] of countrySorted) {
+                    sections.push(`- ${country}: ${count} high-cost subscriber(s)`);
+                }
+            }
             sections.push(`\n## Recommended Actions`);
             sections.push(`1. Review tariff rates for top countries via \`get_tariff\``);
             sections.push(`2. Consider throttling heavy users via \`hlr_set_bitrate\``);
             sections.push(`3. Run \`optimize_package\` on flagged ICCIDs to find better-fit plans`);
+            sections.push(`4. Negotiate better wholesale rates for high-volume countries`);
         }
         return result(sections.join("\n"));
-    }));
+    });
+    // ---------------------------------------------------------------------------
+    // 9. DETECT COUNTRY ENTRY — cheap MCC-based location change detection
+    // ---------------------------------------------------------------------------
+    server.registerTool("detect_country_entry", {
+        title: "Detect Country Entry",
+        description: "Detects when a subscriber has entered a new country by reading " +
+            "networkInfo.lastMcc from getSingleSubscriber (one cheap OCS call — " +
+            "avoids the per-call cost of getSubscriberLocationByCellId). Resolves " +
+            "MCC → ISO 3166-1 alpha-2 and optionally diffs against a caller-supplied " +
+            "expectedCountry to return countryChanged. Designed for downstream " +
+            "country-entry upsell workflows (e.g. mango.talk SMS/push offers). " +
+            "COST NOTE: This tool makes exactly one OCS call per invocation. " +
+            "Consumers running polling crons MUST enforce their own rate floor — " +
+            "this layer provides no throttle.",
+        inputSchema: {
+            subscriber: z
+                .union([
+                z.object({ subscriberId: z.number() }).describe("Internal subscriber ID"),
+                z.object({ imsi: z.string() }).describe("IMSI"),
+                z.object({ iccid: z.string() }).describe("ICCID"),
+                z.object({ msisdn: z.string() }).describe("MSISDN / phone number"),
+                z.object({ multiImsi: z.string() }).describe("Multi-IMSI identifier"),
+                z.object({ activationCode: z.string() }).describe("eSIM activation code"),
+            ])
+                .describe("Subscriber identifier (use exactly one field)"),
+            expectedCountry: z
+                .string()
+                .length(2)
+                .transform((code) => code.toUpperCase())
+                .optional()
+                .describe("Caller\u2019s last-known ISO 3166-1 alpha-2 country for this subscriber " +
+                "(e.g. \"RU\"). When provided, countryChanged is included in the response."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ subscriber, expectedCountry }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        // getSingleSubscriber accepts any of subscriberId | imsi | iccid | msisdn |
+        // multiImsi | activationCode — pass the discriminated union value directly.
+        const sub = await safeCall(ctx.env, token, "getSingleSubscriber", subscriber);
+        if (sub.error)
+            return result(`Failed to fetch subscriber: ${sub.error}`, true);
+        if (!sub.data)
+            return result("Subscriber not found", true);
+        const subscriberId = sub.data.subscriberId ??
+            sub.data.id ??
+            ("subscriberId" in subscriber
+                ? subscriber.subscriberId
+                : undefined);
+        const networkInfo = sub.data.networkInfo;
+        if (networkInfo === null || networkInfo === undefined || typeof networkInfo !== "object") {
+            return result(JSON.stringify({ status: "no_location_data", subscriberId: subscriberId ?? null }));
+        }
+        const lastMcc = networkInfo.lastMcc != null ? Number(networkInfo.lastMcc) : null;
+        const lastMnc = networkInfo.lastMnc != null ? Number(networkInfo.lastMnc) : null;
+        const lastSeenAtUtc = networkInfo.time != null ? String(networkInfo.time) : null;
+        if (lastMcc === null || isNaN(lastMcc)) {
+            return result(JSON.stringify({ status: "no_location_data", subscriberId: subscriberId ?? null }));
+        }
+        const currentCountry = mccToIso(lastMcc);
+        const mccUnresolved = currentCountry === null;
+        const response = {
+            subscriberId: subscriberId ?? null,
+            currentCountry,
+            currentMcc: lastMcc,
+            currentMnc: lastMnc,
+            lastSeenAtUtc,
+            ...(mccUnresolved ? { mccUnresolved: true } : {}),
+        };
+        if (expectedCountry !== undefined) {
+            response.expectedCountry = expectedCountry;
+            // null = cannot determine (MCC unresolved); true/false = definitive diff
+            response.countryChanged = currentCountry !== null
+                ? currentCountry !== expectedCountry
+                : null;
+        }
+        return result(JSON.stringify(response, null, 2));
+    });
 }
 //# sourceMappingURL=intelligence.js.map