@carrierllc/mcp 0.4.0 → 0.5.0

package/dist/index.js

@@ -25,13 +25,14 @@ import {
   probeAll,
   provisionClerk,
   rankTargets,
+  recurringPackageParams,
   renderHtml,
   repairPlanFor,
   storefrontClerkUrls,
   subscriberIdParams,
   usageOverPeriodParams,
   verifyStorefront
-} from "./chunk-RBG4MKMW.js";
+} from "./chunk-QZBALDKD.js";
 import "./chunk-SHKKVIIA.js";
 
 // src/index.ts
@@ -1217,21 +1218,10 @@ function registerAllTools(server2, ctx) {
       TOOL_SCOPES["assign_recurring_package"],
       ctx,
       async ({ iccid, packageTemplateId, activation_at_first_use, start_time_utc }, token2) => {
-        const cache = /* @__PURE__ */ new Map();
-        const sub = await resolveSubscriberByIccid(ctx.env, token2, iccid, cache);
-        const subscriberId = sub.id ?? sub.subscriberId;
-        if (subscriberId === void 0) {
-          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 !== void 0) params.startTimeUTC = start_time_utc;
+        const params = recurringPackageParams(iccid, packageTemplateId, {
+          activationAtFirstUse: activation_at_first_use,
+          startTimeUTC: start_time_utc
+        });
         return ocsCall(ctx.env, token2, "affectRecurringPackageToSubscriber", params);
       }
     )
@@ -3544,7 +3534,10 @@ High suspension rate (${totalSuspended} suspended vs ${totalActive} active)`);
         (a) => Number(a.balance ?? 0) < 10
       );
       const packageOnlyZero = accounts.filter(
-        (a) => Boolean(a.packageOnly) && Number(a.balance ?? 0) <= 0
+        (a) => a.packageOnly === true && Number(a.balance ?? 0) === 0
+      );
+      const criticalZero = accounts.filter(
+        (a) => a.packageOnly === false && Number(a.balance ?? 0) <= 0
       );
       sections.push(`
 ## Account Summary`);
@@ -3560,23 +3553,28 @@ High suspension rate (${totalSuspended} suspended vs ${totalActive} active)`);
           sections.push(`| ${a.name ?? a.accountId ?? "?"} | ${Number(a.balance ?? 0).toFixed(2)} | ${a.packageOnly ? "yes" : "no"} |`);
         }
       }
-      const critical = packageOnlyZero.length;
-      const warning = lowBalance.length - critical;
-      const healthy = accounts.length - lowBalance.length;
+      const informational = packageOnlyZero.length;
+      const critical = criticalZero.length;
+      const warning = lowBalance.length - informational - critical;
+      const healthy = accounts.length - informational - critical - Math.max(warning, 0);
       sections.push(`
 ## Fleet Health Verdict`);
       sections.push(`- Healthy: ${healthy}`);
