@carrierllc/mcp 0.0.1 → 0.2.0

package/dist/tools.js

@@ -0,0 +1,1295 @@
+/**
+ * Carrier MCP — OCS tool registrations (43 tools).
+ *
+ * All 43 OCS v1 methods are exposed as MCP tools. Each is wrapped with:
+ *   - Scope enforcement (read / write / admin)
+ *   - Dry-run short-circuit for destructive tools (no OCS call)
+ *   - Sentry error capture
+ *   - Audit hook into Analytics Engine
+ *   - Per-user token resolution via getUserToken(sub)
+ *
+ * Scope assignments live in TOOL_SCOPES below; must match packages/ocs-spec/ocs-methods.json.
+ *
+ * PR #10 schema fixes applied:
+ *   Fix #1:  getSimProviderStatus  — ICCID → simId lookup → bare integer
+ *   Fix #2:  hlrGetBitrate         — ICCID → IMSI lookup → { imsi }
+ *   Fix #3:  hlrSetBitrate         — ICCID → IMSI + bitrate → limit rename → { imsi, limit }
+ *   Fix #4:  subscriberUsageOverPeriod       — { subscriber: { iccid }, period: { start, end } }
+ *   Fix #5:  subscriberNetworkEventsOverPeriod — same nested shape
+ *   Fix #6:  modifySubscriberStatus          — { subscriber, newStatus }
+ *   Fix #7:  modifySubscriberBalance         — { subscriber, amount } or { subscriber, setBalance }
+ *   Fix #8:  changeSimStatus                 — ICCID → simId + simStatus → newStatus
+ *   Fix #9:  modifySubscriberContactInfo     — firstName+lastName → name, email→mail, phone→phone
+ *   Fix #10: setSubscriberTrafficRestrictions — typed booleans, not JSON string
+ *   Fix #11: sendMtSms                       — ICCID→IMSI, message→text, sender→senderId
+ *   Fix #12: listSponsor                     — bare integer (resellerId)
+ *   Fix #13: listSteeringList                — bare integer (resellerId)
+ *   Fix #14: getCustomerTariff               — bare integer + response key listTariffRule
+ *   Fix #15: listDetailedLocationZone        — bare integer (resellerId)
+ *   Fix #16: modifySubscriberSteeringList    — { subscriber, steeringListId }
+ */
+import { z } from "zod";
+import * as Sentry from "@sentry/cloudflare";
+import { OcsClient, OcsApiError } from "./client.js";
+import { checkCallQuota, recordUsage, UPGRADE_URL } from "./billing.js";
+// Scope metadata per tool — all 43 tools declared here.
+// Must stay in sync with ocs-methods.json from packages/ocs-spec.
+export const TOOL_SCOPES = {
+    // --- read ---
+    list_reseller_accounts: "read",
+    get_reseller_info: "read",
+    esim_status_per_account: "read",
+    list_sponsors: "read",
+    list_steering_lists: "read",
+    get_subscriber: "read",
+    list_subscribers: "read",
+    get_sim_provider_status: "read",
+    get_subscriber_location: "read",
+    hlr_get_bitrate: "read",
+    list_subscriber_packages: "read",
+    list_package_templates: "read",
+    list_location_zones: "read",
+    list_detailed_location_zones: "read",
+    list_destination_prefixes: "read",
+    subscriber_usage: "read",
+    subscriber_network_events: "read",
+    subscriber_active_period: "read",
+    get_tariff: "read",
+    list_network_profiles: "read",
+    // --- write ---
+    modify_subscriber_balance: "write",
+    modify_subscriber_status: "write",
+    modify_subscriber_contact_info: "write",
+    set_subscriber_traffic_restrictions: "write",
+    modify_subscriber_steering_list: "write",
+    move_subscriber_range_to_account: "write",
+    hlr_set_bitrate: "write",
+    assign_package: "write",
+    assign_recurring_package: "write",
+    modify_package_limits: "write",
+    modify_package_expiry: "write",
+    modify_package_status: "write",
+    stop_resume_recurring_package: "write",
+    create_package_template: "write",
+    create_location_zone: "write",
+    // --- admin ---
+    modify_account_balance: "admin", // corrected per ocs-spec PR #6
+    change_sim_status: "admin",
+    delete_subscriber_package: "admin",
+    clean_all_packages: "admin",
+    modify_template_core: "admin",
+    modify_template_recurring: "admin",
+    modify_template_throttling: "admin",
+    send_sms: "admin",
+};
+export const DESTRUCTIVE_TOOLS = new Set([
+    "modify_account_balance",
+    "modify_subscriber_balance",
+    "modify_subscriber_status",
+    "change_sim_status",
+    "modify_subscriber_contact_info",
+    "set_subscriber_traffic_restrictions",
+    "modify_subscriber_steering_list",
+    "move_subscriber_range_to_account",
+    "hlr_set_bitrate",
+    "assign_package",
+    "assign_recurring_package",
+    "modify_package_limits",
+    "modify_package_expiry",
+    "modify_package_status",
+    "stop_resume_recurring_package",
+    "delete_subscriber_package",
+    "clean_all_packages",
+    "modify_template_core",
+    "modify_template_recurring",
+    "modify_template_throttling",
+    "create_package_template",
+    "create_location_zone",
+    "send_sms",
+    // v1.1 backlog — same dry_run contract as v1 write/admin tools (tools-backlog.ts)
+    "affect_subscriber_phone_number",
+    "modify_subscriber_mobile_plan",
+    "modify_subscriber_package_active_period",
+    "modify_subscriber_voip_plan",
+    "push_steering_to_subscriber",
+    "reset_subscriber_gz_counter",
+]);
+/**
+ * Wraps a tool handler with scope enforcement, dry-run short-circuit,
+ * Sentry capture, and audit logging.
+ */
+export function wrapHandler(toolName, ocsMethod, requiredScope, ctx, handler) {
+    return async (args) => {
+        const start = Date.now();
+        const isDryRun = args.dry_run === true;
+        // Scope enforcement
+        if (!ctx.props.scope.includes(requiredScope)) {
+            ctx.audit({
+                tool_name: toolName,
+                ocs_method: ocsMethod,
+                status: "scope_denied",
+                dry_run: false,
+                duration_ms: 0,
+            });
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Scope denied: tool '${toolName}' requires '${requiredScope}' scope. Your token has: [${ctx.props.scope.join(", ")}].`,
+                    },
+                ],
+            };
+        }
+        // Billing quota check (Phase 7 — v1.1)
+        // Enterprise is unlimited; free/pro are gate-checked against KV counter.
+        const quota = await checkCallQuota(ctx.env, ctx.props.sub, ctx.props.tier);
+        if (!quota.allowed) {
+            ctx.audit({
+                tool_name: toolName,
+                ocs_method: ocsMethod,
+                status: "quota_exceeded",
+                dry_run: isDryRun,
+                duration_ms: 0,
+            });
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Quota exceeded: your ${quota.tier} plan allows ${quota.tier === "free" ? "1,000" : "50,000"} tool calls/month.`,
+                            `Resets ${quota.resetAt}.`,
+                            `Upgrade at ${UPGRADE_URL}`,
+                        ].join(" "),
+                    },
+                ],
+            };
+        }
+        // Dry-run short-circuit for destructive tools
+        if (isDryRun && DESTRUCTIVE_TOOLS.has(toolName)) {
+            ctx.audit({
+                tool_name: toolName,
+                ocs_method: ocsMethod,
+                status: "dry_run",
+                dry_run: true,
+                duration_ms: 0,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `[dry_run=true] Would execute '${toolName}' (OCS method '${ocsMethod}') with args: ${JSON.stringify(args)}. No changes made.`,
+                    },
+                ],
+            };
+        }
+        let result;
+        try {
+            const token = await ctx.getUserToken(ctx.props.sub);
+            result = await handler(args, token);
+        }
+        catch (err) {
+            try {
+                Sentry.captureException(err, {
+                    tags: {
+                        tool: toolName,
+                        feature: "mcp",
+                        reseller_id: String(ctx.props.reseller_id),
+                    },
+                });
+            }
+            catch {
+                // Sentry may not be initialised in tests — swallow.
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            const ocsCode = err instanceof OcsApiError ? err.code : undefined;
+            ctx.audit({
+                tool_name: toolName,
+                ocs_method: ocsMethod,
+                status: "error",
+                dry_run: isDryRun,
+                duration_ms: Date.now() - start,
+                ...(ocsCode !== undefined ? { ocs_status_code: ocsCode } : {}),
+            });
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: ${message}` }],
+            };
+        }
+        ctx.audit({
+            tool_name: toolName,
+            ocs_method: ocsMethod,
+            status: result.isError ? "error" : "ok",
+            dry_run: isDryRun,
+            duration_ms: Date.now() - start,
+        });
+        // Record usage on successful (non-error, non-dry-run) calls.
+        // Fire-and-forget — never blocks the response.
+        if (!result.isError && !isDryRun) {
+            recordUsage(ctx.env, ctx.props.sub, ctx.props.tier);
+        }
+        return result;
+    };
+}
+// ---------------------------------------------------------------------------
+// OCS call helper — accepts explicit token (no module-level singleton).
+// Fix: params broadened to accept bare scalar for methods that expect it
+// (listSponsor, listSteeringList, getCustomerTariff, listDetailedLocationZone,
+//  getSimProviderStatus).
+// ---------------------------------------------------------------------------
+async function ocsCall(env, token, method, params = {}) {
+    const client = new OcsClient(env.CARRIER_OCS_BASE_URL, token);
+    const result = await client.call(method, params);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+}
+export async function resolveSubscriberByIccid(env, token, iccid, cache) {
+    const hit = cache.get(iccid);
+    if (hit)
+        return hit;
+    const client = new OcsClient(env.CARRIER_OCS_BASE_URL, token);
+    const record = await client.call("getSingleSubscriber", { iccid });
+    cache.set(iccid, record);
+    return record;
+}
+// ---------------------------------------------------------------------------
+// Fetch the token owner's reseller ID via getResellerInfo.
+// Used for bare-integer OCS methods: listSponsor, listSteeringList,
+// getCustomerTariff, listDetailedLocationZone.
+// Fix #12, #13, #14, #15.
+// ---------------------------------------------------------------------------
+export async function getDefaultResellerId(env, token) {
+    const client = new OcsClient(env.CARRIER_OCS_BASE_URL, token);
+    const info = await client.call("getResellerInfo", {});
+    const id = info?.id;
+    if (typeof id !== "number") {
+        throw new Error("Could not determine resellerId from getResellerInfo");
+    }
+    return id;
+}
+// Shorthand: build the destructive-tool annotation + dry_run schema field
+const DRY_RUN_FIELD = {
+    dry_run: z
+        .boolean()
+        .optional()
+        .describe("If true, do not call OCS — return the would-be request for confirmation"),
+};
+export function registerAllTools(server, ctx) {
+    // =========================================================================
+    // 1. RESELLER TOOLS
+    // =========================================================================
+    server.registerTool("list_reseller_accounts", {
+        title: "List Reseller Accounts",
+        description: "Use this to enumerate all accounts (sub-resellers or customer accounts) under a reseller. " +
+            "Returns each account's name, ID, current balance, package-only flag, and account type. " +
+            "Params: `resellerId` (integer, optional — omit to list accounts under the token owner's reseller). " +
+            "Returns: array of account records, each containing `accountId`, `name`, `balance`, `type`. " +
+            "Do NOT use this to fetch a single subscriber's details — use `get_subscriber` instead. " +
+            "Do NOT use this to check eSIM activation counts — use `esim_status_per_account` for that.",
+        inputSchema: {
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Filter to a specific reseller by ID (omit for token owner's reseller)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_reseller_accounts", "listResellerAccount", TOOL_SCOPES["list_reseller_accounts"], ctx, async ({ resellerId }, token) => {
+        const params = {};
+        if (resellerId !== undefined)
+            params.resellerId = resellerId;
+        return ocsCall(ctx.env, token, "listResellerAccount", params);
+    }));
+    server.registerTool("modify_account_balance", {
+        title: "Modify Account Balance",
+        description: "Use this to adjust or set the monetary balance on a reseller account. " +
+            "'adapt' mode adds (positive amount) or subtracts (negative amount) from the current balance; " +
+            "'set' mode replaces the balance with the exact amount. Every change is logged as a transaction. " +
+            "Params: `accountId` (integer account ID from `list_reseller_accounts`), `amount` (number), " +
+            "`mode` ('adapt' | 'set'). " +
+            "Returns: updated account balance record with the transaction ID. " +
+            "Do NOT use this to modify a subscriber's personal balance — use `modify_subscriber_balance` instead. " +
+            "Always call `list_reseller_accounts` first to confirm the target accountId before executing.",
+        inputSchema: {
+            accountId: z.number().describe("The account ID to modify"),
+            amount: z.number().describe("Amount to add (adapt) or set to (set)"),
+            mode: z
+                .enum(["adapt", "set"])
+                .describe("'adapt' adds/subtracts, 'set' replaces the balance"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_account_balance", "modifyAccountBalance", TOOL_SCOPES["modify_account_balance"], ctx, async ({ accountId, amount, mode }, token) => {
+        const params = { accountId };
+        if (mode === "adapt")
+            params.adaptBalance = amount;
+        else
+            params.setBalance = amount;
+        return ocsCall(ctx.env, token, "modifyAccountBalance", params);
+    }));
+    server.registerTool("get_reseller_info", {
+        title: "Get Reseller Info",
+        description: "Use this to retrieve full details for a reseller: main info, traffic configuration, " +
+            "charging info, contact info, and active pricing plans. " +
+            "Params: `resellerId` (integer, optional — omit to return the token owner's reseller). " +
+            "Returns: reseller object with `id`, `name`, `balance`, `pricingPlan`, `contactInfo`, and more. " +
+            "Do NOT use this to list all accounts under a reseller — use `list_reseller_accounts` for that.",
+        inputSchema: {
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit for token owner)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("get_reseller_info", "getResellerInfo", TOOL_SCOPES["get_reseller_info"], ctx, async ({ resellerId }, token) => {
+        const params = {};
+        if (resellerId !== undefined)
+            params.resellerId = resellerId;
+        return ocsCall(ctx.env, token, "getResellerInfo", params);
+    }));
+    server.registerTool("esim_status_per_account", {
+        title: "eSIM Status Per Account",
+        description: "Use this to get eSIM status counts broken down by account: active, suspended, inventory " +
+            "(not yet activated), and other states. Good for fleet health dashboards and capacity planning. " +
+            "Params: `accountId` (integer, optional — omit for all accounts under the reseller). " +
+            "Returns: array of per-account objects with `accountId`, `active`, `suspended`, `inventory`, `other`. " +
+            "Do NOT use this to check a single subscriber's status — use `get_subscriber` for that. " +
+            "Do NOT use this for billing or balance checks — use `list_reseller_accounts` for balances.",
+        inputSchema: {
+            accountId: z
+                .number()
+                .optional()
+                .describe("Filter to a specific account"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("esim_status_per_account", "esimStatusPerAccount", TOOL_SCOPES["esim_status_per_account"], ctx, async ({ accountId }, token) => {
+        const params = {};
+        if (accountId !== undefined)
+            params.accountId = accountId;
+        return ocsCall(ctx.env, token, "esimStatusPerAccount", params);
+    }));
+    // Fix #12: OCS expects bare integer (resellerId), not {}
+    server.registerTool("list_sponsors", {
+        title: "List Sponsors",
+        description: "Use this to list all sponsor networks (eSIM sponsor carriers) available to this reseller. " +
+            "A sponsor defines which physical network infrastructure backs a given eSIM profile. " +
+            "Params: `resellerId` (integer, optional — omit to use the token owner's reseller). " +
+            "Returns: array of sponsor records with `sponsorId`, `name`, and coverage metadata. " +
+            "Do NOT use this to list steering lists or network profiles — those are separate concepts. " +
+            "Use `list_steering_lists` to see operator preference configurations.",
+        inputSchema: {
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit to use token owner's reseller)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_sponsors", "listSponsor", TOOL_SCOPES["list_sponsors"], ctx, async ({ resellerId }, token) => {
+        const id = resellerId ?? (await getDefaultResellerId(ctx.env, token));
+        return ocsCall(ctx.env, token, "listSponsor", id);
+    }));
+    // Fix #13: OCS expects bare integer (resellerId), not {}
+    server.registerTool("list_steering_lists", {
+        title: "List Steering Lists",
+        description: "Use this to retrieve all network steering lists configured for this reseller. " +
+            "A steering list is a named configuration of excluded and priority mobile operators that " +
+            "controls which networks an eSIM prefers to roam onto — the primary mechanism for network " +
+            "quality optimisation and cost control. Call this before `modify_subscriber_steering_list` " +
+            "to obtain valid steering list IDs. " +
+            "Params: `resellerId` (integer, optional — omit to use the token owner's reseller). " +
+            "Returns: array of steering list records with `steeringListId`, `name`, and configured operators. " +
+            "Do NOT use this to assign a steering list to a subscriber — use `modify_subscriber_steering_list`. " +
+            "Do NOT use this to push a steering change to a device — use `push_steering_to_subscriber` after assignment.",
+        inputSchema: {
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit to use token owner's reseller)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_steering_lists", "listSteeringList", TOOL_SCOPES["list_steering_lists"], ctx, async ({ resellerId }, token) => {
+        const id = resellerId ?? (await getDefaultResellerId(ctx.env, token));
+        return ocsCall(ctx.env, token, "listSteeringList", id);
+    }));
+    // =========================================================================
+    // 2. SUBSCRIBER TOOLS
+    // =========================================================================
+    server.registerTool("get_subscriber", {
+        title: "Get Single Subscriber",
+        description: "Use this as the primary lookup for a single subscriber by ICCID or MSISDN. " +
+            "Returns the complete subscriber record: status, balance, assigned account, contact info, " +
+            "IMSI, simId, steering list, active pricing plan, and traffic restriction flags. " +
+            "Params: `iccid` (20-digit ICC identifier, optional) OR `msisdn` (E.164 phone number, optional) — " +
+            "provide at least one. " +
+            "Returns: full subscriber object. Key fields: `status` (ACTIVE/SUSPENDED/TERMINATED), " +
+            "`balance`, `imsi`, `simId`, `steeringListId`. " +
+            "Do NOT use this for bulk lookups — use `list_subscribers` with filters for that.",
+        inputSchema: {
+            iccid: z.string().optional().describe("The ICCID of the subscriber"),
+            msisdn: z
+                .string()
+                .optional()
+                .describe("The MSISDN (phone number) of the subscriber"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("get_subscriber", "getSingleSubscriber", TOOL_SCOPES["get_subscriber"], ctx, async ({ iccid, msisdn }, token) => {
+        const params = {};
+        if (iccid)
+            params.iccid = iccid;
+        if (msisdn)
+            params.msisdn = msisdn;
+        return ocsCall(ctx.env, token, "getSingleSubscriber", params);
+    }));
+    server.registerTool("list_subscribers", {
+        title: "List Subscribers",
+        description: "Use this to list subscribers with optional filters and pagination. Good for fleet enumeration, " +
+            "bulk status checks, and finding subscribers by account or status. " +
+            "Params: `accountId` (integer, filter by account), `status` (string, e.g. 'ACTIVE'/'SUSPENDED'), " +
+            "`offset` (integer, for pagination — default 0), `limit` (integer, max results — always set to avoid " +
+            "unbounded fetches; recommended max 100 per call). " +
+            "Returns: array of subscriber summary records with ICCID, status, and account. " +
+            "Do NOT use this to fetch full details for a specific subscriber — use `get_subscriber` for that.",
+        inputSchema: {
+            accountId: z.number().optional().describe("Filter by account ID"),
+            status: z.string().optional().describe("Filter by status"),
+            offset: z.number().optional().describe("Pagination offset"),
+            limit: z.number().optional().describe("Max results to return"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_subscribers", "listSubscriber", TOOL_SCOPES["list_subscribers"], ctx, async (args, token) => {
+        // OCS listSubscriber does not accept `limit` — strip it before forwarding.
+        // We keep `limit` in the inputSchema as a UX hint so callers can express intent.
+        const params = {};
+        if (args.accountId !== undefined)
+            params.accountId = args.accountId;
+        if (args.status)
+            params.status = args.status;
+        if (args.offset !== undefined)
+            params.offset = args.offset;
+        const client = new OcsClient(ctx.env.CARRIER_OCS_BASE_URL, token);
+        const raw = await client.call("listSubscriber", params);
+        const limit = args.limit;
+        const payload = Array.isArray(raw) && typeof limit === "number" && limit >= 0
+            ? raw.slice(0, limit)
+            : raw;
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        };
+    }));
+    // Fix #7: OCS expects { subscriber, amount } or { subscriber, setBalance } not { iccid, adaptBalance|setBalance }
+    server.registerTool("modify_subscriber_balance", {
+        title: "Modify Subscriber Balance",
+        description: "Use this to adjust or set the monetary balance for an individual subscriber. " +
+            "'adapt' mode adds (positive) or subtracts (negative) from the current balance; " +
+            "'set' mode replaces the balance with the exact amount provided. " +
+            "Params: `iccid` (subscriber identifier), `amount` (number), `mode` ('adapt' | 'set'). " +
+            "Returns: updated subscriber balance. " +
+            "Do NOT use this to modify an account-level balance — use `modify_account_balance` for that. " +
+            "Always call `get_subscriber` first to capture the current balance before adjusting.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            amount: z.number().describe("Amount to add (adapt) or set to (set)"),
+            mode: z
+                .enum(["adapt", "set"])
+                .describe("'adapt' adds/subtracts, 'set' replaces"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_subscriber_balance", "modifySubscriberBalance", TOOL_SCOPES["modify_subscriber_balance"], ctx, async ({ iccid, amount, mode }, token) => {
+        const params = { subscriber: iccid };
+        if (mode === "adapt")
+            params.amount = amount;
+        else
+            params.setBalance = amount;
+        return ocsCall(ctx.env, token, "modifySubscriberBalance", params);
+    }));
+    // Fix #6: OCS expects { subscriber, newStatus } not { iccid, status }
+    server.registerTool("modify_subscriber_status", {
+        title: "Modify Subscriber Status",
+        description: "Use this to change the OCS lifecycle status of a subscriber. " +
+            "Common transitions: ACTIVE → SUSPENDED (pause without losing packages), " +
+            "SUSPENDED → ACTIVE (reactivate), ACTIVE/SUSPENDED → TERMINATED (irreversible). " +
+            "WARNING: TERMINATED status is permanent — the subscriber record cannot be reactivated. " +
+            "Params: `iccid` (subscriber identifier), `status` (new status string, e.g. 'ACTIVE', " +
+            "'SUSPENDED', 'TERMINATED'). " +
+            "Returns: updated subscriber record with the new status. " +
+            "Do NOT use this to disable the SIM card at the network level — use `change_sim_status` for that. " +
+            "Always call `get_subscriber` first to confirm current status before modifying.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            status: z.string().describe("New status value"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_subscriber_status", "modifySubscriberStatus", TOOL_SCOPES["modify_subscriber_status"], ctx, async ({ iccid, status }, token) => ocsCall(ctx.env, token, "modifySubscriberStatus", {
+        subscriber: iccid,
+        newStatus: status,
+    })));
+    // Fix #8: OCS expects { simId, newStatus } not { iccid, simStatus }.
+    // Resolve ICCID → simId via getSingleSubscriber, then send { simId, newStatus }.
+    server.registerTool("change_sim_status", {
+        title: "Change SIM Status",
+        description: "Use this to change the physical SIM/eSIM card status at the SIM provider level, " +
+            "independent of the OCS subscriber lifecycle status. " +
+            "Statuses: ENABLED (normal operation), DISABLED (blocked at network level, subscriber cannot connect), " +
+            "DELETED (irrecoverably removes the SIM profile — use only to decommission). " +
+            "WARNING: DELETED is irreversible. Always use `dry_run=true` first. " +
+            "Internally resolves ICCID → numeric simId via a getSingleSubscriber call before forwarding to OCS. " +
+            "Params: `iccid` (subscriber identifier), `simStatus` ('ENABLED' | 'DISABLED' | 'DELETED'). " +
+            "Returns: updated SIM record with new status. " +
+            "Do NOT use this to change the subscriber's OCS lifecycle status — use `modify_subscriber_status`. " +
+            "Do NOT confuse DISABLED (reversible) with DELETED (irreversible).",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            simStatus: z.string().describe("New SIM status (e.g. ENABLED, DISABLED, DELETED)"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("change_sim_status", "changeSimStatus", TOOL_SCOPES["change_sim_status"], ctx, async ({ iccid, simStatus }, token) => {
+        const cache = new Map();
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
+        const simId = Number(sub.simId ?? sub.sim_id ?? sub.id);
+        if (simId === undefined) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: Could not resolve simId for ICCID ${iccid}` }],
+            };
+        }
+        return ocsCall(ctx.env, token, "changeSimStatus", {
+            simId: Number(simId),
+            newStatus: simStatus,
+        });
+    }));
+    // Fix #1: OCS expects bare Long (simId integer) not { iccid }.
+    // Resolve ICCID → simId via getSingleSubscriber, then send bare integer.
+    server.registerTool("get_sim_provider_status", {
+        title: "Get SIM Provider Status",
+        description: "Use this to check the physical SIM/eSIM card status at the SIM provider level " +
+            "(ENABLED, DISABLED, DELETED) — distinct from the OCS subscriber status. " +
+            "Useful when `get_subscriber` shows ACTIVE but connectivity is broken; the SIM may be " +
+            "DISABLED at the provider level. Internally resolves ICCID → numeric simId. " +
+            "Params: `iccid` (subscriber identifier). " +
+            "Returns: provider status object with `simStatus`, `activationDate`, `lastStatusChange`. " +
+            "Do NOT use this to change the SIM status — use `change_sim_status` for that.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("get_sim_provider_status", "getSimProviderStatus", TOOL_SCOPES["get_sim_provider_status"], ctx, async ({ iccid }, token) => {
+        const cache = new Map();
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
+        const simId = Number(sub.simId ?? sub.sim_id ?? sub.id);
+        if (simId === undefined) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: Could not resolve simId for ICCID ${iccid}` }],
+            };
+        }
+        return ocsCall(ctx.env, token, "getSimProviderStatus", Number(simId));
+    }));
+    server.registerTool("get_subscriber_location", {
+        title: "Get Subscriber Location",
+        description: "Use this to get the last known roaming location of a subscriber (country and operator). " +
+            "Returned on a best-effort basis — location is updated when the device re-registers on the network. " +
+            "Params: `iccid` (subscriber identifier). " +
+            "Returns: object with `country`, `countryCode`, `network`, `operator`, and `timestamp` of last update. " +
+            "Do NOT use this for cell-tower-level precision — use `get_subscriber_location_by_cell_id` instead. " +
+            "Do NOT use this for bulk fleet location analysis — use `audit_network_coverage` for that.",
+        inputSchema: { iccid: z.string().describe("The subscriber ICCID") },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("get_subscriber_location", "getSubscriberLocation", TOOL_SCOPES["get_subscriber_location"], ctx, async ({ iccid }, token) => ocsCall(ctx.env, token, "getSubscriberLocation", { iccid })));
+    // Fix #9: OCS expects { subscriber, name, company, phone, mail }
+    // not { iccid, firstName, lastName, email, phoneNumber }
+    server.registerTool("modify_subscriber_contact_info", {
+        title: "Modify Subscriber Contact Info",
+        description: "Use this to update the contact details stored on a subscriber record in OCS. " +
+            "Only the fields you provide are updated — omitted fields are left unchanged. " +
+            "Params: `iccid` (subscriber identifier), `firstName` (optional), `lastName` (optional), " +
+            "`company` (optional), `email` (optional), `phoneNumber` (optional). " +
+            "Returns: updated subscriber contact record. " +
+            "Do NOT use this to change subscriber status, balance, or traffic flags — those have dedicated tools.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            firstName: z.string().optional().describe("First name"),
+            lastName: z.string().optional().describe("Last name"),
+            company: z.string().optional().describe("Company name"),
+            email: z.string().optional().describe("Email address"),
+            phoneNumber: z.string().optional().describe("Phone number"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_subscriber_contact_info", "modifySubscriberContactInfo", TOOL_SCOPES["modify_subscriber_contact_info"], ctx, async ({ iccid, firstName, lastName, company, email, phoneNumber }, token) => {
+        const params = { subscriber: iccid };
+        const nameParts = [firstName, lastName].filter(Boolean);
+        if (nameParts.length > 0)
+            params.name = nameParts.join(" ");
+        if (company !== undefined)
+            params.company = company;
+        if (phoneNumber !== undefined)
+            params.phone = phoneNumber;
+        if (email !== undefined)
+            params.mail = email;
+        return ocsCall(ctx.env, token, "modifySubscriberContactInfo", params);
+    }));
+    // Fix #10: OCS expects { subscriber, mtcAllowed, smsMoAllowed, dataAllowed, mocAllowed }
+    // Drop JSON-string antipattern; use typed booleans directly.
+    server.registerTool("set_subscriber_traffic_restrictions", {
+        title: "Set Traffic Restrictions",
+        description: "Use this to enable or disable individual traffic types for a subscriber: mobile data, " +
+            "voice calls (mobile-originated and mobile-terminated), and SMS. Omit any flag to leave " +
+            "it unchanged. Changes take effect immediately at the OCS level. " +
+            "Params: `iccid` (subscriber identifier), `dataAllowed` (boolean, controls data traffic), " +
+            "`mocAllowed` (boolean, controls outbound calls), `mtcAllowed` (boolean, controls inbound calls), " +
+            "`smsMoAllowed` (boolean, controls outbound SMS). " +
+            "Returns: updated traffic restriction record for the subscriber. " +
+            "Do NOT use this to throttle bandwidth — use `hlr_set_bitrate` for speed limiting. " +
+            "Do NOT use this to suspend the subscriber entirely — use `modify_subscriber_status` (SUSPENDED) instead.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            mtcAllowed: z.boolean().optional().describe("Allow mobile-terminated calls"),
+            smsMoAllowed: z.boolean().optional().describe("Allow SMS mobile-originated"),
+            dataAllowed: z.boolean().optional().describe("Allow data traffic"),
+            mocAllowed: z.boolean().optional().describe("Allow mobile-originated calls"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("set_subscriber_traffic_restrictions", "setSubscriberTrafficRestrictions", TOOL_SCOPES["set_subscriber_traffic_restrictions"], ctx, async ({ iccid, mtcAllowed, smsMoAllowed, dataAllowed, mocAllowed }, token) => {
+        const params = { subscriber: iccid };
+        if (mtcAllowed !== undefined)
+            params.mtcAllowed = mtcAllowed;
+        if (smsMoAllowed !== undefined)
+            params.smsMoAllowed = smsMoAllowed;
+        if (dataAllowed !== undefined)
+            params.dataAllowed = dataAllowed;
+        if (mocAllowed !== undefined)
+            params.mocAllowed = mocAllowed;
+        return ocsCall(ctx.env, token, "setSubscriberTrafficRestrictions", params);
+    }));
+    // Fix #16: OCS expects { subscriber, steeringListId } not { iccid, steeringListId }
+    server.registerTool("modify_subscriber_steering_list", {
+        title: "Modify Subscriber Steering List",
+        description: "Use this to assign or remove a network steering list on a specific subscriber, controlling " +
+            "which mobile operators the subscriber's eSIM prefers to connect to. Steering lists are " +
+            "managed separately — call `list_steering_lists` to get valid IDs. " +
+            "This operates at the SUBSCRIBER level only. After assigning, call `push_steering_to_subscriber` " +
+            "to push the change to the physical device immediately; without that call the device continues " +
+            "using the old operator preference list until next re-registration. " +
+            "Params: `iccid` (subscriber identifier), `steeringListId` (integer from `list_steering_lists`, " +
+            "or null/0 to remove the current steering list). " +
+            "Returns: updated subscriber record confirming the new steeringListId. " +
+            "Do NOT use this for account-level steering (no MCP tool yet — gap G-03, awaiting eSIMVault input).",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            steeringListId: z.number().describe("The steering list ID to assign"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_subscriber_steering_list", "modifySubscriberSteeringList", TOOL_SCOPES["modify_subscriber_steering_list"], ctx, async ({ iccid, steeringListId }, token) => ocsCall(ctx.env, token, "modifySubscriberSteeringList", {
+        subscriber: iccid,
+        steeringListId,
+    })));
+    server.registerTool("move_subscriber_range_to_account", {
+        title: "Move Subscribers to Account",
+        description: "Use this to move a contiguous ICCID range of subscribers to a different account. " +
+            "Useful for bulk subscriber migrations between accounts or during account restructuring. " +
+            "Params: `iccidFrom` (start ICCID of range, inclusive), `iccidTo` (end ICCID of range, inclusive), " +
+            "`accountId` (target account ID from `list_reseller_accounts`). " +
+            "Returns: OCS confirmation of the range move with affected subscriber count. " +
+            "Do NOT use this for a single subscriber move — provide identical iccidFrom and iccidTo. " +
+            "Always call `list_subscribers` on the range first to verify the correct subscribers are included.",
+        inputSchema: {
+            iccidFrom: z.string().describe("Start ICCID of range"),
+            iccidTo: z.string().describe("End ICCID of range"),
+            accountId: z.number().describe("Target account ID"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("move_subscriber_range_to_account", "moveSubscriberRangeToAccount", TOOL_SCOPES["move_subscriber_range_to_account"], ctx, async ({ iccidFrom, iccidTo, accountId }, token) => ocsCall(ctx.env, token, "moveSubscriberRangeToAccount", {
+        iccidFrom,
+        iccidTo,
+        accountId,
+    })));
+    // Fix #3: OCS expects { imsi, limit } not { iccid, bitrate }.
+    // Resolve ICCID → IMSI via getSingleSubscriber; rename bitrate → limit.
+    server.registerTool("hlr_set_bitrate", {
+        title: "Set HLR Bitrate",
+        description: "Use this to set a hard bandwidth cap for a subscriber at the HLR (Home Location Register) level. " +
+            "This is a network-level throttle applied regardless of package allowance — use it to enforce " +
+            "fair-use speed limits or to throttle heavy users without suspending service. " +
+            "Common values: 256000 (256 kbps throttle), 1000000 (1 Mbps), 0 (remove limit). " +
+            "Internally resolves ICCID → IMSI via a getSingleSubscriber lookup. " +
+            "Params: `iccid` (subscriber identifier), `bitrate` (integer, bits-per-second; 0 removes the limit). " +
+            "Returns: HLR confirmation with the applied bitrate. " +
+            "Do NOT use this to block data entirely — use `set_subscriber_traffic_restrictions` with `dataAllowed=false`. " +
+            "Do NOT use this to change throttling thresholds on a package template — use `modify_template_throttling`.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            bitrate: z.number().describe("Max bitrate in bps"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("hlr_set_bitrate", "hlrSetBitrate", TOOL_SCOPES["hlr_set_bitrate"], ctx, async ({ iccid, bitrate }, token) => {
+        const cache = new Map();
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
+        const imsi = sub.imsi;
+        if (typeof imsi !== "string" || imsi.length === 0) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: Could not resolve IMSI for ICCID ${iccid}` }],
+            };
+        }
+        return ocsCall(ctx.env, token, "hlrSetBitrate", { imsi, limit: bitrate });
+    }));
+    // Fix #2: OCS expects { imsi } not { iccid }.
+    // Resolve ICCID → IMSI via getSingleSubscriber.
+    server.registerTool("hlr_get_bitrate", {
+        title: "Get HLR Bitrate",
+        description: "Use this to read the current HLR-level bandwidth cap applied to a subscriber. " +
+            "A non-zero value means the subscriber is throttled to that speed regardless of package allowance. " +
+            "A zero or null response means no HLR-level cap is in effect. " +
+            "Internally resolves ICCID → IMSI via a getSingleSubscriber lookup. " +
+            "Params: `iccid` (subscriber identifier). " +
+            "Returns: object with `bitrate` (integer, bits-per-second) or null if no limit is set. " +
+            "Do NOT use this to check package data allowance limits — use `list_subscriber_packages` for that.",
+        inputSchema: { iccid: z.string().describe("The subscriber ICCID") },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("hlr_get_bitrate", "hlrGetBitrate", TOOL_SCOPES["hlr_get_bitrate"], ctx, async ({ iccid }, token) => {
+        const cache = new Map();
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
+        const imsi = sub.imsi;
+        if (typeof imsi !== "string" || imsi.length === 0) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: Could not resolve IMSI for ICCID ${iccid}` }],
+            };
+        }
+        return ocsCall(ctx.env, token, "hlrGetBitrate", { imsi });
+    }));
+    // =========================================================================
+    // 3. PACKAGE TOOLS
+    // =========================================================================
+    server.registerTool("list_subscriber_packages", {
+        title: "List Subscriber Packages",
+        description: "Use this to retrieve all prepaid packages currently assigned to a subscriber. " +
+            "Returns each package's allowance (data/voice/SMS), consumed usage, expiry date, status, and packageId. " +
+            "Always call this before any package modification tool (`modify_package_limits`, " +
+            "`modify_package_expiry`, `modify_package_status`, `delete_subscriber_package`) to confirm " +
+            "the correct packageId and current state. " +
+            "Params: `iccid` (subscriber identifier). " +
+            "Returns: array of package records with `packageId`, `name`, `status`, `dataLimit`, `dataUsed`, " +
+            "`expirationDate`, `recurring` flag. " +
+            "Do NOT use this to browse the product catalog — use `list_package_templates` for that.",
+        inputSchema: { iccid: z.string().describe("The subscriber ICCID") },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_subscriber_packages", "listSubscriberPrepaidPackages", TOOL_SCOPES["list_subscriber_packages"], ctx, async ({ iccid }, token) => ocsCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid })));
+    server.registerTool("assign_package", {
+        title: "Assign Package to Subscriber",
+        description: "Use this to assign a one-time prepaid data/voice package to a subscriber from an existing template. " +
+            "The package is active immediately (or at first usage, depending on template settings). " +
+            "Params: `iccid` (subscriber identifier), `packageTemplateId` (integer from `list_package_templates`). " +
+            "Returns: created package record with `packageId`, `startDate`, `endDate`, and allowances. " +
+            "Do NOT use this for packages that should auto-renew — use `assign_recurring_package` instead. " +
+            "Do NOT use this to provision a new subscriber end-to-end — consider `provision_esim_wizard` " +
+            "for a guided flow with dry-run preview.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            packageTemplateId: z
+                .number()
+                .describe("The package template ID to assign"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("assign_package", "affectPackageToSubscriber", TOOL_SCOPES["assign_package"], ctx, async ({ iccid, packageTemplateId }, token) => {
+        // Fix #17: OCS affectPackageToSubscriber expects integer subscriberId, not ICCID string.
+        // Resolve ICCID → numeric id via getSingleSubscriber before calling OCS.
+        const cache = new Map();
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
+        const subscriberId = sub.id ?? sub.subscriberId;
+        if (subscriberId === undefined) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: Could not resolve subscriberId for ICCID ${iccid}` }],
+            };
+        }
+        return ocsCall(ctx.env, token, "affectPackageToSubscriber", {
+            subscriber: Number(subscriberId),
+            packageTemplateId,
+        });
+    }));
+    server.registerTool("assign_recurring_package", {
+        title: "Assign Recurring Package",
+        description: "Use this to assign an auto-renewing prepaid package to a subscriber. The package renews " +
+            "automatically based on the template's periodicity settings, reducing churn from manual renewal. " +
+            "Params: `iccid` (subscriber identifier), `packageTemplateId` (integer from `list_package_templates` " +
+            "— must be a template configured with recurring/periodicity settings). " +
+            "Returns: created recurring package record with `packageId` and renewal schedule. " +
+            "Do NOT use this for one-time packages — use `assign_package` instead. " +
+            "To pause or cancel auto-renewal without deleting the package, use `stop_resume_recurring_package`.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            packageTemplateId: z.number().describe("The package template ID"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("assign_recurring_package", "affectRecurringPackageToSubscriber", TOOL_SCOPES["assign_recurring_package"], ctx, async ({ iccid, packageTemplateId }, token) => {
+        // Fix #18: OCS affectRecurringPackageToSubscriber expects integer subscriberId, not ICCID string.
+        // Resolve ICCID → numeric id via getSingleSubscriber before calling OCS.
+        const cache = new Map();
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
+        const subscriberId = sub.id ?? sub.subscriberId;
+        if (subscriberId === undefined) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: Could not resolve subscriberId for ICCID ${iccid}` }],
+            };
+        }
+        return ocsCall(ctx.env, token, "affectRecurringPackageToSubscriber", {
+            subscriber: Number(subscriberId),
+            packageTemplateId,
+        });
+    }));
+    server.registerTool("modify_package_limits", {
+        title: "Modify Package Limits",
+        description: "Use this to change the data, voice, or SMS allowance ceilings on an already-assigned subscriber package. " +
+            "Useful for mid-cycle top-ups or corrections without assigning a new package. " +
+            "Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`), " +
+            "`limits` (JSON string with the limit fields to change, e.g. {\"dataLimit\": 5368709120}). " +
+            "Returns: updated package record with new limits. " +
+            "Do NOT use this to change the package template (affecting future subscribers) — use `modify_template_core`. " +
+            "Do NOT use this to change expiry — use `modify_package_expiry`. " +
+            "Always call `list_subscriber_packages` first to confirm the correct packageId.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            packageId: z.number().describe("The active package ID"),
+            limits: z.string().describe("New limits as JSON string"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_package_limits", "modifySubscriberPrepaidPackageLimits", TOOL_SCOPES["modify_package_limits"], ctx, async ({ iccid, packageId, limits }, token) => ocsCall(ctx.env, token, "modifySubscriberPrepaidPackageLimits", {
+        iccid,
+        packageId,
+        ...JSON.parse(limits),
+    })));
+    server.registerTool("modify_package_expiry", {
+        title: "Modify Package Expiry Date",
+        description: "Use this to extend or shorten the expiry date of an active prepaid package on a subscriber. " +
+            "Useful when a subscriber's trip is longer than expected or for promotional extensions. " +
+            "Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`), " +
+            "`expirationDate` (ISO 8601 date string, e.g. '2026-06-01' or '2026-06-01T23:59:59'). " +
+            "Returns: updated package record with the new expiry date. " +
+            "Do NOT use this to change when a package becomes active — use `modify_subscriber_package_active_period`. " +
+            "Do NOT use this to change data allowances — use `modify_package_limits`.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            packageId: z.number().describe("The active package ID"),
+            expirationDate: z
+                .string()
+                .describe("New expiry date (ISO 8601 format)"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_package_expiry", "modifySubscriberPrepaidPackageExpDate", TOOL_SCOPES["modify_package_expiry"], ctx, async ({ iccid, packageId, expirationDate }, token) => ocsCall(ctx.env, token, "modifySubscriberPrepaidPackageExpDate", {
+        iccid,
+        packageId,
+        expirationDate,
+    })));
+    server.registerTool("modify_package_status", {
+        title: "Modify Package Status",
+        description: "Use this to activate or deactivate a specific prepaid package on a subscriber without " +
+            "removing it. A deactivated package retains its allowances and can be reactivated later. " +
+            "Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`), " +
+            "`status` (new package status string, e.g. 'ACTIVE', 'INACTIVE'). " +
+            "Returns: updated package record with the new status. " +
+            "Do NOT use this to delete a package — use `delete_subscriber_package` for permanent removal. " +
+            "Do NOT use this to change the subscriber's overall account status — use `modify_subscriber_status`.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            packageId: z.number().describe("The active package ID"),
+            status: z.string().describe("New package status"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_package_status", "modifySubscriberPrepaidPackageStatus", TOOL_SCOPES["modify_package_status"], ctx, async ({ iccid, packageId, status }, token) => ocsCall(ctx.env, token, "modifySubscriberPrepaidPackageStatus", {
+        iccid,
+        packageId,
+        status,
+    })));
+    server.registerTool("stop_resume_recurring_package", {
+        title: "Stop/Resume Recurring Package",
+        description: "Use this to pause or restart the auto-renewal cycle of a recurring package without removing it. " +
+            "'stop' halts future renewals (subscriber keeps current period until expiry); " +
+            "'resume' re-enables auto-renewal from the next renewal date. " +
+            "Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`), " +
+            "`action` ('stop' | 'resume'). " +
+            "Returns: updated recurring package record with new renewal state. " +
+            "Do NOT use this to permanently delete a recurring package — use `delete_subscriber_package`. " +
+            "Do NOT confuse this with `modify_package_status` (which activates/deactivates a package for usage).",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            packageId: z.number().describe("The recurring package ID"),
+            action: z
+                .enum(["stop", "resume"])
+                .describe("Whether to stop or resume"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("stop_resume_recurring_package", "stopResumeSubsRecurringPackage", TOOL_SCOPES["stop_resume_recurring_package"], ctx, async ({ iccid, packageId, action }, token) => ocsCall(ctx.env, token, "stopResumeSubsRecurringPackage", {
+        iccid,
+        packageId,
+        action,
+    })));
+    server.registerTool("delete_subscriber_package", {
+        title: "Delete Subscriber Package",
+        description: "Use this to permanently remove a single prepaid package from a subscriber. " +
+            "This is irreversible — the package record and any unused allowance are deleted. " +
+            "Always call `list_subscriber_packages` first to confirm the correct packageId and snapshot " +
+            "the current state. Use `dry_run=true` on the first call. " +
+            "Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`). " +
+            "Returns: OCS confirmation of deletion. " +
+            "Do NOT use this to remove ALL packages at once — use `clean_all_packages` for that (requires separate confirm). " +
+            "Do NOT use this to pause a package — use `modify_package_status` to deactivate it instead.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            packageId: z.number().describe("The package ID to delete"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("delete_subscriber_package", "deleteSubscriberPackage", TOOL_SCOPES["delete_subscriber_package"], ctx, async ({ iccid, packageId }, token) => ocsCall(ctx.env, token, "deleteSubscriberPackage", { iccid, packageId })));
+    server.registerTool("clean_all_packages", {
+        title: "Clean All Subscriber Packages",
+        description: "DANGEROUS: Removes ALL prepaid packages from a subscriber in a single irreversible operation. " +
+            "There is no undo. Typical use: resetting a subscriber to zero before re-provisioning a new package series. " +
+            "REQUIRED workflow: (1) call `list_subscriber_packages` to snapshot what will be deleted; " +
+            "(2) call this tool with `dry_run=true` to preview; (3) get explicit user confirmation; " +
+            "(4) call again with `dry_run=false`. " +
+            "Params: `iccid` (subscriber identifier), `dry_run` (boolean — MUST be true on first call). " +
+            "Returns: list of packages that were (or would be) deleted. " +
+            "Do NOT use this to remove a single package — use `delete_subscriber_package` instead.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("clean_all_packages", "cleanSubscriberAllPackages", TOOL_SCOPES["clean_all_packages"], ctx, async ({ iccid }, token) => ocsCall(ctx.env, token, "cleanSubscriberAllPackages", { iccid })));
+    // =========================================================================
+    // 4. PACKAGE TEMPLATE TOOLS
+    // =========================================================================
+    server.registerTool("list_package_templates", {
+        title: "List Package Templates",
+        description: "Use this to browse the product catalog of prepaid package templates available for assignment. " +
+            "Returns each template's name, data/voice/SMS limits, pricing, validity period, location zone, " +
+            "and recurring configuration. Call this before `assign_package` or `assign_recurring_package` " +
+            "to obtain valid `packageTemplateId` values. " +
+            "Params: `accountId` (integer, optional — filter templates visible to a specific account). " +
+            "Returns: array of template records with `templateId`, `name`, `dataLimit`, `price`, " +
+            "`validityDays`, `locationZoneId`, `recurring`. " +
+            "Do NOT use this to list packages assigned to a specific subscriber — use `list_subscriber_packages`.",
+        inputSchema: {
+            accountId: z
+                .number()
+                .optional()
+                .describe("Filter templates by account ID"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_package_templates", "listPrepaidPackageTemplate", TOOL_SCOPES["list_package_templates"], ctx, async ({ accountId }, token) => {
+        const params = {};
+        if (accountId !== undefined)
+            params.accountId = accountId;
+        return ocsCall(ctx.env, token, "listPrepaidPackageTemplate", params);
+    }));
+    server.registerTool("create_package_template", {
+        title: "Create Package Template",
+        description: "Use this to create a new prepaid package template in the product catalog. Templates define " +
+            "allowances, pricing, location zones, validity, and throttling thresholds that are reused each " +
+            "time the template is assigned to a subscriber. " +
+            "Params: `template` (full template configuration as a JSON string — fields include `name`, " +
+            "`dataLimit` in bytes, `price`, `validityDays`, `locationZoneId`, `recurring`, `throttlingActive`). " +
+            "Returns: created template record with the new `templateId`. " +
+            "Do NOT use this to modify an existing template — use `modify_template_core`. " +
+            "After creation, call `list_package_templates` to confirm the template is visible.",
+        inputSchema: {
+            template: z
+                .string()
+                .describe("Full template configuration as JSON string"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("create_package_template", "createPrepaidPackageTemplate", TOOL_SCOPES["create_package_template"], ctx, async ({ template }, token) => ocsCall(ctx.env, token, "createPrepaidPackageTemplate", JSON.parse(template))));
+    server.registerTool("modify_template_core", {
+        title: "Modify Template Core Settings",
+        description: "Use this to change the core fields of an existing package template: name, data/voice/SMS limits, " +
+            "pricing, validity period, and location zone. Changes affect future package assignments from this " +
+            "template but do NOT retroactively change packages already assigned to subscribers. " +
+            "Params: `templateId` (integer from `list_package_templates`), `changes` (JSON string with fields " +
+            "to modify, e.g. {\"name\": \"Europe 5GB\", \"dataLimit\": 5368709120}). " +
+            "Returns: updated template record. " +
+            "Do NOT use this to modify throttling thresholds — use `modify_template_throttling`. " +
+            "Do NOT use this to modify recurring/renewal settings — use `modify_template_recurring`.",
+        inputSchema: {
+            templateId: z.number().describe("The template ID"),
+            changes: z.string().describe("Core fields to modify as JSON string"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_template_core", "modifyPPTCore", TOOL_SCOPES["modify_template_core"], ctx, async ({ templateId, changes }, token) => ocsCall(ctx.env, token, "modifyPPTCore", {
+        templateId,
+        ...JSON.parse(changes),
+    })));
+    server.registerTool("modify_template_recurring", {
+        title: "Modify Template Recurring Settings",
+        description: "Use this to change the auto-renewal configuration of a package template: periodicity " +
+            "(daily/weekly/monthly), occurrence count, and renewal trigger conditions. Changes affect " +
+            "future assignments and existing recurring packages assigned from this template. " +
+            "Params: `templateId` (integer from `list_package_templates`), `changes` (JSON string with " +
+            "recurring fields, e.g. {\"periodicity\": \"monthly\", \"occurrences\": 12}). " +
+            "Returns: updated template record with new recurring settings. " +
+            "Do NOT use this to stop an individual subscriber's recurring renewal — use `stop_resume_recurring_package`. " +
+            "Do NOT use this to change core template fields like data limits — use `modify_template_core`.",
+        inputSchema: {
+            templateId: z.number().describe("The template ID"),
+            changes: z
+                .string()
+                .describe("Recurring fields to modify as JSON string"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_template_recurring", "modifyPPTRecurring", TOOL_SCOPES["modify_template_recurring"], ctx, async ({ templateId, changes }, token) => ocsCall(ctx.env, token, "modifyPPTRecurring", {
+        templateId,
+        ...JSON.parse(changes),
+    })));
+    server.registerTool("modify_template_throttling", {
+        title: "Modify Template Throttling",
+        description: "Use this to change the bandwidth throttling thresholds on a package template. " +
+            "WARNING: changes apply immediately to ALL existing subscriber packages created from this template, " +
+            "not just future ones. Setting a lower threshold will NOT retroactively throttle subscribers " +
+            "already below the new threshold (the system does not re-check existing usage). " +
+            "Params: `templateId` (integer), `changes` (JSON string with throttling fields, e.g. " +
+            "{\"throttlingActive\": true, \"firstThresholdPercent\": 80, \"firstThresholdLimitKbps\": 1024, " +
+            "\"errorAction\": \"continue_unthrottled\"}). " +
+            "Returns: updated template record with new throttling configuration. " +
+            "Do NOT use this to throttle a single subscriber — use `hlr_set_bitrate` instead. " +
+            "Do NOT use this to change core package limits — use `modify_template_core`.",
+        inputSchema: {
+            templateId: z.number().describe("The template ID"),
+            changes: z
+                .string()
+                .describe("Throttling fields to modify as JSON string"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("modify_template_throttling", "modifyPPTThrottling", TOOL_SCOPES["modify_template_throttling"], ctx, async ({ templateId, changes }, token) => ocsCall(ctx.env, token, "modifyPPTThrottling", {
+        templateId,
+        ...JSON.parse(changes),
+    })));
+    server.registerTool("list_location_zones", {
+        title: "List Location Zone Elements",
+        description: "Use this to list countries and networks within a specific location zone. " +
+            "WARNING: this method has a known Jackson deserialization bug in the upstream OCS API that " +
+            "may return malformed responses. Prefer `list_detailed_location_zones` for reliable results. " +
+            "Params: `locationZoneId` (integer, optional — filter to a specific zone). " +
+            "Returns: array of zone element records with country and operator entries. " +
+            "Do NOT use this for reliable zone data — use `list_detailed_location_zones` instead. " +
+            "Do NOT use this to create zones — use `create_location_zone`.",
+        inputSchema: {
+            locationZoneId: z.number().optional().describe("Filter by zone ID"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_location_zones", "listLocationZoneElement", TOOL_SCOPES["list_location_zones"], ctx, async ({ locationZoneId }, token) => {
+        const params = {};
+        if (locationZoneId !== undefined)
+            params.locationZoneId = locationZoneId;
+        return ocsCall(ctx.env, token, "listLocationZoneElement", params);
+    }));
+    // Fix #15: OCS expects bare integer (resellerId), not {}
+    server.registerTool("list_detailed_location_zones", {
+        title: "List Detailed Location Zones",
+        description: "Use this as the preferred way to list location zones with full detail: included countries, " +
+            "operator networks, zone IDs, and names. This is the working alternative to `list_location_zones` " +
+            "which has a known upstream deserialization bug. Use `locationZoneId` values from this response " +
+            "when creating or editing package templates. " +
+            "Params: `resellerId` (integer, optional — omit to use the token owner's reseller). " +
+            "Returns: array of zone objects each containing `locationZoneId`, `name`, `countries`, and `operators`. " +
+            "Do NOT use `list_location_zones` when you need reliable data — always use this tool instead.",
+        inputSchema: {
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit to use token owner's reseller)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_detailed_location_zones", "listDetailedLocationZone", TOOL_SCOPES["list_detailed_location_zones"], ctx, async ({ resellerId }, token) => {
+        const id = resellerId ?? (await getDefaultResellerId(ctx.env, token));
+        return ocsCall(ctx.env, token, "listDetailedLocationZone", id);
+    }));
+    server.registerTool("list_destination_prefixes", {
+        title: "List Destination List Prefixes",
+        description: "Use this to list the phone number prefixes (country dialling codes) within a specific " +
+            "named destination list. Destination lists control which countries a subscriber may call on " +
+            "voice/SMS packages. You must already know the `destinationListId` to use this tool. " +
+            "Params: `destinationListId` (integer, optional — omit to list all known prefixes). " +
+            "Returns: array of prefix records with country code and E.164 prefix. " +
+            "Do NOT use this to discover the destination list catalog — use `list_destination_lists` for that. " +
+            "For data-only eSIM products without MOC voice, destination lists are irrelevant.",
+        inputSchema: {
+            destinationListId: z
+                .number()
+                .optional()
+                .describe("Filter by destination list ID"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_destination_prefixes", "listDestinationListPrefix", TOOL_SCOPES["list_destination_prefixes"], ctx, async ({ destinationListId }, token) => {
+        const params = {};
+        if (destinationListId !== undefined)
+            params.destinationListId = destinationListId;
+        return ocsCall(ctx.env, token, "listDestinationListPrefix", params);
+    }));
+    server.registerTool("create_location_zone", {
+        title: "Create Location Zone",
+        description: "Use this to create a new location zone — a named collection of countries and operators " +
+            "that defines where a package can be used. Location zones are required when creating package " +
+            "templates. Use `list_network_profiles` to find valid operator identifiers to include. " +
+            "Params: `zone` (full zone configuration as a JSON string — fields include `name`, `countries` " +
+            "(array of ISO country codes), `operators` (array of MCC-MNC strings)). " +
+            "Returns: created zone record with the new `locationZoneId`. " +
+            "Do NOT use this to modify an existing zone — no edit tool exists yet (gap G-19, pending eSIMVault). " +
+            "After creation, verify with `list_detailed_location_zones`.",
+        inputSchema: {
+            zone: z.string().describe("Zone configuration as JSON string"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("create_location_zone", "createLocationZone", TOOL_SCOPES["create_location_zone"], ctx, async ({ zone }, token) => ocsCall(ctx.env, token, "createLocationZone", JSON.parse(zone))));
+    // =========================================================================
+    // 5. STATISTICS TOOLS
+    // =========================================================================
+    // Fix #4: OCS expects { subscriber: { iccid }, period: { start, end } }
+    // not { iccid, startDate, endDate }
+    server.registerTool("subscriber_usage", {
+        title: "Subscriber Usage Over Period",
+        description: "Use this to retrieve daily data, voice, and SMS usage for a subscriber over a date range. " +
+            "Hard limit: maximum 7 days per query — do not exceed or OCS will return an error. " +
+            "Params: `iccid` (subscriber identifier), `startDate` (YYYY-MM-DD, inclusive), " +
+            "`endDate` (YYYY-MM-DD, inclusive, max 7 days from start). " +
+            "Returns: array of daily usage records with `date`, `dataBytes`, `voiceSeconds`, `smsCount`. " +
+            "Do NOT use this for event-level network activity — use `subscriber_network_events` for attach/detach events. " +
+            "Do NOT use this to check current package allowances — use `list_subscriber_packages`.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            startDate: z.string().describe("Start date (YYYY-MM-DD, inclusive)"),
+            endDate: z
+                .string()
+                .describe("End date (YYYY-MM-DD, inclusive, max 7 days from start)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("subscriber_usage", "subscriberUsageOverPeriod", TOOL_SCOPES["subscriber_usage"], ctx, async ({ iccid, startDate, endDate }, token) => ocsCall(ctx.env, token, "subscriberUsageOverPeriod", {
+        subscriber: { iccid },
+        period: { start: startDate, end: endDate },
+    })));
+    // Fix #5: same nested shape as subscriberUsageOverPeriod
+    server.registerTool("subscriber_network_events", {
+        title: "Subscriber Network Events",
+        description: "Use this to retrieve timestamped network events for a subscriber: attach, detach, location " +
+            "updates, and handovers between operators. Useful for connectivity troubleshooting, roaming " +
+            "activity verification, and fraud pattern detection. Max 7 days per query. " +
+            "Params: `iccid` (subscriber identifier), `startDate` (YYYY-MM-DD, inclusive), " +
+            "`endDate` (YYYY-MM-DD, inclusive, max 7 days from start). " +
+            "Returns: array of event records with `timestamp`, `eventType`, `country`, `operator`, `mccMnc`. " +
+            "Do NOT use this for daily usage volumes — use `subscriber_usage` for data/voice/SMS byte counts. " +
+            "For real-time events (last 24h), prefer `list_recent_ocs_events` which reads from the ring buffer.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID"),
+            startDate: z.string().describe("Start date (YYYY-MM-DD, inclusive)"),
+            endDate: z.string().describe("End date (YYYY-MM-DD, inclusive)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("subscriber_network_events", "subscriberNetworkEventsOverPeriod", TOOL_SCOPES["subscriber_network_events"], ctx, async ({ iccid, startDate, endDate }, token) => ocsCall(ctx.env, token, "subscriberNetworkEventsOverPeriod", {
+        subscriber: { iccid },
+        period: { start: startDate, end: endDate },
+    })));
+    server.registerTool("subscriber_active_period", {
+        title: "Get Subscriber Active Period",
+        description: "Use this to retrieve the lifetime activity window for a subscriber: the date of first usage " +
+            "and the date of last usage. Useful for churn analysis, dormancy detection, and subscriber " +
+            "lifetime value calculations. " +
+            "Params: `iccid` (subscriber identifier). " +
+            "Returns: object with `firstUseDate` and `lastUseDate` (ISO 8601 strings). " +
+            "Do NOT use this to check current package status — use `list_subscriber_packages`. " +
+            "Do NOT use this for detailed daily usage patterns — use `subscriber_usage`.",
+        inputSchema: { iccid: z.string().describe("The subscriber ICCID") },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("subscriber_active_period", "getSubscriberActivePeriod", TOOL_SCOPES["subscriber_active_period"], ctx, async ({ iccid }, token) => ocsCall(ctx.env, token, "getSubscriberActivePeriod", { iccid })));
+    // =========================================================================
+    // 6. MISC TOOLS (tariff, SMS, network profiles)
+    // =========================================================================
+    // Fix #14: OCS expects bare integer (resellerId); response key is listTariffRule.
+    server.registerTool("get_tariff", {
+        title: "Get Customer Tariff",
+        description: "Use this to retrieve the complete tariff table for a reseller: per-country, per-traffic-type " +
+            "(data/voice/SMS) wholesale rates. Useful for cost analysis, margin calculations, and identifying " +
+            "expensive roaming countries before steering decisions. " +
+            "Params: `resellerId` (integer, optional — omit to use the token owner's reseller). " +
+            "Returns: array of tariff rules, each with `country`, `trafficType`, `rate`, and `currency`. " +
+            "Response key in OCS is `listTariffRule`. " +
+            "Do NOT use this to assign a pricing plan to a subscriber — use `modify_subscriber_mobile_plan`. " +
+            "This shows the RESELLER's wholesale cost, not what end-users are charged.",
+        inputSchema: {
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit to use token owner's reseller)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("get_tariff", "getCustomerTariff", TOOL_SCOPES["get_tariff"], ctx, async ({ resellerId }, token) => {
+        const id = resellerId ?? (await getDefaultResellerId(ctx.env, token));
+        return ocsCall(ctx.env, token, "getCustomerTariff", id);
+    }));
+    // Fix #11: OCS expects { imsi, msisdn, text, senderId? }
+    // not { iccid, msisdn, message, sender }
+    // Resolve ICCID → IMSI; rename message → text, sender → senderId.
+    server.registerTool("send_sms", {
+        title: "Send MT SMS",
+        description: "Use this to send a mobile-terminated (MT) SMS to a subscriber. Useful for service notifications, " +
+            "package expiry alerts, and support messages sent programmatically from the platform. " +
+            "Internally resolves ICCID → IMSI via a getSingleSubscriber lookup before forwarding to OCS. " +
+            "Params: `iccid` (subscriber identifier), `msisdn` (E.164 phone number of the subscriber), " +
+            "`message` (SMS text content, max 160 chars for single SMS), " +
+            "`sender` (optional sender ID or phone number displayed on the device). " +
+            "Returns: OCS delivery confirmation. " +
+            "Do NOT use this for bulk SMS campaigns — this sends one message per call and is rate-limited. " +
+            "Requires admin scope.",
+        inputSchema: {
+            iccid: z.string().describe("The target subscriber ICCID"),
+            msisdn: z.string().describe("The target MSISDN"),
+            message: z.string().describe("SMS text content"),
+            sender: z.string().optional().describe("Sender ID/number (senderId in OCS)"),
+            ...DRY_RUN_FIELD,
+        },
+        annotations: { destructiveHint: true },
+    }, wrapHandler("send_sms", "sendMtSms", TOOL_SCOPES["send_sms"], ctx, async ({ iccid, msisdn, message, sender }, token) => {
+        const cache = new Map();
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
+        const imsi = sub.imsi;
+        if (typeof imsi !== "string" || imsi.length === 0) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: Could not resolve IMSI for ICCID ${iccid}` }],
+            };
+        }
+        const params = { imsi, msisdn, text: message };
+        if (sender)
+            params.senderId = sender;
+        return ocsCall(ctx.env, token, "sendMtSms", params);
+    }));
+    server.registerTool("list_network_profiles", {
+        title: "List Network Profiles",
+        description: "Use this to list all network profiles available to this reseller. A network profile defines " +
+            "the roaming configuration and operator partnerships for eSIM provisioning. Use profile IDs " +
+            "when creating location zones or configuring steering lists. " +
+            "Params: none. " +
+            "Returns: array of profile records with `profileId`, `name`, and coverage metadata. " +
+            "Do NOT use this to list operator steering configurations — use `list_steering_lists` for that.",
+        annotations: { readOnlyHint: true },
+    }, wrapHandler("list_network_profiles", "listNetworkProfile", TOOL_SCOPES["list_network_profiles"], ctx, async (_args, token) => ocsCall(ctx.env, token, "listNetworkProfile")));
+}
+//# sourceMappingURL=tools.js.map