@carrierllc/mcp 0.1.0 → 0.2.1

package/dist/tools.js

@@ -1,34 +1,88 @@
 /**
- * Carrier MCP stdio — OCS tool registrations (43 tools).
+ * Carrier MCP — OCS tool registrations (43 tools).
  *
- * Stdio variant: no scope enforcement, no audit hook, no Sentry.
- * Single-user — token held in OcsClient class, not passed per-call.
+ * 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)
  *
- * All 16 schema fixes from PR #10 are preserved:
+ * 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
- *   Fix #4:  subscriberUsageOverPeriod       — { subscriber: { iccid }, period }
+ *   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|setBalance }
- *   Fix #8:  changeSimStatus                 — ICCID → simId + newStatus
- *   Fix #9:  modifySubscriberContactInfo     — name/mail/phone field names
- *   Fix #10: setSubscriberTrafficRestrictions — typed booleans
+ *   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 + listTariffRule key
+ *   Fix #14: getCustomerTariff               — bare integer + response key listTariffRule
  *   Fix #15: listDetailedLocationZone        — bare integer (resellerId)
  *   Fix #16: modifySubscriberSteeringList    — { subscriber, steeringListId }
  */
 import { z } from "zod";
-import { OcsApiError } from "./client.js";
-const DRY_RUN_FIELD = {
-    dry_run: z
-        .boolean()
-        .optional()
-        .describe("If true, do not call OCS — return the would-be request for confirmation"),
+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",
+    // --- intelligence composites ---
+    detect_country_entry: "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",
@@ -54,159 +108,359 @@ export const DESTRUCTIVE_TOOLS = new Set([
     "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",
 ]);
-async function ocsCall(client, method, params = {}) {
-    const result = await client.call(method, params);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-}
-async function resolveSubscriberByIccid(client, iccid, cache) {
-    const hit = cache.get(iccid);
-    if (hit)
-        return hit;
-    const record = await client.call("getSingleSubscriber", { iccid });
-    cache.set(iccid, record);
-    return record;
-}
-async function getDefaultResellerId(client) {
-    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;
-}
-function makeHandler(toolName, _client, fn) {
+/**
+ * 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) => {
-        if (args.dry_run === true && DESTRUCTIVE_TOOLS.has(toolName)) {
+        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: `[dry_run=true] Would execute '${toolName}' with args: ${JSON.stringify(args)}. No changes made.`,
+                        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 has reached the safety limit of 100,000 regular tool calls/month.`,
+                            `This limit exists to prevent runaway automation. Resets ${quota.resetAt}.`,
+                            `Upgrade to Pro for unlimited calls 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 {
-            return await fn(args);
+            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 prefix = err instanceof OcsApiError ? `OCS ${err.code}: ` : "";
+            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: ${prefix}${message}` }],
+                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 function registerAllTools(server, client) {
+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: "List all accounts across all resellers, or filter by a specific reseller ID. Returns account names, balances, and package-only status.",
+        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"),
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Filter to a specific reseller by ID (omit for token owner's reseller)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("list_reseller_accounts", client, async ({ resellerId }) => {
+    }, wrapHandler("list_reseller_accounts", "listResellerAccount", TOOL_SCOPES["list_reseller_accounts"], ctx, async ({ resellerId }, token) => {
         const params = {};
         if (resellerId !== undefined)
             params.resellerId = resellerId;
-        return ocsCall(client, "listResellerAccount", params);
+        return ocsCall(ctx.env, token, "listResellerAccount", params);
     }));
     server.registerTool("modify_account_balance", {
         title: "Modify Account Balance",
-        description: "Adjust or set the balance of a reseller account. 'adapt' adds/subtracts from current balance; 'set' replaces it.",
+        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"),
+            mode: z
+                .enum(["adapt", "set"])
+                .describe("'adapt' adds/subtracts, 'set' replaces the balance"),
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("modify_account_balance", client, async ({ accountId, amount, mode }) => {
+    }, 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(client, "modifyAccountBalance", params);
+        return ocsCall(ctx.env, token, "modifyAccountBalance", params);
     }));
     server.registerTool("get_reseller_info", {
         title: "Get Reseller Info",
-        description: "Retrieve detailed information about a reseller. If no ID provided, returns info for the reseller owning the API token.",
+        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)"),
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit for token owner)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("get_reseller_info", client, async ({ resellerId }) => {
+    }, wrapHandler("get_reseller_info", "getResellerInfo", TOOL_SCOPES["get_reseller_info"], ctx, async ({ resellerId }, token) => {
         const params = {};
         if (resellerId !== undefined)
             params.resellerId = resellerId;
-        return ocsCall(client, "getResellerInfo", params);
+        return ocsCall(ctx.env, token, "getResellerInfo", params);
     }));
     server.registerTool("esim_status_per_account", {
         title: "eSIM Status Per Account",
-        description: "Get eSIM status breakdown per account — active, suspended, inventory counts.",
+        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"),
+            accountId: z
+                .number()
+                .optional()
+                .describe("Filter to a specific account"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("esim_status_per_account", client, async ({ accountId }) => {
+    }, 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(client, "esimStatusPerAccount", params);
+        return ocsCall(ctx.env, token, "esimStatusPerAccount", params);
     }));
-    // Fix #12: bare integer
+    // Fix #12: OCS expects bare integer (resellerId), not {}
     server.registerTool("list_sponsors", {
         title: "List Sponsors",
-        description: "List all sponsor networks available to this reseller. Pass resellerId explicitly or omit to use the token owner's reseller.",
+        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)"),
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit to use token owner's reseller)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("list_sponsors", client, async ({ resellerId }) => {
-        const id = resellerId ?? (await getDefaultResellerId(client));
-        return ocsCall(client, "listSponsor", id);
+    }, 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: bare integer
+    // Fix #13: OCS expects bare integer (resellerId), not {}
     server.registerTool("list_steering_lists", {
         title: "List Steering Lists",
-        description: "List all network steering lists for this reseller. Steering lists control which networks eSIMs prefer to connect to.",
+        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)"),
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit to use token owner's reseller)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("list_steering_lists", client, async ({ resellerId }) => {
-        const id = resellerId ?? (await getDefaultResellerId(client));
-        return ocsCall(client, "listSteeringList", id);
+    }, 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: "Retrieve full details for a single subscriber by ICCID or MSISDN.",
+        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. " +
+            "Optional: `with_gz_counter` (boolean) — when true, includes `greenZoneCounter` in the response: " +
+            "{ subscriberId, volumeOnGZ (bytes consumed on reseller whitelist hosts/IPs after bundle depletion), " +
+            "lastResetDate, lastUpdateDate }. Omit or set false to skip the GZ counter (default). " +
+            "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"),
+            msisdn: z
+                .string()
+                .optional()
+                .describe("The MSISDN (phone number) of the subscriber"),
+            with_gz_counter: z
+                .boolean()
+                .optional()
+                .describe("When true, include greenZoneCounter { subscriberId, volumeOnGZ (bytes), lastResetDate, lastUpdateDate } — tracks bytes consumed on reseller whitelist hosts/IPs after bundle depletion"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("get_subscriber", client, async ({ iccid, msisdn }) => {
+    }, wrapHandler("get_subscriber", "getSingleSubscriber", TOOL_SCOPES["get_subscriber"], ctx, async ({ iccid, msisdn, with_gz_counter }, token) => {
         const params = {};
         if (iccid)
             params.iccid = iccid;
         if (msisdn)
             params.msisdn = msisdn;
-        return ocsCall(client, "getSingleSubscriber", params);
+        if (with_gz_counter === true)
+            params.withGzCounter = true;
+        return ocsCall(ctx.env, token, "getSingleSubscriber", params);
     }));
     server.registerTool("list_subscribers", {
         title: "List Subscribers",
-        description: "List subscribers with optional filters. Supports pagination.",
+        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"),
@@ -214,7 +468,9 @@ export function registerAllTools(server, client) {
             limit: z.number().optional().describe("Max results to return"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("list_subscribers", client, async (args) => {
+    }, 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;
@@ -222,90 +478,144 @@ export function registerAllTools(server, client) {
             params.status = args.status;
         if (args.offset !== undefined)
             params.offset = args.offset;
-        if (args.limit !== undefined)
-            params.limit = args.limit;
-        return ocsCall(client, "listSubscriber", params);
+        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: { subscriber, amount } or { subscriber, setBalance }
+    // Fix #7: OCS expects { subscriber, amount } or { subscriber, setBalance } not { iccid, adaptBalance|setBalance }
     server.registerTool("modify_subscriber_balance", {
         title: "Modify Subscriber Balance",
-        description: "Adjust or set the balance of an individual subscriber. 'adapt' adds/subtracts; 'set' replaces.",
+        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"),
+            mode: z
+                .enum(["adapt", "set"])
+                .describe("'adapt' adds/subtracts, 'set' replaces"),
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("modify_subscriber_balance", client, async ({ iccid, amount, mode }) => {
+    }, 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(client, "modifySubscriberBalance", params);
+        return ocsCall(ctx.env, token, "modifySubscriberBalance", params);
     }));
-    // Fix #6: { subscriber, newStatus }
+    // Fix #6: OCS expects { subscriber, newStatus } not { iccid, status }
     server.registerTool("modify_subscriber_status", {
         title: "Modify Subscriber Status",
-        description: "Change a subscriber's status (e.g., activate, suspend, terminate).",
+        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. " +
+            "⚠ Setting status to END_OF_LIFE is irreversible. The subscriber becomes read-only (OCS error 17 on subsequent mutations). Confirm before calling. " +
+            "Params: `iccid` (subscriber identifier), `status` (new status string, e.g. 'ACTIVE', " +
+            "'SUSPENDED', 'TERMINATED', 'END_OF_LIFE'). " +
+            "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 },
-    }, makeHandler("modify_subscriber_status", client, async ({ iccid, status }) => ocsCall(client, "modifySubscriberStatus", { subscriber: iccid, newStatus: status })));
-    // Fix #8: ICCID → simId → { simId, newStatus }
+    }, 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: "Change the SIM card status at the provider level (enable/disable/delete). Internally resolves ICCID to simId before calling OCS.",
+        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 },
-    }, makeHandler("change_sim_status", client, async ({ iccid, simStatus }) => {
+    }, wrapHandler("change_sim_status", "changeSimStatus", TOOL_SCOPES["change_sim_status"], ctx, async ({ iccid, simStatus }, token) => {
         const cache = new Map();
-        const sub = await resolveSubscriberByIccid(client, iccid, cache);
-        const simId = sub.simId ?? sub.sim_id ?? sub.id;
+        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(client, "changeSimStatus", { simId: Number(simId), newStatus: simStatus });
+        return ocsCall(ctx.env, token, "changeSimStatus", {
+            simId: Number(simId),
+            newStatus: simStatus,
+        });
     }));
-    // Fix #1: ICCID → simId → bare integer
+    // 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: "Check the SIM provider-level status for a subscriber. Accepts ICCID; resolves to the numeric simId required by OCS internally.",
-        inputSchema: { iccid: z.string().describe("The subscriber ICCID") },
+        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 },
-    }, makeHandler("get_sim_provider_status", client, async ({ iccid }) => {
+    }, wrapHandler("get_sim_provider_status", "getSimProviderStatus", TOOL_SCOPES["get_sim_provider_status"], ctx, async ({ iccid }, token) => {
         const cache = new Map();
-        const sub = await resolveSubscriberByIccid(client, iccid, cache);
-        const simId = sub.simId ?? sub.sim_id ?? sub.id;
+        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(client, "getSimProviderStatus", Number(simId));
+        return ocsCall(ctx.env, token, "getSimProviderStatus", Number(simId));
     }));
     server.registerTool("get_subscriber_location", {
         title: "Get Subscriber Location",
-        description: "Get the last known location of a subscriber.",
+        description: "Returns last-known location from subscriber's most recent cell tower usage. Complementary to GeoSense get_subscriber_location_by_cell_id — use this when you have the subscriber id, use the cell-id variant when you have raw cell parameters.",
         inputSchema: { iccid: z.string().describe("The subscriber ICCID") },
         annotations: { readOnlyHint: true },
-    }, makeHandler("get_subscriber_location", client, async ({ iccid }) => ocsCall(client, "getSubscriberLocation", { iccid })));
-    // Fix #9: name/mail/phone field names
+    }, 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: "Update contact information (name, email, etc.) for a subscriber.",
+        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"),
@@ -316,7 +626,7 @@ export function registerAllTools(server, client) {
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("modify_subscriber_contact_info", client, async ({ iccid, firstName, lastName, company, email, phoneNumber }) => {
+    }, 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)
@@ -327,12 +637,21 @@ export function registerAllTools(server, client) {
             params.phone = phoneNumber;
         if (email !== undefined)
             params.mail = email;
-        return ocsCall(client, "modifySubscriberContactInfo", params);
+        return ocsCall(ctx.env, token, "modifySubscriberContactInfo", params);
     }));
-    // Fix #10: typed booleans
+    // 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: "Configure traffic restrictions for a subscriber — control allowed/blocked traffic types (data, voice MO/MT, SMS MO).",
+        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"),
@@ -342,7 +661,7 @@ export function registerAllTools(server, client) {
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("set_subscriber_traffic_restrictions", client, async ({ iccid, mtcAllowed, smsMoAllowed, dataAllowed, mocAllowed }) => {
+    }, 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;
@@ -352,22 +671,40 @@ export function registerAllTools(server, client) {
             params.dataAllowed = dataAllowed;
         if (mocAllowed !== undefined)
             params.mocAllowed = mocAllowed;
-        return ocsCall(client, "setSubscriberTrafficRestrictions", params);
+        return ocsCall(ctx.env, token, "setSubscriberTrafficRestrictions", params);
     }));
-    // Fix #16: { subscriber, steeringListId }
+    // Fix #16: OCS expects { subscriber, steeringListId } not { iccid, steeringListId }
     server.registerTool("modify_subscriber_steering_list", {
         title: "Modify Subscriber Steering List",
-        description: "Change the network steering list assigned to a subscriber.",
+        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 },
-    }, makeHandler("modify_subscriber_steering_list", client, async ({ iccid, steeringListId }) => ocsCall(client, "modifySubscriberSteeringList", { subscriber: iccid, steeringListId })));
+    }, 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: "Move a range of subscribers to a different 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"),
@@ -375,20 +712,52 @@ export function registerAllTools(server, client) {
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("move_subscriber_range_to_account", client, async ({ iccidFrom, iccidTo, accountId }) => ocsCall(client, "moveSubscriberRangeToAccount", { iccidFrom, iccidTo, accountId })));
-    // Fix #3: ICCID → IMSI + bitrate → limit
+    }, 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.
+    // B2.4: added bitrate_string string-enum alternative; refine ensures at least one of (bitrate, bitrate_string).
     server.registerTool("hlr_set_bitrate", {
         title: "Set HLR Bitrate",
-        description: "Set the maximum data bitrate for a subscriber at the HLR level. Accepts ICCID; resolves to IMSI required by OCS internally.",
-        inputSchema: {
+        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. " +
+            "Provide at least one of `bitrate` (numeric bps) or `bitrate_string` (OCS string enum); " +
+            "when both are provided, `bitrate_string` is used. " +
+            "String enum values: KB_32, KB_64, KB_128, KB_256, KB_384, KB_512, KB_1024, KB_2048, KB_3072, " +
+            "KB_5120, KB_7680, KB_10240, KB_20480, KB_51200, KB_102400, UNLIMITED. " +
+            "Numeric equivalents: 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) OR " +
+            "`bitrate_string` (string enum from the list above). " +
+            "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: z
+            .object({
             iccid: z.string().describe("The subscriber ICCID"),
-            bitrate: z.number().describe("Max bitrate in bps"),
-            ...DRY_RUN_FIELD,
-        },
+            bitrate: z.number().optional().describe("Max bitrate in bps (numeric form; use 0 to remove limit)"),
+            bitrate_string: z
+                .enum([
+                "KB_32", "KB_64", "KB_128", "KB_256", "KB_384", "KB_512",
+                "KB_1024", "KB_2048", "KB_3072", "KB_5120", "KB_7680",
+                "KB_10240", "KB_20480", "KB_51200", "KB_102400", "UNLIMITED",
+            ])
+                .optional()
+                .describe("Max bitrate as OCS string enum (alternative to numeric `bitrate`)"),
+            dry_run: z
+                .boolean()
+                .optional()
+                .describe("If true, do not call OCS — return the would-be request for confirmation"),
+        })
+            .refine((d) => d.bitrate !== undefined || d.bitrate_string !== undefined, { message: "Provide at least one of `bitrate` (number) or `bitrate_string` (string enum)" }),
         annotations: { destructiveHint: true },
-    }, makeHandler("hlr_set_bitrate", client, async ({ iccid, bitrate }) => {
+    }, wrapHandler("hlr_set_bitrate", "hlrSetBitrate", TOOL_SCOPES["hlr_set_bitrate"], ctx, async ({ iccid, bitrate, bitrate_string }, token) => {
         const cache = new Map();
-        const sub = await resolveSubscriberByIccid(client, iccid, cache);
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
         const imsi = sub.imsi;
         if (typeof imsi !== "string" || imsi.length === 0) {
             return {
@@ -396,17 +765,25 @@ export function registerAllTools(server, client) {
                 content: [{ type: "text", text: `Error: Could not resolve IMSI for ICCID ${iccid}` }],
             };
         }
-        return ocsCall(client, "hlrSetBitrate", { imsi, limit: bitrate });
+        const limit = bitrate_string !== undefined ? bitrate_string : bitrate;
+        return ocsCall(ctx.env, token, "hlrSetBitrate", { imsi, limit });
     }));
-    // Fix #2: ICCID → IMSI
+    // Fix #2: OCS expects { imsi } not { iccid }.
+    // Resolve ICCID → IMSI via getSingleSubscriber.
     server.registerTool("hlr_get_bitrate", {
         title: "Get HLR Bitrate",
-        description: "Get the current HLR bitrate setting for a subscriber. Accepts ICCID; resolves to IMSI required by OCS internally.",
+        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 },
-    }, makeHandler("hlr_get_bitrate", client, async ({ iccid }) => {
+    }, wrapHandler("hlr_get_bitrate", "hlrGetBitrate", TOOL_SCOPES["hlr_get_bitrate"], ctx, async ({ iccid }, token) => {
         const cache = new Map();
-        const sub = await resolveSubscriberByIccid(client, iccid, cache);
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
         const imsi = sub.imsi;
         if (typeof imsi !== "string" || imsi.length === 0) {
             return {
@@ -414,40 +791,138 @@ export function registerAllTools(server, client) {
                 content: [{ type: "text", text: `Error: Could not resolve IMSI for ICCID ${iccid}` }],
             };
         }
-        return ocsCall(client, "hlrGetBitrate", { imsi });
+        return ocsCall(ctx.env, token, "hlrGetBitrate", { imsi });
     }));
     // =========================================================================
     // 3. PACKAGE TOOLS
     // =========================================================================
     server.registerTool("list_subscriber_packages", {
         title: "List Subscriber Packages",
-        description: "List all prepaid packages assigned to a subscriber. Shows allowances, usage, expiry, status.",
+        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 },
-    }, makeHandler("list_subscriber_packages", client, async ({ iccid }) => ocsCall(client, "listSubscriberPrepaidPackages", { iccid })));
+    }, 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: "Assign a prepaid package template to a 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`), " +
+            "`account_for_subs` (integer, optional — when provided instead of resolving a subscriber, OCS auto-selects " +
+            "a free eSIM from that account and assigns the package; this is the bulk auto-provisioning path). " +
+            "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"),
+            packageTemplateId: z
+                .number()
+                .describe("The package template ID to assign"),
+            account_for_subs: z
+                .number()
+                .optional()
+                .describe("Account ID — when provided, OCS auto-selects a free eSIM from this account for bulk provisioning"),
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("assign_package", client, async ({ iccid, packageTemplateId }) => ocsCall(client, "affectPackageToSubscriber", { subscriber: iccid, packageTemplateId })));
+    }, wrapHandler("assign_package", "affectPackageToSubscriber", TOOL_SCOPES["assign_package"], ctx, async ({ iccid, packageTemplateId, account_for_subs }, token) => {
+        // accountForSubs is an alternative to subscriber per OCS — never send both.
+        if (account_for_subs !== undefined) {
+            return ocsCall(ctx.env, token, "affectPackageToSubscriber", {
+                packageTemplateId,
+                accountForSubs: account_for_subs,
+            });
+        }
+        // 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: "Assign a recurring (auto-renewing) prepaid package to a subscriber.",
-        inputSchema: {
+        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), " +
+            "`activation_at_first_use` (boolean, optional — when true, package activates on the subscriber's " +
+            "first network usage rather than immediately; mutually exclusive with `start_time_utc`), " +
+            "`start_time_utc` (ISO 8601 UTC datetime, optional — schedules a specific activation start; " +
+            "mutually exclusive with `activation_at_first_use`). " +
+            "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: z
+            .object({
             iccid: z.string().describe("The subscriber ICCID"),
             packageTemplateId: z.number().describe("The package template ID"),
-            ...DRY_RUN_FIELD,
-        },
+            activation_at_first_use: z
+                .boolean()
+                .optional()
+                .describe("When true, package activates on first network usage (mutually exclusive with start_time_utc)"),
+            start_time_utc: z
+                .string()
+                .optional()
+                .describe("Scheduled activation datetime in ISO 8601 UTC format (mutually exclusive with activation_at_first_use)"),
+            dry_run: z
+                .boolean()
+                .optional()
+                .describe("If true, do not call OCS — return the would-be request for confirmation"),
+        })
+            .refine((d) => !(d.activation_at_first_use === true && d.start_time_utc !== undefined), {
+            message: "activation_at_first_use and start_time_utc are mutually exclusive — choose one",
+        }),
         annotations: { destructiveHint: true },
-    }, makeHandler("assign_recurring_package", client, async ({ iccid, packageTemplateId }) => ocsCall(client, "affectRecurringPackageToSubscriber", { subscriber: iccid, packageTemplateId })));
+    }, wrapHandler("assign_recurring_package", "affectRecurringPackageToSubscriber", TOOL_SCOPES["assign_recurring_package"], ctx, async ({ iccid, packageTemplateId, activation_at_first_use, start_time_utc }, 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}` }],
+            };
+        }
+        const params = {
+            subscriber: Number(subscriberId),
+            packageTemplateId,
+        };
+        if (activation_at_first_use === true)
+            params.activationAtFirstUse = true;
+        if (start_time_utc !== undefined)
+            params.startTimeUTC = start_time_utc;
+        return ocsCall(ctx.env, token, "affectRecurringPackageToSubscriber", params);
+    }));
     server.registerTool("modify_package_limits", {
         title: "Modify Package Limits",
-        description: "Change the data/voice/SMS limits on an active subscriber package.",
+        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"),
@@ -455,25 +930,62 @@ export function registerAllTools(server, client) {
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("modify_package_limits", client, async ({ iccid, packageId, limits }) => ocsCall(client, "modifySubscriberPrepaidPackageLimits", {
+    }, 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: "Change the expiration date of an active subscriber package.",
-        inputSchema: {
+        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' — absolute date), " +
+            "`validity_days` (integer, optional — number of days from now; passed to OCS as `newValidityDuration`; " +
+            "provide either `expirationDate` OR `validity_days`, not both). " +
+            "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: z
+            .object({
             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)"),
+            expirationDate: z
+                .string()
+                .optional()
+                .describe("New expiry date (ISO 8601 format, absolute)"),
+            validity_days: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Number of days from now until expiry (alternative to expirationDate)"),
             ...DRY_RUN_FIELD,
-        },
+        })
+            .refine((d) => d.expirationDate !== undefined || d.validity_days !== undefined, {
+            message: "Provide at least one of `expirationDate` (absolute) or `validity_days` (relative)",
+        })
+            .refine((d) => !(d.expirationDate !== undefined && d.validity_days !== undefined), {
+            message: "`expirationDate` and `validity_days` are mutually exclusive — choose one",
+        }),
         annotations: { destructiveHint: true },
-    }, makeHandler("modify_package_expiry", client, async ({ iccid, packageId, expirationDate }) => ocsCall(client, "modifySubscriberPrepaidPackageExpDate", { iccid, packageId, expirationDate })));
+    }, wrapHandler("modify_package_expiry", "modifySubscriberPrepaidPackageExpDate", TOOL_SCOPES["modify_package_expiry"], ctx, async ({ iccid, packageId, expirationDate, validity_days }, token) => {
+        const params = { iccid, packageId };
+        if (expirationDate !== undefined)
+            params.expirationDate = expirationDate;
+        if (validity_days !== undefined)
+            params.newValidityDuration = validity_days;
+        return ocsCall(ctx.env, token, "modifySubscriberPrepaidPackageExpDate", params);
+    }));
     server.registerTool("modify_package_status", {
         title: "Modify Package Status",
-        description: "Activate or deactivate a subscriber's prepaid package.",
+        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"),
@@ -481,195 +993,360 @@ export function registerAllTools(server, client) {
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("modify_package_status", client, async ({ iccid, packageId, status }) => ocsCall(client, "modifySubscriberPrepaidPackageStatus", { iccid, packageId, status })));
+    }, 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: "Stop or resume a recurring package's auto-renewal.",
+        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"),
+            action: z
+                .enum(["stop", "resume"])
+                .describe("Whether to stop or resume"),
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("stop_resume_recurring_package", client, async ({ iccid, packageId, action }) => ocsCall(client, "stopResumeSubsRecurringPackage", { iccid, packageId, action })));
+    }, 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: "Remove a package from a subscriber entirely.",
+        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 },
-    }, makeHandler("delete_subscriber_package", client, async ({ iccid, packageId }) => ocsCall(client, "deleteSubscriberPackage", { iccid, packageId })));
+    }, 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: "Remove ALL packages from a subscriber. Use with caution.",
+        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 },
-    }, makeHandler("clean_all_packages", client, async ({ iccid }) => ocsCall(client, "cleanSubscriberAllPackages", { iccid })));
+    }, 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: "List all available prepaid 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"),
+            accountId: z
+                .number()
+                .optional()
+                .describe("Filter templates by account ID"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("list_package_templates", client, async ({ accountId }) => {
+    }, wrapHandler("list_package_templates", "listPrepaidPackageTemplate", TOOL_SCOPES["list_package_templates"], ctx, async ({ accountId }, token) => {
         const params = {};
         if (accountId !== undefined)
             params.accountId = accountId;
-        return ocsCall(client, "listPrepaidPackageTemplate", params);
+        return ocsCall(ctx.env, token, "listPrepaidPackageTemplate", params);
     }));
     server.registerTool("create_package_template", {
         title: "Create Package Template",
-        description: "Create a new prepaid package template. Define allowances, pricing, zones, and validity.",
+        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"),
+            template: z
+                .string()
+                .describe("Full template configuration as JSON string"),
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("create_package_template", client, async ({ template }) => ocsCall(client, "createPrepaidPackageTemplate", JSON.parse(template))));
+    }, 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: "Modify core settings of a package template (name, limits, pricing).",
+        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 },
-    }, makeHandler("modify_template_core", client, async ({ templateId, changes }) => ocsCall(client, "modifyPPTCore", { templateId, ...JSON.parse(changes) })));
+    }, 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: "Modify recurring/renewal settings of a package template.",
+        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"),
+            changes: z
+                .string()
+                .describe("Recurring fields to modify as JSON string"),
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("modify_template_recurring", client, async ({ templateId, changes }) => ocsCall(client, "modifyPPTRecurring", { templateId, ...JSON.parse(changes) })));
+    }, 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: "Modify throttling/speed settings of a package template.",
+        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"),
+            changes: z
+                .string()
+                .describe("Throttling fields to modify as JSON string"),
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("modify_template_throttling", client, async ({ templateId, changes }) => ocsCall(client, "modifyPPTThrottling", { templateId, ...JSON.parse(changes) })));
+    }, 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: "List countries/networks in a location zone.",
+        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 },
-    }, makeHandler("list_location_zones", client, async ({ locationZoneId }) => {
+    }, wrapHandler("list_location_zones", "listLocationZoneElement", TOOL_SCOPES["list_location_zones"], ctx, async ({ locationZoneId }, token) => {
         const params = {};
         if (locationZoneId !== undefined)
             params.locationZoneId = locationZoneId;
-        return ocsCall(client, "listLocationZoneElement", params);
+        return ocsCall(ctx.env, token, "listLocationZoneElement", params);
     }));
-    // Fix #15: bare integer
+    // Fix #15: OCS expects bare integer (resellerId), not {}
     server.registerTool("list_detailed_location_zones", {
         title: "List Detailed Location Zones",
-        description: "Get detailed location zone definitions with included countries/networks. Pass resellerId explicitly or omit to use the token owner's reseller.",
+        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)"),
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit to use token owner's reseller)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("list_detailed_location_zones", client, async ({ resellerId }) => {
-        const id = resellerId ?? (await getDefaultResellerId(client));
-        return ocsCall(client, "listDetailedLocationZone", id);
+    }, 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: "List phone number prefixes in destination lists (for voice/SMS routing).",
+        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"),
+            destinationListId: z
+                .number()
+                .optional()
+                .describe("Filter by destination list ID"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("list_destination_prefixes", client, async ({ destinationListId }) => {
+    }, wrapHandler("list_destination_prefixes", "listDestinationListPrefix", TOOL_SCOPES["list_destination_prefixes"], ctx, async ({ destinationListId }, token) => {
         const params = {};
         if (destinationListId !== undefined)
             params.destinationListId = destinationListId;
-        return ocsCall(client, "listDestinationListPrefix", params);
+        return ocsCall(ctx.env, token, "listDestinationListPrefix", params);
     }));
     server.registerTool("create_location_zone", {
         title: "Create Location Zone",
-        description: "Create a new location zone for use in package templates.",
+        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 },
-    }, makeHandler("create_location_zone", client, async ({ zone }) => ocsCall(client, "createLocationZone", JSON.parse(zone))));
+    }, 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: { subscriber: { iccid }, period: { start, end } }
+    // Fix #4: OCS expects { subscriber: { iccid }, period: { start, end } }
+    // not { iccid, startDate, endDate }
     server.registerTool("subscriber_usage", {
         title: "Subscriber Usage Over Period",
-        description: "Get daily data/voice/SMS usage for a subscriber over a date range (max 7 days).",
+        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. Each record contains a `usageType` integer code: " +
+            "1=MOC (mobile-originated call), 15=MTC (mobile-terminated call), " +
+            "21=MO-SMS (outbound SMS), 22=MT-SMS (inbound SMS), " +
+            "33=Data, 40=MOC VoIP, 41=MTC VoIP. " +
+            "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)"),
+            endDate: z
+                .string()
+                .describe("End date (YYYY-MM-DD, inclusive, max 7 days from start)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("subscriber_usage", client, async ({ iccid, startDate, endDate }) => ocsCall(client, "subscriberUsageOverPeriod", {
+    }, 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
+    // Fix #5: same nested shape as subscriberUsageOverPeriod
     server.registerTool("subscriber_network_events", {
         title: "Subscriber Network Events",
-        description: "Get network events (attach, detach, location updates) for a subscriber over a period (max 7 days).",
+        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 },
-    }, makeHandler("subscriber_network_events", client, async ({ iccid, startDate, endDate }) => ocsCall(client, "subscriberNetworkEventsOverPeriod", {
+    }, 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: "Get the active period (first to last use) for a subscriber.",
+        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 },
-    }, makeHandler("subscriber_active_period", client, async ({ iccid }) => ocsCall(client, "getSubscriberActivePeriod", { iccid })));
+    }, wrapHandler("subscriber_active_period", "getSubscriberActivePeriod", TOOL_SCOPES["subscriber_active_period"], ctx, async ({ iccid }, token) => ocsCall(ctx.env, token, "getSubscriberActivePeriod", { iccid })));
     // =========================================================================
-    // 6. MISC TOOLS
+    // 6. MISC TOOLS (tariff, SMS, network profiles)
     // =========================================================================
-    // Fix #14: bare integer, listTariffRule response key
+    // Fix #14: OCS expects bare integer (resellerId); response key is listTariffRule.
     server.registerTool("get_tariff", {
         title: "Get Customer Tariff",
-        description: "Retrieve the tariff/pricing table for this reseller (per-country, per-traffic-type rates). Pass resellerId explicitly or omit to use the token owner's reseller.",
+        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)"),
+            resellerId: z
+                .number()
+                .optional()
+                .describe("Reseller ID (omit to use token owner's reseller)"),
         },
         annotations: { readOnlyHint: true },
-    }, makeHandler("get_tariff", client, async ({ resellerId }) => {
-        const id = resellerId ?? (await getDefaultResellerId(client));
-        return ocsCall(client, "getCustomerTariff", id);
+    }, 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: ICCID→IMSI, message→text, sender→senderId
+    // 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: "Send a mobile-terminated SMS to a subscriber. Accepts ICCID; resolves to IMSI required by OCS internally.",
+        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 in GSM-7 encoding), " +
+            "`sender` (optional sender ID or phone number displayed on the device). " +
+            "⚠ Messages containing non-GSM-7 characters (any emoji, é, ñ, Chinese, Arabic, Hebrew, etc.) " +
+            "trigger UCS-2 encoding which limits a single SMS to 70 characters instead of 160. " +
+            "Plan for multi-part splits accordingly. " +
+            "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"),
@@ -678,9 +1355,9 @@ export function registerAllTools(server, client) {
             ...DRY_RUN_FIELD,
         },
         annotations: { destructiveHint: true },
-    }, makeHandler("send_sms", client, async ({ iccid, msisdn, message, sender }) => {
+    }, wrapHandler("send_sms", "sendMtSms", TOOL_SCOPES["send_sms"], ctx, async ({ iccid, msisdn, message, sender }, token) => {
         const cache = new Map();
-        const sub = await resolveSubscriberByIccid(client, iccid, cache);
+        const sub = await resolveSubscriberByIccid(ctx.env, token, iccid, cache);
         const imsi = sub.imsi;
         if (typeof imsi !== "string" || imsi.length === 0) {
             return {
@@ -691,12 +1368,17 @@ export function registerAllTools(server, client) {
         const params = { imsi, msisdn, text: message };
         if (sender)
             params.senderId = sender;
-        return ocsCall(client, "sendMtSms", params);
+        return ocsCall(ctx.env, token, "sendMtSms", params);
     }));
     server.registerTool("list_network_profiles", {
         title: "List Network Profiles",
-        description: "List all available 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 },
-    }, makeHandler("list_network_profiles", client, async (_args) => ocsCall(client, "listNetworkProfile")));
+    }, wrapHandler("list_network_profiles", "listNetworkProfile", TOOL_SCOPES["list_network_profiles"], ctx, async (_args, token) => ocsCall(ctx.env, token, "listNetworkProfile")));
 }
 //# sourceMappingURL=tools.js.map