-      sections.push(`- Warning (low balance, not package-only-zero): ${Math.max(warning, 0)}`);
-      sections.push(`- Critical (package-only and 0 balance): ${critical}`);
+      sections.push(`- Informational (package-only at 0 balance): ${informational}`);
+      sections.push(`- Warning (low balance): ${Math.max(warning, 0)}`);
+      sections.push(`- Critical (non-package-only at 0 balance): ${critical}`);
       if (accounts.length === 0) {
         sections.push(`
 No accounts found under this reseller.`);
       } else if (critical > 0) {
         sections.push(`
-Action: top up package-only accounts at 0 balance to keep packages assignable.`);
+Action: top up non-package-only accounts at 0 balance to restore rated traffic.`);
       } else if (lowBalance.length === 0) {
         sections.push(`
 All accounts healthy.`);
+      } else if (informational > 0 && warning <= 0) {
+        sections.push(`
+Package-only accounts at 0 balance require no action.`);
       }
     } else {
       sections.push(`
@@ -8516,6 +8514,14 @@ function writeUsageThresholdAudit(env, severity, remainingCredits, month, taskCo
 }
 
 // src/tools-ui-agent-schedule.ts
+var UI_AGENT_SCHEDULE_TOOL_SCOPES = {
+  ui_agent_schedule_create: "admin",
+  ui_agent_schedule_list: "read",
+  ui_agent_schedule_delete: "admin",
+  ui_agent_schedule_pause: "admin",
+  ui_agent_schedule_resume: "admin",
+  ui_agent_usage: "read"
+};
 function noManusKeyError() {
   return {
     isError: true,
@@ -9223,6 +9229,18 @@ Report success or failure with a clear summary.`;
     }
   };
 }
+var UI_AGENT_TOOL_SCOPES = {
+  ui_create_steering_list: "write",
+  ui_build_steering_list: "write",
+  ui_set_account_steering_list: "write",
+  ui_create_account: "admin",
+  ui_create_destination_list: "write",
+  ui_edit_destination_list: "write",
+  ui_delete_destination_list: "admin",
+  ui_delete_package_template: "admin",
+  ui_edit_location_zone: "write",
+  ui_delete_location_zone: "admin"
+};
 function registerAllUiAgentTools(server2, ctx) {
   server2.registerTool(
     "ui_create_steering_list",
@@ -9568,6 +9586,10 @@ async function askReply(keys, taskId, reply) {
 }
 
 // src/tools-ui-agent-ask.ts
+var UI_AGENT_ASK_TOOL_SCOPES = {
+  ui_agent_reply: "write",
+  ui_agent_list_pending: "read"
+};
 function computeExpiresAt(askedAt) {
   const asked = new Date(askedAt).getTime();
   if (isNaN(asked)) return "";
@@ -9811,6 +9833,110 @@ function writeAudit(env, row) {
   });
 }
 
+// src/tool-annotations.ts
+function annotationsForScope(scope) {
+  switch (scope) {
+    case "read":
+      return {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      };
+    case "write":
+      return {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      };
+    case "admin":
+      return {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      };
+  }
+}
+var ANNOTATION_OVERRIDES = {
+  // --- Destructive despite a non-admin scope -------------------------------
+  /** Removes a package from a live SIM; the subscriber loses service on it. */
+  delete_subscriber_package: { destructiveHint: true },
+  /** Can suspend or terminate a line — service stops until reversed. */
+  modify_subscriber_status: { destructiveHint: true },
+  /** Invalidates the credentials in use; anything holding the old ones breaks. */
+  rotate_credentials: { destructiveHint: true },
+  /** Moves money back to a cardholder. Not reversible from Carrier's side. */
+  stripe_connect_refund: { destructiveHint: true },
+  /** Closes a Radar review against the payment; the decision sticks. */
+  radar_review_decline: { destructiveHint: true },
+  /** Blocks or allows a value fleet-wide; affects future charges, not just one. */
+  radar_value_list_add: { destructiveHint: true },
+  /** Re-parents a whole subscriber range to another account. */
+  move_subscriber_range_to_account: { destructiveHint: true },
+  /** Drops entries off a whitelist, so traffic that worked stops working. */
+  greenzone_whitelist_remove: { destructiveHint: true },
+  /**
+   * Charges the saved card off-session with no browser step and no human
+   * confirmation. Spending real money irreversibly is the thing an agent most
+   * needs warning about, whatever the scope says.
+   */
+  wallet_auto_topup: { destructiveHint: true },
+  // --- Idempotency corrections ---------------------------------------------
+  /**
+   * 'adapt' mode is additive, so calling twice charges twice. Explicitly not
+   * idempotent even though 'set' mode alone would be.
+   */
+  modify_subscriber_balance: { idempotentHint: false },
+  /** Same adapt/set split as the subscriber variant. */
+  modify_account_balance: { idempotentHint: false },
+  /** Starts a checkout session; each call creates a new one. */
+  wallet_topup_checkout: { idempotentHint: false },
+  // --- Read-only tools that are not idempotent -----------------------------
+  /**
+   * Approving a review is an admin state change, but it releases a payment
+   * rather than destroying anything.
+   */
+  radar_review_approve: { destructiveHint: false },
+  /**
+   * Admin-scoped but a documented no-op: Stripe exposes no API for Radar rule
+   * state, so this returns Dashboard instructions and changes nothing. Treated
+   * as read-only so an agent does not gate it behind a confirmation it does
+   * not need — and so it never reports the rule as toggled.
+   */
+  radar_rule_toggle: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true
+  }
+};
+function annotationsFor(name, scope, overrides = {}) {
+  return {
+    ...annotationsForScope(scope),
+    ...ANNOTATION_OVERRIDES[name] ?? {},
+    ...overrides
+  };
+}
+function installAnnotationDefaults(server2, scopes) {
+  const target = server2;
+  const original = target.registerTool.bind(target);
+  let wrapped = false;
+  target.registerTool = (name, config, ...rest) => {
+    wrapped = true;
+    const scope = scopes[name] ?? UNKNOWN_TOOL_SCOPE;
+    const declared = config?.annotations ?? {};
+    const merged = { ...annotationsFor(name, scope), ...declared };
+    return original(name, { ...config, annotations: merged }, ...rest);
+  };
+  return {
+    get wrapped() {
+      return wrapped;
+    }
+  };
+}
+var UNKNOWN_TOOL_SCOPE = "admin";
+
 // src/stripe-connect-tools.ts
 async function verifyConfirmToken(env, sub, toolName, token2) {
   const key = `confirm:${sub}:${toolName}`;
@@ -9853,6 +9979,18 @@ async function stripePost(stripeKey, path, params, connectedAccountId) {
   const data = await res.json();
   return { ok: res.ok, status: res.status, data };
 }
+var STRIPE_CONNECT_TOOL_SCOPES = {
+  stripe_connect_status: "read",
+  stripe_connect_payouts: "read",
+  stripe_connect_balance: "read",
+  stripe_connect_refund: "write",
+  stripe_connect_dispute_list: "read",
+  radar_review_list: "read",
+  radar_review_approve: "admin",
+  radar_review_decline: "admin",
+  radar_value_list_add: "admin",
+  radar_rule_toggle: "admin"
+};
 function registerStripeConnectTools(server2, ctx) {
   const { env, props: props2 } = ctx;
   const operatorId = props2.org_id ?? props2.sub;
@@ -9860,11 +9998,15 @@ function registerStripeConnectTools(server2, ctx) {
   async function getAccountId() {
     return env.CARRIER_USERS.get(kvKey);
   }
-  server2.tool(
+  server2.registerTool(
     "stripe_connect_status",
-    "Read-only: returns the Stripe Connect account status, capabilities, and requirements for the authenticated operator.",
     {
-      operator_id: z17.string().optional().describe("Override operator_id (admin use). Defaults to caller's org/user.")
+      title: "Stripe Connect Status",
+      description: "Read-only: returns the Stripe Connect account status, capabilities, and requirements for the authenticated operator.",
+      inputSchema: {
+        operator_id: z17.string().optional().describe("Override operator_id (admin use). Defaults to caller's org/user.")
+      },
+      annotations: annotationsFor("stripe_connect_status", "read")
     },
     async ({ operator_id }) => {
       const opId = operator_id ?? operatorId;
@@ -9908,12 +10050,16 @@ function registerStripeConnectTools(server2, ctx) {
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "stripe_connect_payouts",
-    "List money Stripe has already sent from the operator's connected account to their bank, newest first. Read-only. Params: `limit` (1-50, default 10), `status` (optional Stripe payout status, e.g. 'paid', 'pending', 'failed'). Returns: { payouts: [{ id, amount, currency, status, arrival_date, automatic, created }], has_more } \u2014 amount in the currency's smallest unit. Do NOT use this for money still sitting at Stripe and not yet paid out \u2014 use `stripe_connect_balance`.",
     {
-      limit: z17.number().int().min(1).max(50).default(10).describe("Number of payouts to return."),
-      status: z17.enum(["pending", "paid", "failed", "canceled", "in_transit"]).optional().describe("Filter by payout status.")
+      title: "List Stripe Payouts",
+      description: "List money Stripe has already sent from the operator's connected account to their bank, newest first. Read-only. Params: `limit` (1-50, default 10), `status` (optional Stripe payout status, e.g. 'paid', 'pending', 'failed'). Returns: { payouts: [{ id, amount, currency, status, arrival_date, automatic, created }], has_more } \u2014 amount in the currency's smallest unit. Do NOT use this for money still sitting at Stripe and not yet paid out \u2014 use `stripe_connect_balance`.",
+      inputSchema: {
+        limit: z17.number().int().min(1).max(50).default(10).describe("Number of payouts to return."),
+        status: z17.enum(["pending", "paid", "failed", "canceled", "in_transit"]).optional().describe("Filter by payout status.")
+      },
+      annotations: annotationsFor("stripe_connect_payouts", "read")
     },
     async ({ limit, status }) => {
       const start = Date.now();
@@ -9942,10 +10088,14 @@ function registerStripeConnectTools(server2, ctx) {
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "stripe_connect_balance",
-    "Read the money sitting in the operator's connected Stripe account: available and pending, split per currency. Params: none (the connected account is resolved from the session). Returns: { account_id, available: [{ amount, currency }], pending: [{ amount, currency }] } \u2014 amounts in the currency's smallest unit (cents for EUR/USD). Do NOT use this for the Carrier prepaid wallet \u2014 use `wallet_balance`. Do NOT use this for money already paid out to the bank \u2014 use `stripe_connect_payouts`.",
-    {},
+    {
+      title: "Stripe Connect Balance",
+      description: "Read the money sitting in the operator's connected Stripe account: available and pending, split per currency. Params: none (the connected account is resolved from the session). Returns: { account_id, available: [{ amount, currency }], pending: [{ amount, currency }] } \u2014 amounts in the currency's smallest unit (cents for EUR/USD). Do NOT use this for the Carrier prepaid wallet \u2014 use `wallet_balance`. Do NOT use this for money already paid out to the bank \u2014 use `stripe_connect_payouts`.",
+      inputSchema: {},
+      annotations: annotationsFor("stripe_connect_balance", "read")
+    },
     async () => {
       const start = Date.now();
       try {
@@ -9975,14 +10125,18 @@ function registerStripeConnectTools(server2, ctx) {
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "stripe_connect_refund",
-    "Refund money to a customer on one charge in the operator's connected Stripe account. This returns real funds and Stripe cannot reverse a refund once issued. Two-step by design: call without `confirm_token` to get a token and a summary of what would be refunded, then call again with that token to execute. The token expires in 5 minutes. Params: `charge_id` (Stripe charge id, `ch_...`), `amount_cents` (optional integer in the charge's smallest currency unit \u2014 omit for a full refund), `reason` ('duplicate' | 'fraudulent' | 'requested_by_customer', optional), `confirm_token`. Returns: the refund id and status. Requires `write` scope. Do NOT use this to stop a charge that has not settled yet \u2014 decline it with `radar_review_decline`. Do NOT use this to contest a chargeback \u2014 read the case with `stripe_connect_dispute_list` first, since refunding a disputed charge can cost the operator twice.",
     {
-      charge_id: z17.string().min(1).describe("Stripe charge ID (ch_...)."),
-      amount_cents: z17.number().int().min(1).optional().describe("Partial refund amount in cents. Omit for full refund."),
-      reason: z17.enum(["duplicate", "fraudulent", "requested_by_customer"]).optional(),
-      confirm_token: z17.string().optional().describe("Confirmation token from previous call. Required to execute.")
+      title: "Refund a Charge (moves real money)",
+      description: "Refund money to a customer on one charge in the operator's connected Stripe account. This returns real funds and Stripe cannot reverse a refund once issued. Two-step by design: call without `confirm_token` to get a token and a summary of what would be refunded, then call again with that token to execute. The token expires in 5 minutes. Params: `charge_id` (Stripe charge id, `ch_...`), `amount_cents` (optional integer in the charge's smallest currency unit \u2014 omit for a full refund), `reason` ('duplicate' | 'fraudulent' | 'requested_by_customer', optional), `confirm_token`. Returns: the refund id and status. Requires `write` scope. Do NOT use this to stop a charge that has not settled yet \u2014 decline it with `radar_review_decline`. Do NOT use this to contest a chargeback \u2014 read the case with `stripe_connect_dispute_list` first, since refunding a disputed charge can cost the operator twice.",
+      inputSchema: {
+        charge_id: z17.string().min(1).describe("Stripe charge ID (ch_...)."),
+        amount_cents: z17.number().int().min(1).optional().describe("Partial refund amount in cents. Omit for full refund."),
+        reason: z17.enum(["duplicate", "fraudulent", "requested_by_customer"]).optional(),
+        confirm_token: z17.string().optional().describe("Confirmation token from previous call. Required to execute.")
+      },
+      annotations: annotationsFor("stripe_connect_refund", "write")
     },
     async ({ charge_id, amount_cents, reason, confirm_token }) => {
       const start = Date.now();
@@ -10025,12 +10179,16 @@ Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "stripe_connect_dispute_list",
-    "List chargebacks customers have raised with their bank against the operator's connected Stripe account. Read-only \u2014 responding to one is Dashboard work. Params: `limit` (1-50, default 10), `status` (optional Stripe dispute status, e.g. 'needs_response', 'under_review'). Returns: { disputes: [{ id, charge, amount, currency, status, reason, evidence_details.due_by }], has_more } \u2014 amount in the currency's smallest unit, `due_by` a Unix timestamp or null. Do NOT use this for charges Stripe is holding for fraud review before they settle \u2014 those are `radar_review_list`. Check this before refunding: refunding a disputed charge can cost the operator the amount twice.",
     {
-      limit: z17.number().int().min(1).max(50).default(10),
-      status: z17.string().optional().describe("Filter by dispute status (e.g. needs_response, under_review).")
+      title: "List Chargeback Disputes",
+      description: "List chargebacks customers have raised with their bank against the operator's connected Stripe account. Read-only \u2014 responding to one is Dashboard work. Params: `limit` (1-50, default 10), `status` (optional Stripe dispute status, e.g. 'needs_response', 'under_review'). Returns: { disputes: [{ id, charge, amount, currency, status, reason, evidence_details.due_by }], has_more } \u2014 amount in the currency's smallest unit, `due_by` a Unix timestamp or null. Do NOT use this for charges Stripe is holding for fraud review before they settle \u2014 those are `radar_review_list`. Check this before refunding: refunding a disputed charge can cost the operator the amount twice.",
+      inputSchema: {
+        limit: z17.number().int().min(1).max(50).default(10),
+        status: z17.string().optional().describe("Filter by dispute status (e.g. needs_response, under_review).")
+      },
+      annotations: annotationsFor("stripe_connect_dispute_list", "read")
     },
     async ({ limit, status }) => {
       const start = Date.now();
@@ -10059,12 +10217,16 @@ Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "radar_review_list",
-    "List the Stripe Radar fraud reviews waiting on a manual approve/decline decision, newest first. Reads only \u2014 deciding a review is a separate call. Params: `open_only` (boolean, default true \u2014 false also returns already-decided reviews), `limit` (1-50, default 10). Returns: { reviews: [{ id (`prv_...`), charge, reason, opened_reason, closed_reason, created, closed }], has_more }. Call this first to get the `review_id` that `radar_review_approve` and `radar_review_decline` require. Do NOT use this for chargebacks the customer has already raised with their bank \u2014 use `stripe_connect_dispute_list`.",
     {
-      open_only: z17.boolean().default(true).describe("If true, only returns open (undecided) reviews."),
-      limit: z17.number().int().min(1).max(50).default(10)
+      title: "List Radar Fraud Reviews",
+      description: "List the Stripe Radar fraud reviews waiting on a manual approve/decline decision, newest first. Reads only \u2014 deciding a review is a separate call. Params: `open_only` (boolean, default true \u2014 false also returns already-decided reviews), `limit` (1-50, default 10). Returns: { reviews: [{ id (`prv_...`), charge, reason, opened_reason, closed_reason, created, closed }], has_more }. Call this first to get the `review_id` that `radar_review_approve` and `radar_review_decline` require. Do NOT use this for chargebacks the customer has already raised with their bank \u2014 use `stripe_connect_dispute_list`.",
+      inputSchema: {
+        open_only: z17.boolean().default(true).describe("If true, only returns open (undecided) reviews."),
+        limit: z17.number().int().min(1).max(50).default(10)
+      },
+      annotations: annotationsFor("radar_review_list", "read")
     },
     async ({ open_only, limit }) => {
       const start = Date.now();
@@ -10091,12 +10253,16 @@ Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "radar_review_approve",
-    "Clear a Stripe Radar fraud review so the held charge is captured and the money is taken. Approving overrides Radar's fraud signal, so a genuinely fraudulent charge approved here usually returns later as a chargeback plus a fee. Two-step by design: call without `confirm_token` to get a token, then call again with it to execute. Params: `review_id` (`prv_...`, from `radar_review_list`), `confirm_token`. Requires `admin` scope. Do NOT call this to block a suspicious charge \u2014 that is `radar_review_decline`, the opposite outcome. Do NOT call this to return money on a charge that already went through \u2014 that is `stripe_connect_refund`.",
     {
-      review_id: z17.string().min(1).describe("Stripe Radar review ID (prv_...)."),
-      confirm_token: z17.string().optional()
+      title: "Approve Radar Review (captures charge)",
+      description: "Clear a Stripe Radar fraud review so the held charge is captured and the money is taken. Approving overrides Radar's fraud signal, so a genuinely fraudulent charge approved here usually returns later as a chargeback plus a fee. Two-step by design: call without `confirm_token` to get a token, then call again with it to execute. Params: `review_id` (`prv_...`, from `radar_review_list`), `confirm_token`. Requires `admin` scope. Do NOT call this to block a suspicious charge \u2014 that is `radar_review_decline`, the opposite outcome. Do NOT call this to return money on a charge that already went through \u2014 that is `stripe_connect_refund`.",
+      inputSchema: {
+        review_id: z17.string().min(1).describe("Stripe Radar review ID (prv_...)."),
+        confirm_token: z17.string().optional()
+      },
+      annotations: annotationsFor("radar_review_approve", "admin")
     },
     async ({ review_id, confirm_token }) => {
       const toolName = "radar_review_approve";
@@ -10136,12 +10302,16 @@ Call again with confirm_token="${token2}" to execute. Expires in 5 minutes.`
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "radar_review_decline",
-    "Close a Stripe Radar fraud review as fraudulent, so the held charge is blocked and the customer is never billed. The customer sees a failed payment; if they were legitimate, they have to pay again. Two-step by design: call without `confirm_token` to get a token, then call again with it to execute. Params: `review_id` (`prv_...`, from `radar_review_list`), `confirm_token`. Requires `admin` scope. Do NOT call this to let a charge through \u2014 that is `radar_review_approve`, the opposite outcome. Do NOT call this on a charge that already succeeded; a review only exists while the charge is held, and returning settled money is `stripe_connect_refund`.",
     {
-      review_id: z17.string().min(1),
-      confirm_token: z17.string().optional()
+      title: "Decline Radar Review (blocks charge)",
+      description: "Close a Stripe Radar fraud review as fraudulent, so the held charge is blocked and the customer is never billed. The customer sees a failed payment; if they were legitimate, they have to pay again. Two-step by design: call without `confirm_token` to get a token, then call again with it to execute. Params: `review_id` (`prv_...`, from `radar_review_list`), `confirm_token`. Requires `admin` scope. Do NOT call this to let a charge through \u2014 that is `radar_review_approve`, the opposite outcome. Do NOT call this on a charge that already succeeded; a review only exists while the charge is held, and returning settled money is `stripe_connect_refund`.",
+      inputSchema: {
+        review_id: z17.string().min(1),
+        confirm_token: z17.string().optional()
+      },
+      annotations: annotationsFor("radar_review_decline", "admin")
     },
     async ({ review_id, confirm_token }) => {
       const toolName = "radar_review_decline";
@@ -10181,13 +10351,17 @@ Expires in 5 minutes.`
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "radar_value_list_add",
-    "Add one value to an existing Stripe Radar value list, changing how every future charge is scored. Whether the value ends up blocked or allowed depends entirely on which list you name in `value_list_id` \u2014 this tool does not choose, and putting a value on the allow list when you meant the block list silently lets fraud through. Confirm the list's purpose before calling. Two-step by design: call without `confirm_token` to get a token, then call again with it to execute. Params: `value_list_id` (`rsl_...`, an existing list), `value` (one email, IP address, card fingerprint, or ISO country code \u2014 one item per call), `confirm_token`. Requires `admin` scope. Do NOT use this to decide a single charge that is already under review \u2014 use `radar_review_approve` or `radar_review_decline`. Do NOT use this to create a list or a rule: only `value` is added, and rules cannot be edited through this API at all (see `radar_rule_toggle`).",
     {
-      value_list_id: z17.string().min(1).describe("Stripe Radar value list ID (rsl_...)."),
-      value: z17.string().min(1).describe("The value to add (email, IP address, country code, etc.)."),
-      confirm_token: z17.string().optional()
+      title: "Add Value to Radar List",
+      description: "Add one value to an existing Stripe Radar value list, changing how every future charge is scored. Whether the value ends up blocked or allowed depends entirely on which list you name in `value_list_id` \u2014 this tool does not choose, and putting a value on the allow list when you meant the block list silently lets fraud through. Confirm the list's purpose before calling. Two-step by design: call without `confirm_token` to get a token, then call again with it to execute. Params: `value_list_id` (`rsl_...`, an existing list), `value` (one email, IP address, card fingerprint, or ISO country code \u2014 one item per call), `confirm_token`. Requires `admin` scope. Do NOT use this to decide a single charge that is already under review \u2014 use `radar_review_approve` or `radar_review_decline`. Do NOT use this to create a list or a rule: only `value` is added, and rules cannot be edited through this API at all (see `radar_rule_toggle`).",
+      inputSchema: {
+        value_list_id: z17.string().min(1).describe("Stripe Radar value list ID (rsl_...)."),
+        value: z17.string().min(1).describe("The value to add (email, IP address, country code, etc.)."),
+        confirm_token: z17.string().optional()
+      },
+      annotations: annotationsFor("radar_value_list_add", "admin")
     },
     async ({ value_list_id, value, confirm_token }) => {
       const toolName = "radar_value_list_add";
@@ -10227,12 +10401,16 @@ Expires in 5 minutes.`
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "radar_rule_toggle",
-    "Return the Stripe Dashboard steps for enabling or disabling a Radar rule. This tool changes nothing: Stripe has no public API for rule state, so the call always succeeds and the rule stays exactly as it was. Never report the rule as toggled. Params: `rule_id` (Stripe Radar rule id), `enabled` (true for the enable instructions, false for disable). Returns: the Dashboard URL and steps for a human to follow. Requires `admin` scope. Do NOT use this when a change must actually take effect from an agent \u2014 the only Radar state reachable through this API is value-list membership, via `radar_value_list_add`.",
     {
-      rule_id: z17.string().min(1).describe("Stripe Radar rule ID."),
-      enabled: z17.boolean().describe("true = enable, false = disable.")
+      title: "Radar Rule Toggle (instructions only)",
+      description: "Return the Stripe Dashboard steps for enabling or disabling a Radar rule. This tool changes nothing: Stripe has no public API for rule state, so the call always succeeds and the rule stays exactly as it was. Never report the rule as toggled. Params: `rule_id` (Stripe Radar rule id), `enabled` (true for the enable instructions, false for disable). Returns: the Dashboard URL and steps for a human to follow. Requires `admin` scope. Do NOT use this when a change must actually take effect from an agent \u2014 the only Radar state reachable through this API is value-list membership, via `radar_value_list_add`.",
+      inputSchema: {
+        rule_id: z17.string().min(1).describe("Stripe Radar rule ID."),
+        enabled: z17.boolean().describe("true = enable, false = disable.")
+      },
+      annotations: annotationsFor("radar_rule_toggle", "admin")
     },
     async ({ rule_id, enabled }) => {
       return ok2(
@@ -10503,6 +10681,11 @@ async function runAutoTopup(env, args) {
     };
   }
 }
+var WALLET_TOOL_SCOPES = {
+  wallet_balance: "read",
+  wallet_topup_checkout: "write",
+  wallet_auto_topup: "write"
+};
 function ok3(text) {
   return { content: [{ type: "text", text }] };
 }
@@ -10512,10 +10695,14 @@ function err3(text) {
 function registerWalletTools(server2, ctx) {
   const { env, props: props2 } = ctx;
   const defaultOrgId = props2.org_id ?? props2.sub;
-  server2.tool(
+  server2.registerTool(
     "wallet_balance",
-    "Read the caller organisation's Carrier prepaid wallet: current balance and auto-top-up settings. The wallet is what Carrier bills your own eSIM spend against \u2014 it is not an OCS balance and not your MCP plan credits. Params: none (the organisation is taken from the session). Returns: { org_id, balance_eur_cents, auto_topup_enabled, auto_topup_threshold_cents, auto_topup_pack_cents } \u2014 all amounts in EUR cents, not euros. Do NOT use this for a reseller account balance in OCS \u2014 use `get_reseller_info` or `list_reseller_accounts`. Do NOT use this for a subscriber's OCS balance \u2014 use `get_subscriber`. Do NOT use this for MCP plan credits \u2014 use `credit_balance`. Do NOT use this for money held at Stripe \u2014 use `stripe_connect_balance`.",
-    {},
+    {
+      title: "Wallet Balance",
+      description: "Read the caller organisation's Carrier prepaid wallet: current balance and auto-top-up settings. The wallet is what Carrier bills your own eSIM spend against \u2014 it is not an OCS balance and not your MCP plan credits. Params: none (the organisation is taken from the session). Returns: { org_id, balance_eur_cents, auto_topup_enabled, auto_topup_threshold_cents, auto_topup_pack_cents } \u2014 all amounts in EUR cents, not euros. Do NOT use this for a reseller account balance in OCS \u2014 use `get_reseller_info` or `list_reseller_accounts`. Do NOT use this for a subscriber's OCS balance \u2014 use `get_subscriber`. Do NOT use this for MCP plan credits \u2014 use `credit_balance`. Do NOT use this for money held at Stripe \u2014 use `stripe_connect_balance`.",
+      inputSchema: {},
+      annotations: annotationsFor("wallet_balance", "read")
+    },
     async () => {
       const orgId = defaultOrgId;
       const start = Date.now();
@@ -10546,13 +10733,17 @@ function registerWalletTools(server2, ctx) {
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "wallet_topup_checkout",
-    "Create a Stripe Checkout link so a human can top up the Carrier prepaid wallet by card. This tool charges nothing itself: it returns a hosted URL, and the wallet is credited (pack amount + bonus) only after someone completes the payment in a browser. Params: `pack` (optional \u2014 pack id `pack_500`/`pack_1000`/`pack_2500`/`pack_5000`, or an exact EUR-cents amount matching a catalog pack; omit to list the packs and their bonuses without creating a session). Returns: { pack_id, pack_eur_cents, bonus_eur_cents, checkout_session_id, checkout_url } \u2014 amounts in EUR cents. Do NOT use this when the wallet must be funded now with no human in the loop \u2014 use `wallet_auto_topup`, which charges the saved card immediately. Do NOT use this to move money in OCS \u2014 `modify_account_balance` and `modify_subscriber_balance` are unrelated ledgers.",
     {
-      pack: z18.string().optional().describe(
-        "Pack id (pack_500/pack_1000/pack_2500/pack_5000) or exact EUR-cents amount. Omit to list packs."
-      )
+      title: "Wallet Top-up Checkout",
+      description: "Create a Stripe Checkout link so a human can top up the Carrier prepaid wallet by card. This tool charges nothing itself: it returns a hosted URL, and the wallet is credited (pack amount + bonus) only after someone completes the payment in a browser. Params: `pack` (optional \u2014 pack id `pack_500`/`pack_1000`/`pack_2500`/`pack_5000`, or an exact EUR-cents amount matching a catalog pack; omit to list the packs and their bonuses without creating a session). Returns: { pack_id, pack_eur_cents, bonus_eur_cents, checkout_session_id, checkout_url } \u2014 amounts in EUR cents. Do NOT use this when the wallet must be funded now with no human in the loop \u2014 use `wallet_auto_topup`, which charges the saved card immediately. Do NOT use this to move money in OCS \u2014 `modify_account_balance` and `modify_subscriber_balance` are unrelated ledgers.",
+      inputSchema: {
+        pack: z18.string().optional().describe(
+          "Pack id (pack_500/pack_1000/pack_2500/pack_5000) or exact EUR-cents amount. Omit to list packs."
+        )
+      },
+      annotations: annotationsFor("wallet_topup_checkout", "write")
     },
     async ({ pack }) => {
       const orgId = defaultOrgId;
@@ -10603,11 +10794,15 @@ function registerWalletTools(server2, ctx) {
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "wallet_auto_topup",
-    "Charge the organisation's saved card off-session, right now, and credit the Carrier prepaid wallet with the pack. This spends real money without any browser step or human confirmation, so only call it when the user has asked to be charged. Params: `pack_cents` (optional integer, EUR cents \u2014 must match a catalog pack; omit to use the organisation's configured auto-top-up pack). Returns on success: { org_id, charged: true, credited_eur_cents, balance_after_cents, payment_intent_id } \u2014 amounts in EUR cents. Returns { charged: false, reason } as an error when the card declines or no payment method is saved. Do NOT use this to let a human pay in a browser \u2014 use `wallet_topup_checkout`, which only returns a link. Do NOT use this to change the threshold that triggers automatic top-ups; this tool performs one charge and does not edit the configuration. Do NOT use this to credit an OCS reseller account or subscriber \u2014 see `modify_account_balance` and `modify_subscriber_balance`.",
     {
-      pack_cents: z18.number().int().positive().optional().describe("Override pack amount in EUR cents (must match a catalog pack).")
+      title: "Wallet Auto Top-up (charges card now)",
+      description: "Charge the organisation's saved card off-session, right now, and credit the Carrier prepaid wallet with the pack. This spends real money without any browser step or human confirmation, so only call it when the user has asked to be charged. Params: `pack_cents` (optional integer, EUR cents \u2014 must match a catalog pack; omit to use the organisation's configured auto-top-up pack). Returns on success: { org_id, charged: true, credited_eur_cents, balance_after_cents, payment_intent_id } \u2014 amounts in EUR cents. Returns { charged: false, reason } as an error when the card declines or no payment method is saved. Do NOT use this to let a human pay in a browser \u2014 use `wallet_topup_checkout`, which only returns a link. Do NOT use this to change the threshold that triggers automatic top-ups; this tool performs one charge and does not edit the configuration. Do NOT use this to credit an OCS reseller account or subscriber \u2014 see `modify_account_balance` and `modify_subscriber_balance`.",
+      inputSchema: {
+        pack_cents: z18.number().int().positive().optional().describe("Override pack amount in EUR cents (must match a catalog pack).")
+      },
+      annotations: annotationsFor("wallet_auto_topup", "write")
     },
     async ({ pack_cents }) => {
       const orgId = defaultOrgId;
@@ -11155,16 +11350,23 @@ function registerUiAgentGenericTools(server2, _ctx) {
 
 // src/tools-storefront-logo.ts
 import { z as z21 } from "zod";
+var STOREFRONT_LOGO_TOOL_SCOPES = {
+  generate_storefront_logo: "read"
+};
 var ok5 = (text) => ({ content: [{ type: "text", text }] });
 var err5 = (text) => ({ isError: true, content: [{ type: "text", text }] });
 function registerStorefrontLogoTools(server2, env = {}) {
-  server2.tool(
+  server2.registerTool(
     "generate_storefront_logo",
-    "Generate a storefront logo (SVG always; PNG when an image key is configured on the Carrier worker). Works for any authenticated Carrier MCP user \u2014 no local image-API key required. Write the SVG to public/brand/logo.svg in the storefront.",
     {
-      name: z21.string().min(1).describe("Brand / shop name, e.g. Bananas"),
-      accent: z21.string().regex(/^#?[0-9A-Fa-f]{6}$/).optional().describe("Accent hex, e.g. #FF8A00"),
-      tagline: z21.string().optional().describe("Optional tagline for AI-enhanced marks")
+      title: "Generate Storefront Logo",
+      description: "Generate a storefront logo (SVG always; PNG when an image key is configured on the Carrier worker). Works for any authenticated Carrier MCP user \u2014 no local image-API key required. Write the SVG to public/brand/logo.svg in the storefront.",
+      inputSchema: {
+        name: z21.string().min(1).describe("Brand / shop name, e.g. Bananas"),
+        accent: z21.string().regex(/^#?[0-9A-Fa-f]{6}$/).optional().describe("Accent hex, e.g. #FF8A00"),
+        tagline: z21.string().optional().describe("Optional tagline for AI-enhanced marks")
+      },
+      annotations: annotationsFor("generate_storefront_logo", "read")
     },
     async ({ name, accent, tagline }) => {
       try {
@@ -11195,16 +11397,25 @@ function registerStorefrontLogoTools(server2, env = {}) {
 
 // src/tools-storefront-deploy.ts
 import { z as z22 } from "zod";
+var STOREFRONT_DEPLOY_TOOL_SCOPES = {
+  list_deploy_targets: "read",
+  deploy_storefront: "write",
+  provision_storefront_clerk: "write"
+};
 var ok6 = (value) => ({
   content: [{ type: "text", text: JSON.stringify(value) }]
 });
 var err6 = (text) => ({ isError: true, content: [{ type: "text", text }] });
 function registerStorefrontDeployTools(server2) {
-  server2.tool(
+  server2.registerTool(
     "list_deploy_targets",
-    "Report which storefront deploy hosts (Cloudflare, Vercel, Netlify, Fly) are installed, logged in, and ready on this machine, and which one a deploy would pick.",
     {
-      dir: z22.string().min(1).describe("Path to the scaffolded storefront directory")
+      title: "List Deploy Targets",
+      description: "Report which storefront deploy hosts (Cloudflare, Vercel, Netlify, Fly) are installed, logged in, and ready on this machine, and which one a deploy would pick.",
+      inputSchema: {
+        dir: z22.string().min(1).describe("Path to the scaffolded storefront directory")
+      },
+      annotations: annotationsFor("list_deploy_targets", "read")
     },
     async ({ dir }) => {
       try {
@@ -11220,17 +11431,21 @@ function registerStorefrontDeployTools(server2) {
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "deploy_storefront",
-    "Build and deploy a scaffolded storefront to whichever host is available on this machine, then push its runtime secrets (CARRIER_API_KEY, CLERK_SECRET_KEY) to that host.",
     {
-      dir: z22.string().min(1).describe("Path to the scaffolded storefront directory"),
-      target: z22.enum(TARGET_IDS).optional().describe("Force a host instead of auto-detecting"),
-      name: z22.string().optional().describe("Project/worker name (defaults from brand)"),
-      skip_build: z22.boolean().optional().describe("Deploy the existing build without rebuilding"),
-      push_secrets: z22.boolean().optional().describe("Stage runtime secrets on the host before deploy (default true)"),
-      verify: z22.boolean().optional().describe("Probe the deployed URL and report whether it actually serves (default true)"),
-      domain: z22.boolean().optional().describe("Route the brand domain to the deployment (Cloudflare provisions DNS + cert)")
+      title: "Deploy Storefront",
+      description: "Build and deploy a scaffolded storefront to whichever host is available on this machine, then push its runtime secrets (CARRIER_API_KEY, CLERK_SECRET_KEY) to that host.",
+      inputSchema: {
+        dir: z22.string().min(1).describe("Path to the scaffolded storefront directory"),
+        target: z22.enum(TARGET_IDS).optional().describe("Force a host instead of auto-detecting"),
+        name: z22.string().optional().describe("Project/worker name (defaults from brand)"),
+        skip_build: z22.boolean().optional().describe("Deploy the existing build without rebuilding"),
+        push_secrets: z22.boolean().optional().describe("Stage runtime secrets on the host before deploy (default true)"),
+        verify: z22.boolean().optional().describe("Probe the deployed URL and report whether it actually serves (default true)"),
+        domain: z22.boolean().optional().describe("Route the brand domain to the deployment (Cloudflare provisions DNS + cert)")
+      },
+      annotations: annotationsFor("deploy_storefront", "write")
     },
     async ({ dir, target, name, skip_build, push_secrets, verify, domain }) => {
       try {
@@ -11270,15 +11485,19 @@ function registerStorefrontDeployTools(server2) {
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "provision_storefront_clerk",
-    "Create a Clerk application (Platform API) or reuse Clerk keys already on this machine, write them into the storefront .env.local, and configure allowed origins and redirect URLs on the instance.",
     {
-      dir: z22.string().min(1).describe("Path to the scaffolded storefront directory"),
-      name: z22.string().optional().describe("Clerk application name (defaults from brand)"),
-      production: z22.boolean().optional().describe("Also create a production instance (Platform API only)"),
-      no_create: z22.boolean().optional().describe("Never create a new application; only reuse existing keys"),
-      url: z22.string().optional().describe("Deployed URL to whitelist as origin and redirect")
+      title: "Provision Storefront Clerk App",
+      description: "Create a Clerk application (Platform API) or reuse Clerk keys already on this machine, write them into the storefront .env.local, and configure allowed origins and redirect URLs on the instance.",
+      inputSchema: {
+        dir: z22.string().min(1).describe("Path to the scaffolded storefront directory"),
+        name: z22.string().optional().describe("Clerk application name (defaults from brand)"),
+        production: z22.boolean().optional().describe("Also create a production instance (Platform API only)"),
+        no_create: z22.boolean().optional().describe("Never create a new application; only reuse existing keys"),
+        url: z22.string().optional().describe("Deployed URL to whitelist as origin and redirect")
+      },
+      annotations: annotationsFor("provision_storefront_clerk", "write")
     },
     async ({ dir, name, production, no_create, url }) => {
       try {
@@ -11325,6 +11544,76 @@ function registerStorefrontDeployTools(server2) {
   );
 }
 
+// src/tool-registry.ts
+var INTELLIGENCE_TOOL_SCOPES = {
+  diagnose_subscriber: "read",
+  fleet_health: "read",
+  detect_usage_anomalies: "read",
+  optimize_package: "read",
+  churn_risk: "read",
+  audit_network_coverage: "read",
+  marketing_intelligence: "read",
+  high_cost_subscribers: "read"
+};
+var UI_AGENT_GENERIC_TOOL_SCOPES = {
+  ui_agent_ask: "write",
+  ui_agent_status: "read"
+};
+var GREENZONE_TOOL_SCOPES = {
+  greenzone_whitelist_add: "write",
+  greenzone_whitelist_remove: "write",
+  greenzone_whitelist_list: "read"
+};
+var OPS_TOOL_SCOPES = {
+  list_recent_ocs_events: "read",
+  rate_limit_status: "read",
+  subscriber_country_history: "read",
+  subscriber_depletion_events: "read"
+};
+var APP_TOOL_SCOPES = {
+  fleet_health_app: "read",
+  provision_esim_wizard: "write",
+  balance_topup_form: "admin"
+};
+var CARRIER_ASK_TOOL_SCOPES = {
+  carrier_ask: "read",
+  carrier_ask_describe: "read"
+};
+var STRIPE_PROXY_TOOL_SCOPES = {
+  stripe_proxy_call: "write"
+};
+function scopesFromToolDefs(tools) {
+  return Object.fromEntries(tools.map((t) => [t.name, t.scope]));
+}
+var PRICING_TOOL_SCOPES = scopesFromToolDefs(PRICING_TOOLS);
+var PROJECTS_TOOL_SCOPES = scopesFromToolDefs(PROJECTS_TOOLS);
+var ALL_TOOL_SCOPES = Object.freeze({
+  ...TOOL_SCOPES,
+  ...BACKLOG_TOOL_SCOPES,
+  ...INTELLIGENCE_TOOL_SCOPES,
+  ...OPS_TOOL_SCOPES,
+  ...PRICING_TOOL_SCOPES,
+  ...PROJECTS_TOOL_SCOPES,
+  ...APP_TOOL_SCOPES,
+  ...UI_AGENT_TOOL_SCOPES,
+  ...UI_AGENT_ASK_TOOL_SCOPES,
+  ...UI_AGENT_SCHEDULE_TOOL_SCOPES,
+  ...UI_AGENT_GENERIC_TOOL_SCOPES,
+  ...WALLET_TOOL_SCOPES,
+  ...STRIPE_CONNECT_TOOL_SCOPES,
+  ...GREENZONE_TOOL_SCOPES,
+  ...CARRIER_ASK_TOOL_SCOPES,
+  ...STRIPE_PROXY_TOOL_SCOPES,
+  ...STOREFRONT_LOGO_TOOL_SCOPES,
+  // Storefront deploy tools exist only in this package, not in the Worker.
+  ...STOREFRONT_DEPLOY_TOOL_SCOPES
+});
+var TOOL_REGISTRY2 = new Set(Object.keys(ALL_TOOL_SCOPES));
+var UNREGISTERED_TOOLS = /* @__PURE__ */ new Set(["stripe_proxy_call"]);
+var REGISTERED_TOOL_COUNT = Object.keys(ALL_TOOL_SCOPES).filter(
+  (name) => !UNREGISTERED_TOOLS.has(name)
+).length;
+
 // src/index.ts
 var baseUrl = process.env.CARRIER_OCS_BASE_URL ?? process.env.ESIMVAULT_BASE_URL ?? "https://ocs.esimvault.cloud";
 var token = process.env.CARRIER_OCS_API_TOKEN ?? process.env.ESIMVAULT_API_TOKEN;
@@ -11375,6 +11664,7 @@ var server = new McpServer(
     instructions: "Carrier MCP \u2014 single-user stdio mode. Full tool registry (mirrors the deployed Worker)."
   }
 );
+installAnnotationDefaults(server, ALL_TOOL_SCOPES);
 registerAllTools(server, toolCtx);
 registerIntelligenceTools(server, toolCtx);
 registerAllBacklogTools(server, toolCtx);