@usethrottle/mcp 0.2.0 → 0.2.2

package/dist/mcp.js

@@ -9,6 +9,7 @@ var ThrottleError = class extends Error {
   statusCode;
   details;
   body;
+  requestId;
   constructor(args) {
     super(args.message);
     this.name = "ThrottleError";
@@ -16,14 +17,17 @@ var ThrottleError = class extends Error {
     this.statusCode = args.statusCode;
     this.details = args.details;
     this.body = args.body;
+    const fromBody = args.body?.meta?.requestId;
+    const fromHeader = typeof args.responseHeaders?.get === "function" ? args.responseHeaders.get("x-request-id") : args.responseHeaders?.["x-request-id"];
+    this.requestId = args.requestId ?? (typeof fromBody === "string" ? fromBody : void 0) ?? (typeof fromHeader === "string" ? fromHeader : void 0);
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
 
 // src/client.ts
 var ThrottleApiError = class extends ThrottleError {
-  constructor(code, message, statusCode, details) {
-    super({ code, message, statusCode, details });
+  constructor(code, message, statusCode, details, responseHeaders) {
+    super({ code, message, statusCode, details, responseHeaders });
     this.name = "ThrottleApiError";
   }
 };
@@ -37,18 +41,43 @@ function buildQuery(query) {
   const qs = params.toString();
   return qs ? `?${qs}` : "";
 }
+var API_KEY_PREFIX_RE = /^(sk_|pk_)/;
 var ThrottleClient = class {
   constructor(auth, fetchImpl = fetch) {
     this.auth = auth;
     this.fetchImpl = fetchImpl;
   }
+  /**
+   * Swap the credential every later request is sent with. The hosted remote
+   * server builds one client per MCP session at `initialize`, but an OAuth
+   * access token lives one hour and the MCP client refreshes it underneath
+   * the session — each request then arrives with a newer bearer than the one
+   * the session was opened with. Without this, the session keeps calling the
+   * REST API with the token it was born with and every tool fails with a 401
+   * the moment that first token expires, even though the caller is still
+   * perfectly authenticated.
+   */
+  setApiKey(apiKey) {
+    this.auth = { ...this.auth, apiKey };
+  }
   async requestJson(method, path, options = {}) {
     const url = `${this.auth.apiBaseUrl.replace(/\/$/, "")}${path}${buildQuery(options.query)}`;
     const headers = {
       "content-type": "application/json",
-      "x-api-key": this.auth.apiKey
+      "x-api-key": this.auth.apiKey,
+      // Also sent as Authorization: Bearer — required for an OAuth access
+      // token (the remote server's oauth_token sessions), which the auth
+      // middleware only ever recognizes via this header (peeked by issuer),
+      // never via x-api-key. For an sk_/pk_ key this is a no-op: the
+      // middleware already treats `Authorization: Bearer sk_.../pk_...`
+      // identically to `X-API-Key`, so existing stdio-CLI callers are
+      // unaffected.
+      Authorization: `Bearer ${this.auth.apiKey}`
     };
     if (options.idempotencyKey) headers["idempotency-key"] = options.idempotencyKey;
+    if (options.applicationId && !API_KEY_PREFIX_RE.test(this.auth.apiKey)) {
+      headers["x-throttle-application-id"] = options.applicationId;
+    }
     const sendsBody = method === "POST" || method === "PATCH" || method === "PUT";
     const body = options.body !== void 0 ? JSON.stringify(options.body) : sendsBody ? "{}" : void 0;
     const res = await this.fetchImpl(url, { method, headers, body });
@@ -64,18 +93,19 @@ var ThrottleClient = class {
         err?.code ?? `http_${res.status}`,
         err?.message ?? `Request failed (${res.status}): ${text.slice(0, 200)}`,
         res.status,
-        err?.details
+        err?.details,
+        res.headers
       );
     }
     return parsed;
   }
   /** Unwraps the `{ data }` envelope. Key presence, not `??` — `{data: null}` unwraps to null. */
-  async get(path, query) {
-    const body = await this.requestJson("GET", path, { query });
+  async get(path, query, options) {
+    const body = await this.requestJson("GET", path, { query, applicationId: options?.applicationId });
     return body && typeof body === "object" && "data" in body ? body.data : body;
   }
-  async list(path, query) {
-    const body = await this.requestJson("GET", path, { query });
+  async list(path, query, options) {
+    const body = await this.requestJson("GET", path, { query, applicationId: options?.applicationId });
     const data = "data" in body ? body.data : body;
     const meta = body.meta;
     return { data: Array.isArray(data) ? data : [], pagination: meta?.pagination ?? null };
@@ -84,6 +114,10 @@ var ThrottleClient = class {
     const body = await this.requestJson("POST", path, options);
     return body && typeof body === "object" && "data" in body ? body.data : body;
   }
+  async patch(path, options = {}) {
+    const body = await this.requestJson("PATCH", path, options);
+    return body && typeof body === "object" && "data" in body ? body.data : body;
+  }
 };
 async function optional(load) {
   try {
@@ -98,6 +132,7 @@ async function optional(load) {
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // ../core-scopes/src/scopes.ts
 function hasScope(granted, required) {
@@ -126,6 +161,8 @@ function add(group, resource, actions, labels, opts = {}) {
       staffOnly: opts.staffOnly ?? false,
       // publishable defaults false; only the curated set below is true
       publishableAllowed: opts.publishableAllowed ?? false,
+      // publishableOnly defaults false; only customer_accounts:write sets it
+      publishableOnly: opts.publishableOnly ?? false,
       // extension default true for commerce scopes; Taxonomy B passes false
       extensionAllowed: opts.extensionAllowed ?? true,
       implies
@@ -136,19 +173,36 @@ add("Orders", "orders", ["read", "write"], { read: "View orders", write: "Manage
 add("Quotes", "quotes", ["read", "write"], { read: "View quotes", write: "Manage quotes" });
 add("Orders", "order_cancellations", ["write"], { write: "Cancel orders" });
 add("Orders", "order_returns", ["read", "write"], { read: "View returns", write: "Process returns" });
+add("Orders", "order_comps", ["write"], { write: "Comp orders (write off the balance)" }, { sensitive: true });
+add("Orders", "order_holds", ["write"], { write: "Freeze and unfreeze orders" });
+add(
+  "Imports",
+  "imports",
+  ["read", "write"],
+  { read: "View data imports", write: "Run and undo data imports" },
+  { extensionAllowed: false }
+);
 add("Payments", "payments", ["read", "write"], { read: "View payments", write: "Create payments" });
 add("Payments", "payment_authorizations", ["write"], { write: "Authorize payments" });
 add("Payments", "payment_captures", ["write"], { write: "Capture payments" });
 add("Payments", "payment_refunds", ["read", "write"], { read: "View refunds", write: "Refund payments" }, { sensitive: true });
 add("Payments", "payment_voids", ["write"], { write: "Void payments" }, { sensitive: true });
+add("Payments", "payment_records", ["write"], { write: "Record payments received outside Throttle" }, { sensitive: true });
 add("Payments", "payment_disputes", ["read", "write"], { read: "View disputes", write: "Handle disputes" }, { sensitive: true });
 add("Payments", "payment_methods", ["read", "write"], { read: "View payment methods", write: "Tokenize payment methods" }, { sensitive: true });
 add("Customers", "customers", ["read", "write"], { read: "View customers", write: "Manage customers" });
 add("Customers", "customer_pii", ["read"], { read: "View customer PII" }, { sensitive: true });
 add("Customers", "customer_addresses", ["read", "write"], { read: "View addresses", write: "Manage addresses" });
 add("Customers", "customer_payment_methods", ["read", "write"], { read: "View stored cards", write: "Manage stored cards" }, { sensitive: true });
+add(
+  "Customer accounts",
+  "customer_accounts",
+  ["write"],
+  { write: "Let shoppers register, sign in and manage their account" },
+  { publishableAllowed: true, publishableOnly: true, extensionAllowed: false }
+);
 add("Carts", "carts", ["read", "write"], { read: "View carts", write: "Manage carts" });
-add("Carts", "cart_items", ["read", "write"], { read: "View line items", write: "Manage line items" });
+add("Carts", "cart_items", ["write"], { write: "Manage line items" });
 add("Carts", "checkout_sessions", ["read", "write"], { read: "View checkout sessions", write: "Manage checkout sessions" });
 add("Discounts", "discounts", ["read", "write"], { read: "View discounts", write: "Manage discounts" });
 add("Subscriptions", "subscriptions", ["read", "write"], { read: "View subscriptions", write: "Manage subscriptions" });
@@ -169,8 +223,32 @@ add("Shipping & Tax", "shipping_quotes", ["write"], { write: "Request shipping q
 add("Shipping & Tax", "tax_calculations", ["write"], { write: "Calculate tax" }, { publishableAllowed: true });
 add("Shipping & Tax", "shipping_tax_quote_tokens", ["read", "write"], { read: "View quote tokens", write: "Manage quote tokens" });
 add("Shipping & Tax", "shipping_tax_snapshots", ["write"], { write: "Accept external snapshots" });
+add(
+  "Scripts",
+  "storefront_scripts",
+  ["read", "write"],
+  {
+    read: "Load storefront scripts",
+    // `write` covers exactly one thing: reporting a script's own load outcome
+    // from the merchant's storefront, so the health panel stops being
+    // hosted-checkout-only. On checkout the session id in the URL is the
+    // capability that scopes that write; a storefront page has no session, so
+    // the pk it already holds is what scopes it instead. It writes nothing but
+    // load telemetry — authoring stays on `application_scripts:write`, which
+    // is not publishable-allowed.
+    write: "Report storefront script load outcomes"
+  },
+  { publishableAllowed: true }
+);
+add("Scripts", "application_scripts", ["read", "write"], {
+  read: "View merchant-authored scripts",
+  write: "Create, edit and disable merchant-authored scripts"
+}, { extensionAllowed: false });
+add("Scripts", "extension_scripts", ["read", "write"], {
+  read: "View an extension's buyer-facing scripts",
+  write: "Create, edit and delete an extension's buyer-facing scripts"
+}, { extensionAllowed: false });
 add("Connectors", "connectors", ["read", "write"], { read: "View connectors", write: "Manage connectors" });
-add("Connectors", "connector_activations", ["write"], { write: "Activate/deactivate connectors" });
 add("Webhooks & Events", "webhooks", ["read", "write"], { read: "View webhooks", write: "Manage webhooks" });
 add("Webhooks & Events", "webhook_deliveries", ["read", "write"], { read: "View deliveries", write: "Retry deliveries" });
 add("Webhooks & Events", "events", ["read"], { read: "View events" });
@@ -186,7 +264,7 @@ add("Platform billing", "billing", ["read", "write"], { read: "View billing", wr
 add("Platform billing", "billing_payment_methods", ["read", "write"], { read: "View billing cards", write: "Manage billing cards" }, HUMAN);
 add("Email", "email_templates", ["read", "write"], { read: "View email templates", write: "Edit email templates" }, HUMAN);
 add("Email", "email_settings", ["read", "write"], { read: "View email settings", write: "Edit email settings" }, HUMAN);
-add("Go-live", "go_live", ["read", "write"], { read: "View go-live status", write: "Submit go-live" }, HUMAN);
+add("Go-live", "go_live", ["write"], { write: "Submit go-live" }, HUMAN);
 add("Partner", "partner", ["read", "write"], { read: "View partner profile", write: "Edit partner profile" }, HUMAN);
 add("Partner", "affiliates", ["read", "write"], { read: "View affiliates", write: "Manage affiliates" }, HUMAN);
 add("Notifications", "notifications", ["write"], { write: "Send notifications" }, HUMAN);
@@ -210,6 +288,7 @@ REG["extensions:install"] = {
   sensitive: false,
   staffOnly: false,
   publishableAllowed: false,
+  publishableOnly: false,
   extensionAllowed: false,
   implies: []
 };
@@ -222,6 +301,7 @@ REG["*"] = {
   sensitive: true,
   staffOnly: false,
   publishableAllowed: false,
+  publishableOnly: false,
   extensionAllowed: false,
   implies: []
 };
@@ -241,6 +321,9 @@ var EVENT_SCOPE_OVERRIDES = {
   "payment.refunded": "payment_refunds:read",
   "payment.partially_refunded": "payment_refunds:read",
   "payment.refund_failed": "payment_refunds:read",
+  // Money returned, so it belongs with the other refund events rather than
+  // behind the broad subscriptions:read the `subscription.` prefix would give.
+  "subscription.invoice_refunded": "payment_refunds:read",
   "payment.disputed": "payment_disputes:read",
   "payment.dispute_cleared": "payment_disputes:read",
   "fulfillment.digital.delivered": "fulfillment_digital:read"
@@ -257,9 +340,17 @@ var PREFIX_RULES = [
   ["fulfillment.", "fulfillments:read"],
   ["discount.", "discounts:read"],
   ["invoice.", "invoices:read"],
+  ["import.", "imports:read"],
   ["shipping_tax.", "shipping_tax:read"],
   ["workspace.", "billing:read"],
-  ["extension.", "merchant:read"]
+  // `extensions:read` is a human scope (extensions must never watch other
+  // extensions), so only a workspace endpoint can SUBSCRIBE to this family.
+  // The uninstalled installation's own endpoint is addressed directly by the
+  // uninstall path and needs no subscription at all.
+  ["extension.", "extensions:read"],
+  // Subscribing to script outcomes needs script read — the payload names the
+  // script key and its hash, which is the merchant's script inventory.
+  ["script.", "application_scripts:read"]
 ];
 function eventReadScope(type) {
   if (EVENT_SCOPE_OVERRIDES[type]) return EVENT_SCOPE_OVERRIDES[type];
@@ -271,8 +362,90 @@ function eventReadScope(type) {
 
 // ../core-scopes/src/issuance.ts
 var PUBLISHABLE_SCOPES = Object.values(SCOPE_REGISTRY).filter((d) => d.publishableAllowed).map((d) => d.id);
+var CONNECTOR_GRANTABLE_SENSITIVE_SCOPES = ["customer_pii:read"];
+function validateScopesForOAuth(scopes, opts = {}) {
+  const invalid = [];
+  for (const id of scopes) {
+    if (id === "*") {
+      invalid.push(id);
+      continue;
+    }
+    const def = SCOPE_REGISTRY[id];
+    if (!def || def.staffOnly) {
+      invalid.push(id);
+      continue;
+    }
+    if (def.sensitive && !(opts.connector && CONNECTOR_GRANTABLE_SENSITIVE_SCOPES.includes(id))) invalid.push(id);
+  }
+  return { ok: invalid.length === 0, invalid };
+}
+
+// ../core-scopes/src/shopper-pii.ts
+var PERSON_KEYS = /* @__PURE__ */ new Set([
+  "email",
+  "customerEmail",
+  "billingEmail",
+  "buyerEmail",
+  "authorEmail",
+  "authorName",
+  "phone",
+  "firstName",
+  "lastName",
+  "addressLine1",
+  "addressLine2",
+  "billingAddressLines",
+  "processorResponse",
+  "shareToken",
+  "company",
+  "externalId",
+  "externalCustomerId",
+  // Free-form: contents cannot be inspected for a person, so the field goes.
+  "metadata",
+  "notes",
+  "internalNotes",
+  "buyerNote",
+  "buyerReference",
+  "changeSummary",
+  "declinedReason",
+  "compReason",
+  "holdReason",
+  "body",
+  "acceptance",
+  "acceptanceSelections",
+  "clientContext",
+  "ipAddress",
+  "userAgent",
+  "vatNumber",
+  "buyerVatNumber",
+  "taxExemptionNumber"
+]);
+var PERSON_CONTAINERS = /* @__PURE__ */ new Set(["customer", "buyer"]);
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function walk(value, parentKey, depth) {
+  if (depth > 32) return value;
+  if (Array.isArray(value)) return value.map((item) => walk(item, parentKey, depth + 1));
+  if (!isPlainObject(value)) return value;
+  const out = {};
+  const isPerson = parentKey !== null && PERSON_CONTAINERS.has(parentKey);
+  for (const [key, child] of Object.entries(value)) {
+    if (PERSON_KEYS.has(key) || isPerson && key === "name") {
+      out[key] = child === void 0 ? child : null;
+    } else {
+      out[key] = walk(child, key, depth + 1);
+    }
+  }
+  return out;
+}
+function redactShopperPii(value) {
+  return walk(value, null, 0);
+}
 
 // ../action-catalog/src/actions.ts
+var OAUTH_WITHHELD = "Over an OAuth connection (ChatGPT, Claude) these are withheld, because a buyer can type them: line-item and quote-item names, SKUs and reference ids; company; every address line except the country; the merchant's external ids; notes, messages, reasons and metadata. Describe items by quantity and amount, and say the rest is withheld rather than missing.";
 var ACTIONS = [
   // ---------------------------------------------------------------- identity
   {
@@ -289,7 +462,7 @@ var ACTIONS = [
   {
     id: "search_docs",
     title: "Search the Throttle developer docs",
-    description: "Full-text search over the Throttle developer documentation. Returns titles, canonical docs.usethrottle.dev URLs, and matching excerpts. Prefer this over recalling API details from memory.",
+    description: "Full-text search over the Throttle developer documentation. Returns titles, canonical usethrottle.dev/docs URLs, and matching excerpts. Prefer this over recalling API details from memory.",
     kind: "read",
     scopes: [],
     input: [
@@ -326,7 +499,7 @@ var ACTIONS = [
   {
     id: "validate_payload",
     title: "Validate a request body against the API contract",
-    description: "Check a request body against the published contract before sending it. Names every unsupported field and gives its canonical replacement \u2014 Throttle is strict camelCase and rejects retired aliases such as line_items, unit_price, customer_id and storeId.",
+    description: "Check a request body against the published contract before sending it. Names every unsupported field and gives its canonical replacement \u2014 Throttle is strict camelCase and rejects retired aliases such as line_items, unit_price, customer_id and storeId. Full reference: https://usethrottle.dev/docs/developers/api-reference.",
     kind: "read",
     scopes: [],
     input: [
@@ -341,15 +514,22 @@ var ACTIONS = [
   {
     id: "api_get",
     title: "Read any Throttle API endpoint",
-    description: "Escape hatch for reads the curated tools do not cover: performs a GET against any /api/v1 path and returns the response. Cannot write. Confirm the path with describe_endpoint first if unsure.",
+    description: "Escape hatch for reads the curated tools do not cover: performs a GET against any /api/v1 path and returns the response. Cannot write. Confirm the path with describe_endpoint first if unsure. Full reference: https://usethrottle.dev/docs/developers/api-reference.",
     kind: "read",
     scopes: [],
+    credentialScoped: true,
     input: [
       {
         name: "path",
         type: "string",
         required: true,
         description: "Path beginning with /api/v1, query string included."
+      },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
       }
     ],
     requests: [],
@@ -371,11 +551,33 @@ var ACTIONS = [
       { name: "q", type: "string", required: false, description: "Free-text search." },
       { name: "status", type: "string", required: false, description: "Order status filter." },
       { name: "paymentStatus", type: "string", required: false, description: "Payment status filter." },
+      {
+        name: "createdAfter",
+        type: "string",
+        required: false,
+        description: "ISO 8601 lower bound on creation time, exclusive. For a single day, pass that day's midnight and the next day's midnight."
+      },
+      {
+        name: "createdBefore",
+        type: "string",
+        required: false,
+        description: "ISO 8601 upper bound on creation time, exclusive."
+      },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/orders" }],
-    channels: ["mcp", "zapier", "make", "n8n"]
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      OAUTH_WITHHELD,
+      "Over an OAuth connection, q matches the order id, order number and status fields only."
+    ]
   },
   {
     id: "get_order",
@@ -383,7 +585,16 @@ var ACTIONS = [
     description: "Full picture of a single order: the order itself plus its payments, returns and fulfillments in one response.",
     kind: "read",
     scopes: ["orders:read"],
-    input: [{ name: "id", type: "string", required: true, description: "Order id." }],
+    sectionScopes: ["payments:read", "order_returns:read", "fulfillments:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Order id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [
       { method: "GET", path: "/api/v1/orders/:id" },
       { method: "GET", path: "/api/v1/orders/:id/payments" },
@@ -392,23 +603,45 @@ var ACTIONS = [
     ],
     channels: ["mcp"],
     guardrails: [
-      "Sub-reads need their own scopes (payments:read, order_returns:read, fulfillments:read). Skip a section the credential cannot read and say so in the result rather than failing the whole call."
+      "Sub-reads need their own scopes (payments:read, order_returns:read, fulfillments:read). Skip a section the credential cannot read and say so in the result rather than failing the whole call.",
+      OAUTH_WITHHELD
     ]
   },
   // ---------------------------------------------------------------- customers
   {
     id: "search_customers",
     title: "Search customers",
-    description: "Find customers by name, email or external id.",
+    description: "Find customers by name, email or external id, or list them by creation date. Over an OAuth connection (ChatGPT, Claude) text search is not available \u2014 list by date instead \u2014 because every field it could match is withheld there.",
     kind: "read",
     scopes: ["customers:read"],
     input: [
       { name: "q", type: "string", required: false, description: "Free-text search." },
+      {
+        name: "createdAfter",
+        type: "string",
+        required: false,
+        description: "ISO 8601 lower bound on creation time, exclusive. For a single day, pass that day's midnight and the next day's midnight."
+      },
+      {
+        name: "createdBefore",
+        type: "string",
+        required: false,
+        description: "ISO 8601 upper bound on creation time, exclusive."
+      },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/customers" }],
-    channels: ["mcp", "zapier", "make", "n8n"]
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      'email, phone, firstName, lastName, name and metadata are withheld (null, or absent from the result) unless the credential holds customer_pii:read, which OAuth connections cannot hold. Over an OAuth connection company, externalId and externalCustomerId are withheld too, and q is refused. Do not describe a missing name/email as "no name on file"; say it is withheld.'
+    ]
   },
   {
     id: "get_customer",
@@ -416,7 +649,16 @@ var ACTIONS = [
     description: "Full picture of a single customer: the record plus their subscriptions and addresses in one response.",
     kind: "read",
     scopes: ["customers:read"],
-    input: [{ name: "id", type: "string", required: true, description: "Customer id." }],
+    sectionScopes: ["customer_addresses:read", "subscriptions:read"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Customer id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [
       { method: "GET", path: "/api/v1/customers/:id" },
       { method: "GET", path: "/api/v1/customers/:id/addresses" },
@@ -424,7 +666,9 @@ var ACTIONS = [
     ],
     channels: ["mcp"],
     guardrails: [
-      "Sub-reads need customer_addresses:read / subscriptions:read. Omit a section the credential cannot read instead of failing."
+      "Sub-reads need customer_addresses:read / subscriptions:read. Omit a section the credential cannot read instead of failing.",
+      "email, phone, firstName, lastName, name and metadata on the customer record are withheld (null, or absent from the result) unless the credential holds customer_pii:read, which OAuth connections cannot hold. Say PII is redacted rather than reporting the buyer as anonymous.",
+      OAUTH_WITHHELD
     ]
   },
   // ------------------------------------------------------------- subscriptions
@@ -437,8 +681,26 @@ var ACTIONS = [
     input: [
       { name: "customerId", type: "string", required: false, description: "Filter by customer." },
       { name: "status", type: "string", required: false, description: "Filter by status." },
+      {
+        name: "createdAfter",
+        type: "string",
+        required: false,
+        description: "ISO 8601 lower bound on creation time, exclusive. For a single day, pass that day's midnight and the next day's midnight."
+      },
+      {
+        name: "createdBefore",
+        type: "string",
+        required: false,
+        description: "ISO 8601 upper bound on creation time, exclusive."
+      },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/subscriptions" }],
     channels: ["mcp", "zapier", "make", "n8n"]
@@ -449,7 +711,15 @@ var ACTIONS = [
     description: "Read a single subscription including its current period and pending changes.",
     kind: "read",
     scopes: ["subscriptions:read"],
-    input: [{ name: "id", type: "string", required: true, description: "Subscription id." }],
+    input: [
+      { name: "id", type: "string", required: true, description: "Subscription id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [{ method: "GET", path: "/api/v1/subscriptions/:id" }],
     channels: ["mcp", "zapier", "make", "n8n"]
   },
@@ -462,8 +732,26 @@ var ACTIONS = [
     scopes: ["quotes:read"],
     input: [
       { name: "status", type: "string", required: false, description: "Filter by quote status." },
+      {
+        name: "createdAfter",
+        type: "string",
+        required: false,
+        description: "ISO 8601 lower bound on creation time, exclusive. For a single day, pass that day's midnight and the next day's midnight."
+      },
+      {
+        name: "createdBefore",
+        type: "string",
+        required: false,
+        description: "ISO 8601 upper bound on creation time, exclusive."
+      },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/quotes" }],
     channels: ["mcp", "zapier", "make", "n8n"]
@@ -471,12 +759,21 @@ var ACTIONS = [
   {
     id: "get_quote",
     title: "Get one quote",
-    description: "Read a single quote with its line items, revisions and buyer link state.",
+    description: "Read a single quote: status, totals, and each revision with its line items and payment terms.",
     kind: "read",
     scopes: ["quotes:read"],
-    input: [{ name: "id", type: "string", required: true, description: "Quote id." }],
+    input: [
+      { name: "id", type: "string", required: true, description: "Quote id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [{ method: "GET", path: "/api/v1/quotes/:id" }],
-    channels: ["mcp", "zapier", "make", "n8n"]
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [OAUTH_WITHHELD]
   },
   // ----------------------------------------------------------------- invoices
   {
@@ -488,10 +785,17 @@ var ACTIONS = [
     input: [
       { name: "status", type: "string", required: false, description: "Filter by invoice status." },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/invoices" }],
-    channels: ["mcp", "zapier", "make", "n8n"]
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [OAUTH_WITHHELD]
   },
   {
     id: "receivables_aging",
@@ -499,7 +803,14 @@ var ACTIONS = [
     description: 'Outstanding receivables bucketed by age \u2014 answers "what is overdue and by how long".',
     kind: "read",
     scopes: ["invoices:read"],
-    input: [],
+    input: [
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [{ method: "GET", path: "/api/v1/invoices/aging" }],
     channels: ["mcp", "zapier", "make", "n8n"]
   },
@@ -524,7 +835,13 @@ var ACTIONS = [
       { name: "createdAfter", type: "string", required: false, description: "ISO 8601 date lower bound." },
       { name: "createdBefore", type: "string", required: false, description: "ISO 8601 date upper bound." },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/discounts" }],
     channels: ["mcp", "zapier", "make", "n8n"]
@@ -535,7 +852,15 @@ var ACTIONS = [
     description: "Read a single discount code: value, conditions, usage limits and redemption count.",
     kind: "read",
     scopes: ["discounts:read"],
-    input: [{ name: "id", type: "string", required: true, description: "Discount id." }],
+    input: [
+      { name: "id", type: "string", required: true, description: "Discount id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [{ method: "GET", path: "/api/v1/discounts/:id" }],
     channels: ["mcp", "zapier", "make", "n8n"]
   },
@@ -562,7 +887,13 @@ var ACTIONS = [
       { name: "amountMin", type: "number", required: false, description: "Minimum amount, minor units." },
       { name: "amountMax", type: "number", required: false, description: "Maximum amount, minor units." },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/payments" }],
     channels: ["mcp", "zapier", "make", "n8n"]
@@ -573,7 +904,15 @@ var ACTIONS = [
     description: "Read a single payment plus its full transaction history (authorize/capture/refund/void attempts).",
     kind: "read",
     scopes: ["payments:read"],
-    input: [{ name: "id", type: "string", required: true, description: "Payment id." }],
+    input: [
+      { name: "id", type: "string", required: true, description: "Payment id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [
       { method: "GET", path: "/api/v1/payments/:id" },
       { method: "GET", path: "/api/v1/payments/:id/transactions" }
@@ -590,9 +929,18 @@ var ACTIONS = [
     description: "Read a single issued invoice: line items, totals, status and the billing snapshot at issue time.",
     kind: "read",
     scopes: ["invoices:read"],
-    input: [{ name: "id", type: "string", required: true, description: "Invoice id." }],
+    input: [
+      { name: "id", type: "string", required: true, description: "Invoice id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [{ method: "GET", path: "/api/v1/invoices/:id" }],
-    channels: ["mcp", "zapier", "make", "n8n"]
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [OAUTH_WITHHELD]
   },
   // ------------------------------------------------------------------ carts
   {
@@ -604,7 +952,13 @@ var ACTIONS = [
     input: [
       { name: "sinceDays", type: "number", required: false, description: "How many days back to look." },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [
       { method: "GET", path: "/api/v1/abandoned-carts" },
@@ -625,7 +979,13 @@ var ACTIONS = [
       { name: "entityType", type: "string", required: false, description: "Entity type filter." },
       { name: "entityId", type: "string", required: false, description: "Entity id filter." },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/events" }],
     channels: ["mcp", "n8n"]
@@ -633,13 +993,30 @@ var ACTIONS = [
   {
     id: "list_webhook_deliveries",
     title: "List webhook deliveries",
-    description: "Recent outbound webhook deliveries, filterable by endpoint and status.",
+    description: "Recent outbound webhook deliveries, filterable by endpoint, status and event type.",
     kind: "read",
     scopes: ["webhook_deliveries:read"],
     input: [
       { name: "endpointId", type: "string", required: false, description: "Filter by endpoint." },
-      { name: "status", type: "string", required: false, description: "Filter by delivery status." },
-      { name: "limit", type: "number", required: false, description: "Page size." }
+      {
+        name: "status",
+        type: "string",
+        required: false,
+        description: "Filter by delivery status: pending, delivered, failed or dead_letter."
+      },
+      {
+        name: "eventType",
+        type: "string",
+        required: false,
+        description: "Filter by exact event type, e.g. payment.failed."
+      },
+      { name: "limit", type: "number", required: false, description: "Page size." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/webhook-deliveries" }],
     channels: ["mcp", "n8n"]
@@ -650,7 +1027,15 @@ var ACTIONS = [
     description: "Full delivery record: the signed payload we sent, the response we got back, and every attempt.",
     kind: "read",
     scopes: ["webhook_deliveries:read"],
-    input: [{ name: "id", type: "string", required: true, description: "Delivery id." }],
+    input: [
+      { name: "id", type: "string", required: true, description: "Delivery id." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [{ method: "GET", path: "/api/v1/webhook-deliveries/:id" }],
     channels: ["mcp", "n8n"]
   },
@@ -660,12 +1045,19 @@ var ACTIONS = [
     description: "Diagnose a failing checkout in one call: session state, its cart, the events it emitted, and any webhook deliveries that followed. Use this before asking the user to reproduce anything.",
     kind: "read",
     scopes: ["checkout_sessions:read"],
+    sectionScopes: ["events:read", "webhook_deliveries:read"],
     input: [
       {
         name: "id",
         type: "string",
         required: true,
         description: "Checkout session id (or cart id \u2014 the tool resolves the session)."
+      },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
       }
     ],
     requests: [
@@ -676,7 +1068,8 @@ var ACTIONS = [
     ],
     channels: ["mcp"],
     guardrails: [
-      "Report which sections were unavailable rather than failing the call when a sub-read is unscoped."
+      "Report which sections were unavailable rather than failing the call when a sub-read is unscoped.",
+      OAUTH_WITHHELD
     ]
   },
   // ------------------------------------------------------------- extensions
@@ -695,7 +1088,13 @@ var ACTIONS = [
         enum: ["active", "suspended", "uninstalled"]
       },
       { name: "limit", type: "number", required: false, description: "Page size." },
-      { name: "cursor", type: "string", required: false, description: "Pagination cursor." }
+      { name: "cursor", type: "string", required: false, description: "Pagination cursor." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
     ],
     requests: [{ method: "GET", path: "/api/v1/installations" }],
     channels: ["mcp", "zapier", "make", "n8n"]
@@ -707,7 +1106,14 @@ var ACTIONS = [
     description: "Read the payment-routing cascade, active routing connectors, and card/other decline rules \u2014 what determines which processor handles a payment and what happens on a decline.",
     kind: "read",
     scopes: ["connectors:read"],
-    input: [],
+    input: [
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [
       { method: "GET", path: "/api/v1/payment-routing" },
       { method: "GET", path: "/api/v1/routing-connectors" },
@@ -725,7 +1131,15 @@ var ACTIONS = [
     description: 'Answers "am I ready to go live?" \u2014 active connectors, webhook endpoints and their recent delivery health, and the environment this credential is pinned to.',
     kind: "read",
     scopes: [],
-    input: [],
+    sectionScopes: ["connectors:read", "webhooks:read"],
+    input: [
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [
       { method: "GET", path: "/api/v1/whoami" },
       { method: "GET", path: "/api/v1/connectors" },
@@ -741,7 +1155,7 @@ var ACTIONS = [
   {
     id: "get_workspace_settings",
     title: "Get workspace settings",
-    description: "Read this workspace's identity and settings: name, slug, branding, onboarding state, and the default Net-N payment terms.",
+    description: "Read this workspace's identity: name, slug, branding and onboarding state. Payment terms are set per application and environment, not here.",
     kind: "read",
     scopes: ["merchant:read"],
     input: [],
@@ -760,12 +1174,48 @@ var ACTIONS = [
     requests: [{ method: "GET", path: "/api/v1/audit-log" }],
     channels: ["mcp", "zapier", "make", "n8n"]
   },
+  {
+    id: "list_applications",
+    title: "List applications in this workspace",
+    description: 'List every application in this workspace you have access to, so you can pass one of their ids as applicationId on other read and analytics tools. Note: the underlying route is the legacy-named /v1/stores (kept for contract stability) \u2014 the resource it returns is applications, not a separate "stores" concept.',
+    kind: "read",
+    scopes: ["applications:read"],
+    input: [],
+    requests: [{ method: "GET", path: "/api/v1/stores" }],
+    channels: ["mcp", "zapier", "make", "n8n"]
+  },
+  {
+    id: "get_sales_timeseries",
+    title: "Sales over time",
+    description: `Order count and gross revenue bucketed by day, week or month over any date range, in the merchant's timezone, optionally compared to the previous period or the same range last year. Use this for "how much did we sell on/last/between\u2026" instead of paging search_orders and adding it up.`,
+    kind: "read",
+    scopes: ["orders:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "groupBy", type: "string", required: false, description: "Bucket size.", enum: ["day", "week", "month"], default: "day" },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for bucket boundaries, e.g. America/New_York. Defaults to UTC \u2014 ask the user rather than assuming UTC when the answer depends on day boundaries." },
+      { name: "compareTo", type: "string", required: false, description: "Add a comparison total.", enum: ["previous_period", "previous_year", "none"], default: "none" },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/orders-timeseries" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Revenue is GROSS. Refunds are not deducted, because that needs payment_refunds:read, which OAuth connections cannot hold. Never describe the figure as net."
+    ]
+  },
   {
     id: "get_business_summary",
     title: "Business summary",
-    description: "How are we doing? Orders/revenue, subscription MRR, receivables and quotes pipeline for a week/month/quarter, always compared to the immediately preceding period of equal length.",
+    description: "How are we doing? Orders/revenue, subscription MRR, receivables and quotes pipeline over a date range, compared to the immediately preceding window of equal length. Note: period=week|month|quarter means the TRAILING 7/30/90 days, not a calendar period \u2014 pass from/to for calendar months.",
     kind: "read",
     scopes: [],
+    sectionScopes: ["orders:read", "subscriptions:read", "invoices:read", "quotes:read"],
     input: [
       {
         name: "period",
@@ -774,6 +1224,15 @@ var ACTIONS = [
         description: "Reporting window.",
         enum: ["week", "month", "quarter"],
         default: "month"
+      },
+      { name: "from", type: "string", required: false, description: "ISO 8601 start of range. Overrides period." },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for period boundaries. Defaults to UTC." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
       }
     ],
     requests: [{ method: "GET", path: "/api/v1/analytics/business-summary" }],
@@ -782,19 +1241,189 @@ var ACTIONS = [
       "Each section needs its own scope (orders:read, subscriptions:read, invoices:read, quotes:read). A section without its scope is reported as omitted rather than failing the whole call."
     ]
   },
+  {
+    id: "get_top_products",
+    title: "Top products",
+    description: "Best-selling products over a date range, by revenue or units sold. Line items come from the merchant's own cart payload, so a product is identified by its external reference id when present and by name otherwise. The response carries both the top-N rows (by the chosen sort) and range-wide totals across every matching product, so you can compute what share of total revenue/units the top N represent.",
+    kind: "read",
+    scopes: ["orders:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for range boundaries. Defaults to UTC." },
+      { name: "by", type: "string", required: false, description: "Sort key.", enum: ["revenue", "units"], default: "revenue" },
+      { name: "limit", type: "number", required: false, description: "Max rows to return (1-100). Defaults to 20." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/products" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Revenue is GROSS. Refunds are not deducted, because that needs payment_refunds:read, which OAuth connections cannot hold. Never describe the figure as net."
+    ]
+  },
   {
     id: "get_attention_digest",
     title: "Attention digest",
     description: "What needs attention right now? Open disputes, subscriptions in dunning, overdue Net-N invoices, and webhooks with degraded delivery health \u2014 a point-in-time snapshot, not a time range.",
     kind: "read",
     scopes: [],
-    input: [],
+    sectionScopes: ["payment_disputes:read", "subscriptions:read", "invoices:read", "webhook_deliveries:read"],
+    input: [
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
     requests: [{ method: "GET", path: "/api/v1/analytics/attention-digest" }],
     channels: ["mcp", "zapier", "make", "n8n"],
     guardrails: [
       "Each section needs its own scope (payment_disputes:read, subscriptions:read, invoices:read, webhook_deliveries:read). A section without its scope is reported as omitted rather than failing the whole call."
     ]
   },
+  {
+    id: "get_customer_growth",
+    title: "Customer growth",
+    description: "Customer growth over a date range: signups per day/week/month, how many orders came from first-time versus returning customers, and the highest-value customers in the window.",
+    kind: "read",
+    scopes: ["customers:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "groupBy", type: "string", required: false, description: "Signup series bucket size.", enum: ["day", "week", "month"], default: "day" },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for bucket boundaries. Defaults to UTC." },
+      { name: "topBy", type: "string", required: false, description: "Sort key for top customers.", enum: ["revenue", "orders"], default: "revenue" },
+      { name: "topLimit", type: "number", required: false, description: "Max top-customers rows to return (1-50). Defaults to 10." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/customers" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Revenue is GROSS. Refunds are not deducted, because that needs payment_refunds:read, which OAuth connections cannot hold. Never describe the figure as net.",
+      "topCustomers is a top-N list; use the accompanying totals for range-wide customer/order/revenue counts instead of summing the returned rows.",
+      "topCustomers[].email and .name come back null unless the credential holds customer_pii:read, which OAuth connections cannot hold. Identify a top customer by id, not by a null name."
+    ]
+  },
+  {
+    id: "get_revenue_breakdown",
+    title: "Revenue breakdown",
+    description: "Revenue split by one dimension over a date range \u2014 payment method, order source, or currency. Amounts are gross; refunds are not deducted.",
+    kind: "read",
+    scopes: ["orders:read"],
+    input: [
+      {
+        name: "dimension",
+        type: "string",
+        required: true,
+        description: "Breakdown dimension.",
+        enum: ["paymentMethod", "source", "currency"]
+      },
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for range boundaries. Defaults to UTC." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/revenue-breakdown" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Revenue is GROSS. Refunds are not deducted, because that needs payment_refunds:read, which OAuth connections cannot hold. Never describe the figure as net.",
+      "dimension is required; it is never defaulted, so omitting it fails the call instead of silently picking a dimension.",
+      "For dimension=paymentMethod, an order paid via more than one method can appear in more than one row, so rows can sum to more than totals (a separate whole-range aggregate over orders alone)."
+    ]
+  },
+  {
+    id: "get_funnel_conversion",
+    title: "Checkout funnel",
+    description: "Checkout funnel over a date range: carts created, checkout sessions started, orders completed, with the drop-off between each stage.",
+    kind: "read",
+    scopes: ["carts:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for range boundaries. Defaults to UTC." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/funnel" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "Each stage needs its own scope (carts:read, checkout_sessions:read, orders:read), checked independently \u2014 an OAuth grant carries literal scopes with no legacy expansion, so a credential can hold carts:read without the other two. An omitted stage is reported as such rather than failing the whole call.",
+      "conversionRate and dropOff[].ratePct are null (unknown) when a stage they depend on is omitted, and 0 only when the stage was readable with a true zero count. Never treat a null here as 0.",
+      'dropOff[].ratePct is the percentage of "from" that did NOT reach "to" (loss), not a conversion rate. The step-conversion rate is 100 - ratePct.'
+    ]
+  },
+  {
+    id: "get_subscription_movement",
+    title: "Subscription movement",
+    description: "Subscription movement over a date range: new subscriptions, cancellations and net MRR change per day/week/month. Figures are reconstructed from subscription timestamps, not a stored historical snapshot.",
+    kind: "read",
+    scopes: ["subscriptions:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for bucket boundaries. Defaults to UTC." },
+      { name: "groupBy", type: "string", required: false, description: "Bucket size.", enum: ["day", "week", "month"], default: "day" },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/subscriptions" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      "newSubscriptions, churnedSubscriptions and mrrDeltaCents are reconstructed per bucket from subscription created_at/cancelled_at timestamps, not a stored historical MRR snapshot \u2014 never present this series as an audited historical MRR ledger.",
+      "mrrDeltaCents for a bucket only credits subscriptions created in that bucket that are still active right now, and only debits subscriptions cancelled in that bucket that already existed when it started. A subscription created AND cancelled inside the same bucket still counts toward both newSubscriptions and churnedSubscriptions but contributes 0 to mrrDeltaCents.",
+      "totals is the sum over the full series (the series is never truncated), so totals.newSubscriptions/.churnedSubscriptions/.netMrrDeltaCents always equal the corresponding sums of series[]."
+    ]
+  },
+  {
+    id: "get_discount_performance",
+    title: "Discount performance",
+    description: "Discount code performance over a date range: redemption count, revenue on discounted orders, and total discount given per code.",
+    kind: "read",
+    scopes: ["discounts:read"],
+    input: [
+      { name: "from", type: "string", required: false, description: 'ISO 8601 start of range, exclusive. Defaults to 30 days before "to".' },
+      { name: "to", type: "string", required: false, description: "ISO 8601 end of range, exclusive. Defaults to now." },
+      { name: "timezone", type: "string", required: false, description: "IANA timezone for range boundaries. Defaults to UTC." },
+      { name: "limit", type: "number", required: false, description: "Max rows to return. Defaults to 20." },
+      {
+        name: "applicationId",
+        type: "string",
+        required: false,
+        description: "Application to read from. Defaults to the one this connection was authorized for. Call list_applications to see the others."
+      }
+    ],
+    requests: [{ method: "GET", path: "/api/v1/analytics/discounts" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    guardrails: [
+      'discountedRevenueCents and discountGivenCents are DIFFERENT measures: discountedRevenueCents is the gross order total on orders that redeemed the code; discountGivenCents is the discount amount taken off those same orders. Never describe discountedRevenueCents as "given away" or discountGivenCents as revenue.',
+      "Only orders with status <> draft and a gross-eligible payment_status are counted; refunds are not deducted from discountedRevenueCents, because that needs payment_refunds:read.",
+      "rows are the top N codes by discount given; totals is a SEPARATE whole-range aggregate (not a reduction over rows), so totals.redemptions / totals.discountGivenCents stay valid even when rows is truncated by limit."
+    ]
+  },
   // ------------------------------------------------------------ sandbox write
   {
     id: "seed_test_data",
@@ -820,6 +1449,151 @@ var ACTIONS = [
       "Seeds a finalized DRAFT order \u2014 it does not capture a payment, which needs a browser-side tokenised payment method."
     ]
   },
+  // ---------------------------------------------------------- inbound writes
+  // The no-code channels are mostly used in the "something happened elsewhere,
+  // put it into Throttle" direction — a form submission, a new CRM contact, a
+  // spreadsheet row. These three are that direction.
+  {
+    id: "create_customer",
+    title: "Create a customer",
+    description: "Create a customer record. Use search_customers first if the buyer may already exist \u2014 this does not de-duplicate by email.",
+    kind: "write",
+    scopes: ["customers:write"],
+    input: [
+      { name: "email", type: "string", required: true, description: "The buyer's email address." },
+      { name: "firstName", type: "string", required: false, description: "Given name." },
+      { name: "lastName", type: "string", required: false, description: "Family name." },
+      { name: "phone", type: "string", required: false, description: "Contact phone number." },
+      { name: "company", type: "string", required: false, description: "The buyer's company." },
+      {
+        name: "externalId",
+        type: "string",
+        required: false,
+        description: "This customer's id in your own system. Resolvable later via get_customer."
+      },
+      {
+        name: "netN",
+        type: "number",
+        required: false,
+        description: "Invoice terms in days for this customer specifically, 0-365. Omit to use the workspace default; 0 means due on issue."
+      },
+      {
+        name: "acceptsMarketing",
+        type: "boolean",
+        required: false,
+        description: "Whether the buyer opted into marketing email.",
+        default: false
+      }
+    ],
+    requests: [{ method: "POST", path: "/api/v1/customers" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true,
+    guardrails: [
+      "The created record is echoed back with email, phone, firstName, lastName and name nulled unless the credential holds customer_pii:read, which OAuth connections cannot hold \u2014 the customer is still created with the values sent, only the response is redacted."
+    ]
+  },
+  {
+    id: "update_customer",
+    title: "Update a customer",
+    description: "Change fields on an existing customer. Only the fields supplied are touched; everything else is left alone.",
+    kind: "write",
+    scopes: ["customers:write"],
+    input: [
+      { name: "id", type: "string", required: true, description: "Customer id." },
+      { name: "email", type: "string", required: false, description: "The buyer's email address." },
+      { name: "firstName", type: "string", required: false, description: "Given name." },
+      { name: "lastName", type: "string", required: false, description: "Family name." },
+      { name: "phone", type: "string", required: false, description: "Contact phone number." },
+      { name: "company", type: "string", required: false, description: "The buyer's company." },
+      {
+        name: "externalId",
+        type: "string",
+        required: false,
+        description: "This customer's id in your own system. Pass null to clear it."
+      },
+      {
+        name: "netN",
+        type: "number",
+        required: false,
+        description: "Invoice terms in days for this customer specifically, 0-365."
+      },
+      {
+        name: "acceptsMarketing",
+        type: "boolean",
+        required: false,
+        description: "Whether the buyer opted into marketing email."
+      }
+    ],
+    requests: [{ method: "PATCH", path: "/api/v1/customers/:id" }],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true,
+    guardrails: [
+      "The updated record is echoed back with email, phone, firstName, lastName and name nulled unless the credential holds customer_pii:read, which OAuth connections cannot hold \u2014 the update still applied, only the response is redacted."
+    ]
+  },
+  {
+    id: "create_checkout_link",
+    title: "Create a checkout link",
+    description: "Build a cart from line items and return a hosted checkout URL the buyer can pay at. Prices are in minor units (2500 = $25.00).",
+    kind: "write",
+    scopes: ["carts:write", "cart_items:write", "checkout_sessions:write"],
+    input: [
+      {
+        name: "lineItems",
+        type: "array",
+        required: true,
+        description: "What the buyer is paying for: { name, unitPrice, quantity }. unitPrice is an integer in minor units."
+      },
+      {
+        name: "returnUrl",
+        type: "string",
+        required: true,
+        description: "Absolute URL the buyer lands on after paying."
+      },
+      {
+        name: "cancelUrl",
+        type: "string",
+        required: true,
+        description: "Absolute URL the buyer lands on if they abandon checkout."
+      },
+      {
+        name: "customerId",
+        type: "string",
+        required: false,
+        description: "Attach the cart to an existing customer."
+      },
+      {
+        name: "customerEmail",
+        type: "string",
+        required: false,
+        description: "Pre-fill the buyer email without needing a customer record."
+      },
+      {
+        name: "discountCode",
+        type: "string",
+        required: false,
+        description: "Discount code to apply to the session."
+      },
+      {
+        name: "netN",
+        type: "number",
+        required: false,
+        description: "Invoice terms in days for this cart, 0-365. Omit to pay in full at checkout."
+      }
+    ],
+    // Three calls: the API has no single "checkout link" endpoint, and a
+    // checkout session requires a cart that already holds its line items.
+    requests: [
+      { method: "POST", path: "/api/v1/carts" },
+      { method: "POST", path: "/api/v1/carts/:id/items" },
+      { method: "POST", path: "/api/v1/checkout/sessions" }
+    ],
+    channels: ["mcp", "zapier", "make", "n8n"],
+    idempotent: true,
+    guardrails: [
+      "The returned URL is buyer-facing and takes real payment in a production environment."
+    ]
+  },
   // -------------------------------------------------------------- money/mail
   {
     id: "create_quote",
@@ -848,7 +1622,8 @@ var ACTIONS = [
     requests: [{ method: "POST", path: "/api/v1/quotes/:id/issue" }],
     channels: ["mcp", "zapier", "make", "n8n"],
     idempotent: true,
-    guardrails: ['Sends mail to a real buyer. Never call it speculatively or to "check" a quote.']
+    guardrails: ['Sends mail to a real buyer. Never call it speculatively or to "check" a quote.'],
+    destructive: true
   },
   {
     id: "refund_payment",
@@ -867,12 +1642,20 @@ var ACTIONS = [
       { name: "reason", type: "string", required: false, description: "Reason recorded on the refund." }
     ],
     requests: [{ method: "POST", path: "/api/v1/payments/:id/refund" }],
-    channels: ["mcp", "zapier", "make", "n8n"],
+    // NOT zapier/make. `payment_refunds:write` is `sensitive` in the scope
+    // registry, and `validateScopesForOAuth` rejects every sensitive scope — so
+    // an OAuth grant, which is the only credential a public Zapier or Make app
+    // can hold, can never carry it. Listing the action on those channels would
+    // ship a connector action that 403s on every call. MCP and n8n keep it:
+    // both authenticate with an `sk_` key, which CAN hold the scope.
+    // `oauth-grantable-scopes` in the catalog tests enforces this.
+    channels: ["mcp", "n8n"],
     idempotent: true,
     guardrails: [
       "Moves money and is irreversible. Confirm with the user first.",
       "The API treats an omitted amount as a FULL refund, so this action requires it explicitly."
-    ]
+    ],
+    destructive: true
   },
   {
     id: "manage_subscription",
@@ -915,7 +1698,8 @@ var ACTIONS = [
     requests: [{ method: "POST", path: "/api/v1/subscriptions/:id/cancel" }],
     channels: ["mcp", "zapier", "make", "n8n"],
     idempotent: true,
-    guardrails: ["Ends billing for a paying customer. Confirm with the user first."]
+    guardrails: ["Ends billing for a paying customer. Confirm with the user first."],
+    destructive: true
   },
   {
     id: "replay_webhook_delivery",
@@ -927,7 +1711,8 @@ var ACTIONS = [
     requests: [{ method: "POST", path: "/api/v1/webhook-deliveries/:id/replay" }],
     channels: ["mcp", "n8n"],
     idempotent: true,
-    guardrails: ["The receiving system will process the event again. Confirm it is idempotent first."]
+    guardrails: ["The receiving system will process the event again. Confirm it is idempotent first."],
+    destructive: true
   },
   {
     id: "send_test_webhook",
@@ -941,7 +1726,8 @@ var ACTIONS = [
     ],
     requests: [{ method: "POST", path: "/api/v1/webhook-endpoints/:id/test" }],
     channels: ["mcp", "n8n"],
-    idempotent: true
+    idempotent: true,
+    destructive: true
   }
 ];
 
@@ -1172,7 +1958,7 @@ function validatePayload(index, input) {
 }
 
 // src/docs.ts
-var DOCS_ORIGIN = "https://docs.usethrottle.dev";
+var DOCS_ORIGIN = "https://usethrottle.dev/docs";
 function excerptAround(text, needle, radius = 160) {
   const at = text.toLowerCase().indexOf(needle.toLowerCase());
   if (at < 0) return text.slice(0, radius * 2).trim();
@@ -1256,27 +2042,35 @@ var HANDLERS = {
   // ------------------------------------------------------------- generic read
   api_get: async (ctx, args) => {
     const path = String(args.path ?? "");
-    if (!path.startsWith("/api/v1/")) {
+    const resolved = new URL(path, "https://throttle.invalid").pathname;
+    if (!path.startsWith("/api/v1/") || !resolved.startsWith("/api/v1/") || /(^|[\/\\])\.(\.)?([\/\\?#]|$)|%2e/i.test(path)) {
       throw new Error(
         `Refusing to call "${path}". api_get only reads paths beginning with /api/v1/ on the configured Throttle host.`
       );
     }
-    return ctx.client.get(path);
+    return ctx.client.get(path, void 0, { applicationId: args.applicationId });
   },
   // ------------------------------------------------------------------ orders
-  search_orders: async (ctx, args) => ctx.client.list("/api/v1/orders", {
-    q: args.q,
-    status: args.status,
-    paymentStatus: args.paymentStatus,
-    ...page(args)
-  }),
+  search_orders: async (ctx, args) => ctx.client.list(
+    "/api/v1/orders",
+    {
+      q: args.q,
+      status: args.status,
+      paymentStatus: args.paymentStatus,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
   get_order: async (ctx, args) => {
     const id = String(args.id);
-    const order = await ctx.client.get(`/api/v1/orders/${id}`);
+    const opts = { applicationId: args.applicationId };
+    const order = await ctx.client.get(`/api/v1/orders/${id}`, void 0, opts);
     const [payments, returns, fulfillments] = await Promise.all([
-      optional(() => ctx.client.list(`/api/v1/orders/${id}/payments`)),
-      optional(() => ctx.client.list(`/api/v1/orders/${id}/returns`)),
-      optional(() => ctx.client.list(`/api/v1/orders/${id}/fulfillments`))
+      optional(() => ctx.client.list(`/api/v1/orders/${id}/payments`, void 0, opts)),
+      optional(() => ctx.client.list(`/api/v1/orders/${id}/returns`, void 0, opts)),
+      optional(() => ctx.client.list(`/api/v1/orders/${id}/fulfillments`, void 0, opts))
     ]);
     return {
       order,
@@ -1286,13 +2080,23 @@ var HANDLERS = {
     };
   },
   // --------------------------------------------------------------- customers
-  search_customers: async (ctx, args) => ctx.client.list("/api/v1/customers", { q: args.q, ...page(args) }),
+  search_customers: async (ctx, args) => ctx.client.list(
+    "/api/v1/customers",
+    {
+      q: args.q,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
   get_customer: async (ctx, args) => {
     const id = String(args.id);
-    const customer = await ctx.client.get(`/api/v1/customers/${id}`);
+    const opts = { applicationId: args.applicationId };
+    const customer = await ctx.client.get(`/api/v1/customers/${id}`, void 0, opts);
     const [addresses, subscriptions] = await Promise.all([
-      optional(() => ctx.client.list(`/api/v1/customers/${id}/addresses`)),
-      optional(() => ctx.client.list("/api/v1/subscriptions", { customerId: id }))
+      optional(() => ctx.client.list(`/api/v1/customers/${id}/addresses`, void 0, opts)),
+      optional(() => ctx.client.list("/api/v1/subscriptions", { customerId: id }, opts))
     ]);
     return {
       customer,
@@ -1301,60 +2105,101 @@ var HANDLERS = {
     };
   },
   // ----------------------------------------------------------- subscriptions
-  list_subscriptions: async (ctx, args) => ctx.client.list("/api/v1/subscriptions", {
-    customerId: args.customerId,
-    status: args.status,
-    ...page(args)
+  list_subscriptions: async (ctx, args) => ctx.client.list(
+    "/api/v1/subscriptions",
+    {
+      customerId: args.customerId,
+      status: args.status,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_subscription: async (ctx, args) => ctx.client.get(`/api/v1/subscriptions/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
   }),
-  get_subscription: async (ctx, args) => ctx.client.get(`/api/v1/subscriptions/${String(args.id)}`),
   // ------------------------------------------------------------------ quotes
-  search_quotes: async (ctx, args) => ctx.client.list("/api/v1/quotes", { status: args.status, ...page(args) }),
-  get_quote: async (ctx, args) => ctx.client.get(`/api/v1/quotes/${String(args.id)}`),
+  search_quotes: async (ctx, args) => ctx.client.list(
+    "/api/v1/quotes",
+    {
+      status: args.status,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_quote: async (ctx, args) => ctx.client.get(`/api/v1/quotes/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
+  }),
   // ---------------------------------------------------------------- invoices
-  list_invoices: async (ctx, args) => ctx.client.list("/api/v1/invoices", { status: args.status, ...page(args) }),
-  receivables_aging: async (ctx) => ctx.client.get("/api/v1/invoices/aging"),
+  list_invoices: async (ctx, args) => ctx.client.list(
+    "/api/v1/invoices",
+    { status: args.status, ...page(args) },
+    { applicationId: args.applicationId }
+  ),
+  receivables_aging: async (ctx, args) => ctx.client.get("/api/v1/invoices/aging", void 0, { applicationId: args.applicationId }),
   // --------------------------------------------------------------- discounts
-  search_discounts: async (ctx, args) => ctx.client.list("/api/v1/discounts", {
-    q: args.q,
-    code: args.code,
-    type: args.type,
-    isActive: args.isActive,
-    createdAfter: args.createdAfter,
-    createdBefore: args.createdBefore,
-    ...page(args)
+  search_discounts: async (ctx, args) => ctx.client.list(
+    "/api/v1/discounts",
+    {
+      q: args.q,
+      code: args.code,
+      type: args.type,
+      isActive: args.isActive,
+      createdAfter: args.createdAfter,
+      createdBefore: args.createdBefore,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_discount: async (ctx, args) => ctx.client.get(`/api/v1/discounts/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
   }),
-  get_discount: async (ctx, args) => ctx.client.get(`/api/v1/discounts/${String(args.id)}`),
   // ---------------------------------------------------------------- payments
-  search_payments: async (ctx, args) => ctx.client.list("/api/v1/payments", {
-    method: args.method,
-    status: args.status,
-    // The route only accepts these as snake_case query params -- confirmed
-    // by reading its querystring schema directly, not assumed from the
-    // platform's usual camelCase convention.
-    order_id: args.orderId,
-    aging: args.aging,
-    due_from: args.dueFrom,
-    due_to: args.dueTo,
-    amount_min: args.amountMin,
-    amount_max: args.amountMax,
-    ...page(args)
-  }),
+  search_payments: async (ctx, args) => ctx.client.list(
+    "/api/v1/payments",
+    {
+      method: args.method,
+      status: args.status,
+      // The route only accepts these as snake_case query params -- confirmed
+      // by reading its querystring schema directly, not assumed from the
+      // platform's usual camelCase convention.
+      order_id: args.orderId,
+      aging: args.aging,
+      due_from: args.dueFrom,
+      due_to: args.dueTo,
+      amount_min: args.amountMin,
+      amount_max: args.amountMax,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
   get_payment: async (ctx, args) => {
     const id = String(args.id);
-    const payment = await ctx.client.get(`/api/v1/payments/${id}`);
-    const transactions = await optional(() => ctx.client.list(`/api/v1/payments/${id}/transactions`));
+    const opts = { applicationId: args.applicationId };
+    const payment = await ctx.client.get(`/api/v1/payments/${id}`, void 0, opts);
+    const transactions = await optional(
+      () => ctx.client.list(`/api/v1/payments/${id}/transactions`, void 0, opts)
+    );
     return {
       payment,
       transactions: transactions.ok ? transactions.value.data : transactions.unavailable
     };
   },
   // ---------------------------------------------------------------- invoices
-  get_invoice: async (ctx, args) => ctx.client.get(`/api/v1/invoices/${String(args.id)}`),
+  get_invoice: async (ctx, args) => ctx.client.get(`/api/v1/invoices/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
+  }),
   // ------------------------------------------------------------------ carts
   list_abandoned_carts: async (ctx, args) => {
+    const opts = { applicationId: args.applicationId };
     const [carts, summary] = await Promise.all([
-      optional(() => ctx.client.list("/api/v1/abandoned-carts", { ...page(args) })),
-      optional(() => ctx.client.get("/api/v1/abandoned-carts/summary", { sinceDays: args.sinceDays }))
+      optional(() => ctx.client.list("/api/v1/abandoned-carts", { ...page(args) }, opts)),
+      optional(
+        () => ctx.client.get("/api/v1/abandoned-carts/summary", { sinceDays: args.sinceDays }, opts)
+      )
     ]);
     return {
       carts: carts.ok ? carts.value.data : carts.unavailable,
@@ -1362,18 +2207,29 @@ var HANDLERS = {
     };
   },
   // --------------------------------------------------------------- debugging
-  search_events: async (ctx, args) => ctx.client.list("/api/v1/events", {
-    type: args.type,
-    entityType: args.entityType,
-    entityId: args.entityId,
-    ...page(args)
-  }),
-  list_webhook_deliveries: async (ctx, args) => ctx.client.list("/api/v1/webhook-deliveries", {
-    endpointId: args.endpointId,
-    status: args.status,
-    limit: args.limit
+  search_events: async (ctx, args) => ctx.client.list(
+    "/api/v1/events",
+    {
+      type: args.type,
+      entityType: args.entityType,
+      entityId: args.entityId,
+      ...page(args)
+    },
+    { applicationId: args.applicationId }
+  ),
+  list_webhook_deliveries: async (ctx, args) => ctx.client.list(
+    "/api/v1/webhook-deliveries",
+    {
+      endpointId: args.endpointId,
+      status: args.status,
+      eventType: args.eventType,
+      limit: args.limit
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_webhook_delivery: async (ctx, args) => ctx.client.get(`/api/v1/webhook-deliveries/${String(args.id)}`, void 0, {
+    applicationId: args.applicationId
   }),
-  get_webhook_delivery: async (ctx, args) => ctx.client.get(`/api/v1/webhook-deliveries/${String(args.id)}`),
   send_test_webhook: async (ctx, args) => ctx.client.post(`/api/v1/webhook-endpoints/${String(args.id)}/test`, {
     body: { eventType: args.eventType },
     idempotencyKey: `mcp-send-test-webhook-${String(args.id)}-${Date.now()}`
@@ -1383,18 +2239,21 @@ var HANDLERS = {
   }),
   explain_checkout_failure: async (ctx, args) => {
     const id = String(args.id);
-    const session = await optional(() => ctx.client.get(`/api/v1/checkout-sessions/${id}`));
+    const opts = { applicationId: args.applicationId };
+    const session = await optional(
+      () => ctx.client.get(`/api/v1/checkout-sessions/${id}`, void 0, opts)
+    );
     if (!session.ok) {
       return {
-        note: `No checkout session ${id} (${session.unavailable}). If this is a cart id, read the cart with api_get /api/v1/carts/${id} and search_events for its activity.`
+        note: `No checkout session ${id} (${session.unavailable}). If this is a cart id, use search_events for its activity (or read /api/v1/carts/${id} with api_get, where that tool is available).`
       };
     }
     const cartId = session.value?.cartId ?? void 0;
     const [cart, sessionEvents, cartEvents, deliveries] = await Promise.all([
-      optional(() => ctx.client.get(`/api/v1/checkout-sessions/${id}/cart`)),
-      optional(() => ctx.client.list("/api/v1/events", { entityId: id, limit: 25 })),
-      cartId ? optional(() => ctx.client.list("/api/v1/events", { entityId: cartId, limit: 25 })) : Promise.resolve({ ok: true, value: { data: [], pagination: null } }),
-      optional(() => ctx.client.list("/api/v1/webhook-deliveries", { limit: 15 }))
+      optional(() => ctx.client.get(`/api/v1/checkout-sessions/${id}/cart`, void 0, opts)),
+      optional(() => ctx.client.list("/api/v1/events", { entityId: id, limit: 25 }, opts)),
+      cartId ? optional(() => ctx.client.list("/api/v1/events", { entityId: cartId, limit: 25 }, opts)) : Promise.resolve({ ok: true, value: { data: [], pagination: null } }),
+      optional(() => ctx.client.list("/api/v1/webhook-deliveries", { limit: 15 }, opts))
     ]);
     return {
       session: session.value,
@@ -1454,6 +2313,73 @@ var HANDLERS = {
       note: "Seeded a finalized DRAFT order. No payment was captured \u2014 that needs a browser-tokenised payment method, which a server-side key cannot produce."
     };
   },
+  // ---------------------------------------------------------- inbound writes
+  create_customer: async (ctx, args) => ctx.client.post("/api/v1/customers", {
+    // `createCustomerBody` is `.strict()`, so only fields it declares may be
+    // sent; `undefined` values drop out at JSON.stringify.
+    body: {
+      email: args.email,
+      firstName: args.firstName,
+      lastName: args.lastName,
+      phone: args.phone,
+      company: args.company,
+      externalId: args.externalId,
+      netN: args.netN,
+      acceptsMarketing: args.acceptsMarketing
+    },
+    idempotencyKey: `mcp-create-customer-${String(args.email)}-${Date.now()}`
+  }),
+  update_customer: async (ctx, args) => ctx.client.patch(`/api/v1/customers/${String(args.id)}`, {
+    // `id` is the path parameter, not a body field — `updateCustomerBody` is
+    // `.strict()` and would reject it. A null `externalId` is meaningful
+    // (it clears the value), so only `undefined` is dropped.
+    body: {
+      email: args.email,
+      firstName: args.firstName,
+      lastName: args.lastName,
+      phone: args.phone,
+      company: args.company,
+      externalId: args.externalId,
+      netN: args.netN,
+      acceptsMarketing: args.acceptsMarketing
+    },
+    idempotencyKey: `mcp-update-customer-${String(args.id)}-${Date.now()}`
+  }),
+  create_checkout_link: async (ctx, args) => {
+    const lineItems = Array.isArray(args.lineItems) ? args.lineItems : [];
+    if (lineItems.length === 0) {
+      throw new Error("create_checkout_link: lineItems must contain at least one item.");
+    }
+    const stamp = Date.now();
+    const applicationId = ctx.identity.application?.id;
+    const cart = await ctx.client.post("/api/v1/carts", {
+      body: {
+        applicationId,
+        customerId: args.customerId,
+        customerEmail: args.customerEmail,
+        netN: args.netN
+      },
+      idempotencyKey: `mcp-checkout-link-cart-${stamp}`
+    });
+    for (const [index, item] of lineItems.entries()) {
+      await ctx.client.post(`/api/v1/carts/${cart?.id}/items`, {
+        body: item,
+        idempotencyKey: `mcp-checkout-link-item-${stamp}-${index}`
+      });
+    }
+    const session = await ctx.client.post("/api/v1/checkout/sessions", {
+      body: {
+        applicationId,
+        cartId: cart?.id,
+        returnUrl: args.returnUrl,
+        cancelUrl: args.cancelUrl,
+        customerEmail: args.customerEmail,
+        discountCode: args.discountCode
+      },
+      idempotencyKey: `mcp-checkout-link-session-${stamp}`
+    });
+    return { cartId: cart?.id, ...session };
+  },
   // -------------------------------------------------------------- money/mail
   manage_subscription: async (ctx, args) => {
     const id = String(args.id);
@@ -1483,17 +2409,118 @@ var HANDLERS = {
       idempotencyKey: `mcp-create-quote-${String(args.customerId)}-${Date.now()}`
     })
   ),
-  get_business_summary: async (ctx, args) => ctx.client.get("/api/v1/analytics/business-summary", { period: args.period }),
-  get_attention_digest: async (ctx) => ctx.client.get("/api/v1/analytics/attention-digest"),
+  get_sales_timeseries: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/orders-timeseries",
+    {
+      from: args.from,
+      to: args.to,
+      groupBy: args.groupBy,
+      timezone: args.timezone,
+      compareTo: args.compareTo
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_business_summary: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/business-summary",
+    {
+      period: args.period,
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone
+    },
+    { applicationId: args.applicationId }
+  ),
+  get_attention_digest: async (ctx, args) => ctx.client.get("/api/v1/analytics/attention-digest", void 0, {
+    applicationId: args.applicationId
+  }),
+  get_top_products: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/products",
+    {
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone,
+      by: args.by,
+      limit: args.limit
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, signups, ordersByCustomerType, topCustomers, totals } }`), and
+  // `.list()` only unwraps arrays: it would silently return an empty list
+  // instead of the real payload.
+  get_customer_growth: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/customers",
+    {
+      from: args.from,
+      to: args.to,
+      groupBy: args.groupBy,
+      timezone: args.timezone,
+      topBy: args.topBy,
+      topLimit: args.topLimit
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, dimension, rows, totals, note } }`), not a paginated array.
+  get_revenue_breakdown: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/revenue-breakdown",
+    {
+      dimension: args.dimension,
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, stages, conversionRate, dropOff, note } }`), not a paginated array.
+  get_funnel_conversion: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/funnel",
+    {
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, series, totals, note } }`), not a paginated array.
+  get_subscription_movement: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/subscriptions",
+    {
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone,
+      groupBy: args.groupBy
+    },
+    { applicationId: args.applicationId }
+  ),
+  // `.get()`, not `.list()` — the response is a single object (`{ data: {
+  // range, rows, totals, note } }`), not a paginated array.
+  get_discount_performance: async (ctx, args) => ctx.client.get(
+    "/api/v1/analytics/discounts",
+    {
+      from: args.from,
+      to: args.to,
+      timezone: args.timezone,
+      limit: args.limit
+    },
+    { applicationId: args.applicationId }
+  ),
   // ------------------------------------------------------------- extensions
-  list_extension_installations: async (ctx, args) => ctx.client.list("/api/v1/installations", { status: args.status, ...page(args) }),
+  list_extension_installations: async (ctx, args) => ctx.client.list(
+    "/api/v1/installations",
+    { status: args.status, ...page(args) },
+    { applicationId: args.applicationId }
+  ),
   // ------------------------------------------------------------- connectors
-  get_connector_routing: async (ctx) => {
+  get_connector_routing: async (ctx, args) => {
+    const opts = { applicationId: args.applicationId };
     const [paymentRouting, routingConnectors, cardDecline, otherDecline] = await Promise.all([
-      optional(() => ctx.client.get("/api/v1/payment-routing")),
-      optional(() => ctx.client.get("/api/v1/routing-connectors")),
-      optional(() => ctx.client.get("/api/v1/card-decline")),
-      optional(() => ctx.client.get("/api/v1/other-decline"))
+      optional(() => ctx.client.get("/api/v1/payment-routing", void 0, opts)),
+      optional(() => ctx.client.get("/api/v1/routing-connectors", void 0, opts)),
+      optional(() => ctx.client.get("/api/v1/card-decline", void 0, opts)),
+      optional(() => ctx.client.get("/api/v1/other-decline", void 0, opts))
     ]);
     return {
       paymentRouting: paymentRouting.ok ? paymentRouting.value : paymentRouting.unavailable,
@@ -1502,24 +2529,37 @@ var HANDLERS = {
       otherDecline: otherDecline.ok ? otherDecline.value : otherDecline.unavailable
     };
   },
-  get_integration_status: async (ctx) => {
+  get_integration_status: async (ctx, args) => {
+    const opts = { applicationId: args.applicationId };
     const [connectors, endpoints, coverage] = await Promise.all([
-      optional(() => ctx.client.list("/api/v1/connectors")),
-      optional(() => ctx.client.list("/api/v1/webhook-endpoints")),
-      optional(() => ctx.client.get("/api/v1/webhook-endpoints/coverage"))
+      optional(() => ctx.client.list("/api/v1/connectors", void 0, opts)),
+      optional(() => ctx.client.list("/api/v1/webhook-endpoints", void 0, opts)),
+      optional(() => ctx.client.get("/api/v1/webhook-endpoints/coverage", void 0, opts))
     ]);
+    const overridden = Boolean(args.applicationId) && args.applicationId !== ctx.identity.application?.id;
     return {
       environment: ctx.identity.environment,
       workspace: ctx.identity.workspace,
-      application: ctx.identity.application,
+      applicationId: args.applicationId ?? ctx.identity.application?.id ?? null,
+      application: overridden ? void 0 : ctx.identity.application,
       connectors: connectors.ok ? connectors.value.data : connectors.unavailable,
       webhookEndpoints: endpoints.ok ? endpoints.value.data : endpoints.unavailable,
       unsubscribedEvents: coverage.ok ? coverage.value : coverage.unavailable
     };
   },
   // --------------------------------------------------------------- workspace
+  // No applicationId forwarding here: /api/v1/merchants/me is workspace-only
+  // (`WHERE workspace_id = ...`, never reads auth.applicationId) — an
+  // applicationId field on this tool would be a silent no-op affordance.
   get_workspace_settings: async (ctx) => ctx.client.get("/api/v1/merchants/me"),
-  get_audit_log: async (ctx, args) => ctx.client.list("/api/v1/audit-log", { limit: args.limit })
+  // No applicationId forwarding here either: /api/v1/audit-log filters by
+  // workspaceId (and optionally environmentId), never applicationId.
+  get_audit_log: async (ctx, args) => ctx.client.list("/api/v1/audit-log", { limit: args.limit }),
+  // --------------------------------------------------------- applications
+  // `.get()`, not `.list()` — the legacy /v1/stores route returns a bare
+  // array with no `meta.pagination`, and the brief calls for `.get()` here
+  // specifically.
+  list_applications: async (ctx) => ctx.client.get("/api/v1/stores")
 };
 
 // src/input.ts
@@ -1554,15 +2594,548 @@ function applyModifiers(field, type) {
   return field.default === void 0 ? described.optional() : described.default(field.default);
 }
 
+// src/projection.ts
+var S = "scalar";
+var T = "text";
+var PASS = "pass";
+var section = (shape) => ({ __section: shape });
+var oneOf = (values) => ({ __oneOf: new Set(values) });
+function isPrimitive(value) {
+  return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+var TOKEN = /^[^\s@]{0,200}$/;
+var OMITTED = { omitted: S, grantable: T, reason: T };
+var UNAVAILABLE = /^(not readable with this credential \(missing scope\)|not found|unavailable \([^\s@]{0,100}\))$/;
+function project(value, shape) {
+  if (value === void 0) return void 0;
+  if (shape === PASS) return value;
+  if (shape === S) {
+    if (!isPrimitive(value)) return void 0;
+    return typeof value === "string" && !TOKEN.test(value) ? null : value;
+  }
+  if (shape === T) return isPrimitive(value) ? value : void 0;
+  if ("__oneOf" in shape) {
+    if (!isPrimitive(value)) return void 0;
+    return typeof value === "string" && !shape.__oneOf.has(value) ? null : value;
+  }
+  if (Array.isArray(shape)) {
+    return Array.isArray(value) ? value.map((item) => project(item, shape[0])) : void 0;
+  }
+  if ("__section" in shape) {
+    if (typeof value === "string") return UNAVAILABLE.test(value) ? value : null;
+    if (value && typeof value === "object" && value.omitted === true) {
+      return project(value, OMITTED);
+    }
+    return project(value, shape.__section);
+  }
+  if (value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return void 0;
+  const out = {};
+  for (const [key, child] of Object.entries(shape)) {
+    const projected = project(value[key], child);
+    if (projected !== void 0) out[key] = projected;
+  }
+  return out;
+}
+var PAGINATION = { cursor: S, nextCursor: S, hasMore: S };
+var page2 = (row) => ({ data: [row], pagination: PAGINATION });
+var ADDRESS = { countryCode: S };
+var CUSTOMER_REF = { id: S };
+var APPLICATION = { id: S, name: T, slug: S };
+var LIFECYCLE_LABELS = ["Draft", "Pending", "Processing", "Partially fulfilled", "Fulfilled", "Cancelled", "Closed"];
+var DISPLAY_QUALIFIERS = [
+  "Comped",
+  "Awaiting payment",
+  "Authorized",
+  "Partially paid",
+  "Partially refunded",
+  "Refunded",
+  "Payment failed",
+  "Voided",
+  "Payment processing",
+  "Disputed",
+  "Authorization expired",
+  "Returned",
+  "Partially returned",
+  "Delivered",
+  "In transit"
+];
+var ORDER_DISPLAY_STATUSES = new Set(
+  LIFECYCLE_LABELS.flatMap((l) => [l, ...DISPLAY_QUALIFIERS.map((q) => `${l} \xB7 ${q}`)])
+);
+var DISPLAY_STATUS = oneOf(ORDER_DISPLAY_STATUSES);
+var RANGE = { from: S, to: S, timezone: S, groupBy: S };
+var LINE_ITEM = {
+  id: S,
+  type: S,
+  quantity: S,
+  unitPrice: S,
+  subtotal: S,
+  discountAmount: S,
+  taxAmount: S,
+  total: S,
+  recurring: S
+};
+var ORDER = {
+  id: S,
+  orderNumber: S,
+  status: S,
+  displayStatus: DISPLAY_STATUS,
+  paymentStatus: S,
+  type: S,
+  source: S,
+  currency: S,
+  subtotal: S,
+  discountTotal: S,
+  shippingTotal: S,
+  taxTotal: S,
+  total: S,
+  capturedAmount: S,
+  refundedAmount: S,
+  compAmount: S,
+  onHold: S,
+  taxReverseCharge: S,
+  customerId: S,
+  customer: CUSTOMER_REF,
+  subscriptionId: S,
+  shippingAddress: ADDRESS,
+  billingAddress: ADDRESS,
+  fulfillmentSummary: { itemsFulfilled: S, itemsRemaining: S, itemsTotal: S },
+  lineItems: [LINE_ITEM],
+  createdAt: S,
+  completedAt: S,
+  cancelledAt: S,
+  closedAt: S
+};
+var PAYMENT = {
+  id: S,
+  orderId: S,
+  status: S,
+  method: S,
+  processor: S,
+  amount: S,
+  capturedAmount: S,
+  currency: S,
+  cardBrand: S,
+  disputed: S,
+  disputeOpenedAt: S,
+  errorCode: S,
+  netN: S,
+  netNSource: S,
+  authorizedAt: S,
+  capturedAt: S,
+  voidedAt: S,
+  createdAt: S
+};
+var RETURN = {
+  id: S,
+  orderId: S,
+  status: S,
+  restock: S,
+  refundAmount: S,
+  refundPaymentId: S,
+  createdAt: S,
+  items: [{ lineItemId: S, quantity: S }]
+};
+var FULFILLMENT = {
+  id: S,
+  orderId: S,
+  type: S,
+  status: S,
+  createdAt: S,
+  lineItems: [{ lineItemId: S, quantity: S }],
+  detail: { carrier: T, serviceLevel: T, trackingNumber: T, trackingUrl: T, shippedAt: S, estimatedDelivery: S, actualDelivery: S }
+};
+var CUSTOMER = { id: S, netN: S, acceptsMarketing: S, createdAt: S };
+var SUBSCRIPTION = {
+  id: S,
+  status: S,
+  planName: T,
+  planReference: T,
+  amount: S,
+  currency: S,
+  interval: S,
+  quantity: S,
+  intervalUnit: S,
+  intervalCount: S,
+  totalPayments: S,
+  paymentsMade: S,
+  completedAt: S,
+  customerId: S,
+  customer: CUSTOMER_REF,
+  currentPeriodStart: S,
+  currentPeriodEnd: S,
+  billingAnchorAt: S,
+  cancelAtPeriodEnd: S,
+  trialEnd: S,
+  pausedAt: S,
+  cancelledAt: S,
+  lastPaymentAt: S,
+  failureCount: S,
+  pendingPlanName: T,
+  pendingPlanReference: T,
+  pendingAmount: S,
+  pendingInterval: S,
+  pendingQuantity: S,
+  pendingIntervalUnit: S,
+  pendingIntervalCount: S,
+  createdAt: S
+};
+var QUOTE_SUMMARY = {
+  id: S,
+  quoteNumber: S,
+  status: S,
+  source: S,
+  currency: S,
+  total: S,
+  customerId: S,
+  orderId: S,
+  expiresAt: S,
+  acceptedAt: S,
+  declinedAt: S,
+  createdAt: S
+};
+var QUOTE = {
+  ...QUOTE_SUMMARY,
+  revisions: [{
+    id: S,
+    revisionNumber: S,
+    state: S,
+    subtotal: S,
+    discountTotal: S,
+    shippingTotal: S,
+    taxTotal: S,
+    total: S,
+    depositAmount: S,
+    shippingMode: S,
+    issuedAt: S,
+    expiresAt: S,
+    paymentTerms: { mode: S, netN: S, balanceNetN: S, deposit: { type: S, value: S } },
+    items: [{
+      type: S,
+      quantity: S,
+      unitPrice: S,
+      subtotal: S,
+      discountAmount: S,
+      taxAmount: S,
+      total: S,
+      optional: S,
+      optionalSelected: S
+    }]
+  }],
+  // Who commented and when, never what they wrote.
+  comments: [{ authorType: S, visibility: S, createdAt: S }],
+  timeline: [{ type: S, actorType: S, createdAt: S }]
+};
+var INVOICE = {
+  id: S,
+  number: S,
+  status: S,
+  sourceType: S,
+  sourceId: S,
+  customerId: S,
+  currency: S,
+  subtotal: S,
+  discountTotal: S,
+  shippingTotal: S,
+  taxTotal: S,
+  total: S,
+  amountRefunded: S,
+  issuedAt: S,
+  dueAt: S,
+  periodStart: S,
+  periodEnd: S,
+  createdAt: S,
+  billingSnapshot: {
+    planName: T,
+    period: { start: S, end: S },
+    lineItems: [{ quantity: S, unitPrice: S, discountAmount: S, taxAmount: S, total: S }],
+    totals: { currency: S, subtotal: S, discountTotal: S, shippingTotal: S, taxTotal: S, total: S },
+    payment: { method: S, brand: S, status: S }
+  }
+};
+var DISCOUNT = {
+  id: S,
+  code: T,
+  name: T,
+  type: S,
+  value: S,
+  isActive: S,
+  startsAt: S,
+  endsAt: S,
+  usageCount: S,
+  usageLimit: S,
+  maxRedemptionsPerCustomer: S,
+  createdAt: S
+};
+var EVENT = {
+  id: S,
+  type: S,
+  entityType: S,
+  entityId: S,
+  createdAt: S,
+  data: {
+    status: S,
+    previousStatus: S,
+    action: S,
+    amount: S,
+    currency: S,
+    attempt: S,
+    orderId: S,
+    paymentId: S,
+    order: { id: S, orderNumber: S, status: S, paymentStatus: S, currency: S, total: S },
+    payment: { id: S, orderId: S, status: S, method: S, amount: S, currency: S },
+    subscription: { id: S, status: S, planName: T, amount: S, currency: S, interval: S },
+    fulfillment: { id: S, orderId: S, type: S, status: S }
+  }
+};
+var DELIVERY = {
+  id: S,
+  endpointId: S,
+  eventId: S,
+  eventType: S,
+  status: S,
+  attemptCount: S,
+  lastStatus: S,
+  deliveredAt: S,
+  nextRetryAt: S,
+  createdAt: S,
+  replayOf: S
+};
+var MONEY_COUNT = { count: S, totalCents: S };
+var ORDER_PERIOD = { orderCount: S, grossCents: S, netCents: S, refundsCents: S, avgOrderCents: S };
+var OAUTH_PROJECTIONS = {
+  whoami: {
+    type: S,
+    workspace: { name: T, slug: S },
+    application: APPLICATION,
+    environment: { slug: S, kind: S, providerEnvironment: S },
+    note: T
+  },
+  search_docs: PASS,
+  describe_endpoint: PASS,
+  validate_payload: PASS,
+  search_orders: page2(ORDER),
+  get_order: {
+    order: ORDER,
+    payments: section([PAYMENT]),
+    returns: section([RETURN]),
+    fulfillments: section([FULFILLMENT])
+  },
+  search_customers: page2(CUSTOMER),
+  get_customer: {
+    customer: CUSTOMER,
+    addresses: section([{ id: S, isDefault: S, ...ADDRESS }]),
+    subscriptions: section([SUBSCRIPTION])
+  },
+  list_subscriptions: page2(SUBSCRIPTION),
+  get_subscription: SUBSCRIPTION,
+  search_quotes: page2(QUOTE_SUMMARY),
+  get_quote: QUOTE,
+  list_invoices: page2(INVOICE),
+  get_invoice: INVOICE,
+  receivables_aging: {
+    buckets: [{ key: S, label: T, count: S, total_amount: S }],
+    total_outstanding_amount: S,
+    total_outstanding_count: S
+  },
+  search_discounts: page2(DISCOUNT),
+  get_discount: DISCOUNT,
+  search_payments: page2(PAYMENT),
+  get_payment: {
+    payment: PAYMENT,
+    transactions: section([{ id: S, type: S, status: S, amount: S, currency: S, createdAt: S }])
+  },
+  list_abandoned_carts: {
+    carts: section([{
+      id: S,
+      abandonedAt: S,
+      currency: S,
+      itemCount: S,
+      recoveryStatus: S,
+      total: S,
+      customer: { id: S }
+    }]),
+    summary: section({ abandonedCount: S, abandonedValue: S, recoveryEmailsSent: S, sinceDays: S })
+  },
+  search_events: page2(EVENT),
+  list_webhook_deliveries: page2(DELIVERY),
+  get_webhook_delivery: DELIVERY,
+  explain_checkout_failure: {
+    note: T,
+    hint: T,
+    session: {
+      id: S,
+      status: S,
+      cartId: S,
+      customerId: S,
+      expiresAt: S,
+      completedAt: S,
+      allowedMethods: [S],
+      collect: { shippingAddress: S, billingAddress: S, vatNumber: S },
+      shippingAddress: ADDRESS,
+      billingAddress: ADDRESS,
+      recurringTerms: {
+        interval: S,
+        intervalUnit: S,
+        intervalCount: S,
+        totalPayments: S,
+        taxApplies: S,
+        planChargedToday: S,
+        planName: T,
+        trialDays: S,
+        currency: S,
+        firstChargeAmountMinor: S
+      }
+    },
+    cart: section({
+      id: S,
+      status: S,
+      currency: S,
+      subtotal: S,
+      discountTotal: S,
+      shippingTotal: S,
+      taxTotal: S,
+      total: S,
+      itemCount: S,
+      items: [LINE_ITEM],
+      lineItems: [LINE_ITEM]
+    }),
+    events: [EVENT],
+    eventsUnavailable: T,
+    recentWebhookDeliveries: section([DELIVERY])
+  },
+  list_extension_installations: page2({
+    id: S,
+    extensionId: S,
+    extensionName: T,
+    extensionSlug: S,
+    versionId: S,
+    status: S,
+    environmentSlug: S,
+    installedAt: S,
+    uninstalledAt: S
+  }),
+  get_connector_routing: {
+    paymentRouting: section({
+      defaultCascade: [S],
+      rules: [{ cascade: [S], conditions: [{ type: S, op: S, currency: S, min: S, max: S, values: [S] }] }]
+    }),
+    cardDecline: section({ rules: [{ errorCode: S, conditions: [{ type: S, op: S, values: [S] }] }] }),
+    otherDecline: section({ rules: [{ errorCode: S, conditions: [{ type: S, op: S, values: [S] }] }] }),
+    routingConnectors: section([{ id: S, displayName: T, method: S }])
+  },
+  get_integration_status: {
+    environment: { slug: S, kind: S, providerEnvironment: S },
+    workspace: { name: T, slug: S },
+    applicationId: S,
+    application: APPLICATION,
+    connectors: section([{
+      id: S,
+      displayName: T,
+      method: S,
+      type: S,
+      status: S,
+      active: S,
+      position: S,
+      acceptedCountries: [S],
+      acceptedCurrencies: [S],
+      threeDSecureEnabled: S,
+      createdAt: S
+    }]),
+    webhookEndpoints: section([{ id: S, isActive: S, enabledEvents: [S], createdAt: S }]),
+    unsubscribedEvents: section({ windowDays: S, unsubscribed: [{ type: S, count: S, lastEmittedAt: S }] })
+  },
+  get_workspace_settings: { name: T, slug: S, brandColor: S, logoUrl: T, onboardingCompletedAt: S },
+  // What happened and to which record; not which team member did it.
+  get_audit_log: page2({ id: S, action: S, resourceType: S, resourceId: S, createdAt: S }),
+  list_applications: [{ id: S, name: T, slug: S, currency: S, isActive: S }],
+  // Analytics: computed aggregates, listed field by field all the same.
+  get_business_summary: {
+    period: S,
+    range: RANGE,
+    orders: section({ current: ORDER_PERIOD, previous: ORDER_PERIOD, deltaPct: S }),
+    subscriptions: section({
+      mrr: { currentCents: S, periodStartCents: S, deltaPct: S },
+      newSubscriptions: S,
+      cancelledSubscriptions: S,
+      churnRate: S,
+      note: T
+    }),
+    receivables: section({ outstandingCents: S, outstandingCount: S }),
+    quotes: section({ sent: MONEY_COUNT, accepted: MONEY_COUNT, declined: MONEY_COUNT, expired: MONEY_COUNT })
+  },
+  get_attention_digest: {
+    disputes: section({ open: S, totalCents: S }),
+    subscriptionsInDunning: section(S),
+    overdueInvoices: section(MONEY_COUNT),
+    unhealthyWebhooks: section([{ endpointId: S, failureRate: S, attempts7d: S }])
+  },
+  get_sales_timeseries: {
+    application: APPLICATION,
+    range: RANGE,
+    currency: S,
+    days: S,
+    note: T,
+    series: [{ date: S, grossCents: S, orders: S }],
+    totalGrossCents: S,
+    totalOrders: S
+  },
+  // get_top_products has no entry, so it is not offered over OAuth: it ranks
+  // products by line-item reference id or name, which a buyer can type.
+  get_customer_growth: {
+    application: APPLICATION,
+    range: RANGE,
+    note: T,
+    topBy: S,
+    signups: { total: S, series: [{ date: S, signups: S }] },
+    ordersByCustomerType: { newCustomerOrders: S, returningCustomerOrders: S },
+    // The ranking, by id: a top customer's name and email stay behind.
+    topCustomers: [{ customerId: S, orderCount: S, revenueCents: S }],
+    totals: { customerCount: S, orderCount: S, revenueCents: S }
+  },
+  get_revenue_breakdown: {
+    application: APPLICATION,
+    range: RANGE,
+    dimension: S,
+    note: T,
+    rows: [{ key: S, orderCount: S, grossCents: S }],
+    totals: { orderCount: S, grossCents: S }
+  },
+  get_funnel_conversion: {
+    application: APPLICATION,
+    range: RANGE,
+    note: T,
+    conversionRate: S,
+    stages: [{ name: S, count: S }],
+    dropOff: [{ from: S, to: S, ratePct: S }]
+  },
+  get_subscription_movement: {
+    application: APPLICATION,
+    range: RANGE,
+    note: T,
+    series: [{ date: S, newSubscriptions: S, churnedSubscriptions: S, mrrDeltaCents: S }],
+    totals: { newSubscriptions: S, churnedSubscriptions: S, netMrrDeltaCents: S }
+  },
+  get_discount_performance: {
+    application: APPLICATION,
+    range: RANGE,
+    note: T,
+    rows: [{ discountId: S, code: T, redemptions: S, discountedRevenueCents: S, discountGivenCents: S }],
+    totals: { redemptions: S, discountedRevenueCents: S, discountGivenCents: S }
+  }
+};
+
 // src/server.ts
-var VERSION = true ? "0.2.0" : "0.0.0-dev";
+var VERSION = true ? "0.2.2" : "0.0.0-dev";
 function registerableActions(policy) {
   const isProduction = policy.identity.environment.providerEnvironment === "production";
   return actionsForChannel("mcp").filter((action) => {
     if (!HANDLERS[action.id]) return false;
+    if (action.credentialScoped && policy.allowCredentialScoped === false) return false;
     if (!canRunAction(policy.identity.scopes, action)) return false;
     if (action.kind === "read") return true;
-    if (action.sandboxOnly) return !isProduction;
+    if (action.sandboxOnly) return !isProduction && (policy.allowSandboxWrites ?? true);
     if (!policy.allowWrites) return false;
     return !isProduction || policy.allowLiveWrites;
   });
@@ -1579,11 +3152,14 @@ function buildInstructions(identity, actions, policy) {
     `Throttle MCP ${VERSION}. Connected to ${where}, environment "${identity.environment.slug}" (${isProduction ? "PRODUCTION \u2014 live data" : "non-production \u2014 not live data"}).`,
     "",
     "Conventions:",
-    "- Every tool is scoped to this one workspace/application/environment; there is no way to switch from inside a tool call. Call whoami if you need to state where you are.",
+    "- The workspace and environment are fixed for this session and cannot be switched from inside a tool call. Call whoami if you need to state where you are.",
+    '- The application can vary per call: pass "applicationId" on a read or analytics tool to reach a different application in this workspace, and call list_applications to see which ones this connection can reach. Omitting applicationId uses the application this connection was authorized for.',
+    "- Every analytics result covers exactly ONE application and names it in `application`. Say which application a figure describes. If the user asks about their business as a whole and this connection reaches more than one application, do not answer from the default alone \u2014 call list_applications, then query each and add them up, or ask which application they mean.",
     '- List tools return { data, pagination }. When pagination.hasMore is true, pass pagination.cursor back as "cursor" rather than raising "limit".',
     "- Amounts are integer minor units (2500 = $25.00).",
     "- Throttle rejects snake_case on public request bodies. Before writing integration code, confirm shapes with describe_endpoint and check bodies with validate_payload instead of guessing field names.",
-    "- API errors come back as text with a stable code. On insufficient_scopes, tell the user which scope to add \u2014 do not retry."
+    "- API errors come back as text with a stable code. On insufficient_scopes, tell the user which scope to add \u2014 do not retry.",
+    "- Analytics results may mark a section `omitted`. That means UNKNOWN, never zero. When `grantable` is false the data cannot be read over this connection at all \u2014 say so rather than reporting an absence."
   ];
   if (liveWrites.length === 0) {
     lines.push(
@@ -1601,8 +3177,31 @@ function buildInstructions(identity, actions, policy) {
   }
   return lines.join("\n");
 }
+function declareSecuritySchemes(server, actions) {
+  const inner = server.server;
+  const handlers = inner._requestHandlers;
+  const original = handlers?.get("tools/list");
+  if (!original) return;
+  const schemes = new Map(
+    actions.map((a) => [
+      a.id,
+      [{
+        type: "oauth2",
+        scopes: [.../* @__PURE__ */ new Set([...a.scopes, ...a.sectionScopes ?? []])].filter((scope) => validateScopesForOAuth([scope]).ok)
+      }]
+    ])
+  );
+  inner.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+    const result = await original(request, extra);
+    return {
+      ...result,
+      tools: result.tools.map((tool) => ({ ...tool, securitySchemes: schemes.get(tool.name) ?? [{ type: "oauth2", scopes: [] }] }))
+    };
+  });
+}
 function createServer(options) {
-  const actions = registerableActions(options);
+  const redactPii = options.identity.type === "oauth_token" && !hasScope(options.identity.scopes, "customer_pii:read");
+  const actions = registerableActions(options).filter((a) => !redactPii || OAUTH_PROJECTIONS[a.id] !== void 0);
   const server = new McpServer(
     { name: "throttle", version: VERSION },
     { instructions: buildInstructions(options.identity, actions, options) }
@@ -1615,25 +3214,57 @@ function createServer(options) {
   };
   for (const action of actions) {
     const handler = HANDLERS[action.id];
-    server.tool(
+    server.registerTool(
       action.id,
-      describeForModel(action),
-      fieldsToZodShape(action.input),
+      {
+        title: action.title,
+        description: describeForModel(action),
+        inputSchema: fieldsToZodShape(action.input),
+        // Every hint is an explicit boolean: directory reviews (OpenAI's in
+        // particular) read a missing value as "unknown", not as false.
+        annotations: {
+          title: action.title,
+          readOnlyHint: action.kind === "read",
+          destructiveHint: action.kind === "write" && Boolean(action.destructive),
+          idempotentHint: Boolean(action.idempotent),
+          // Every tool is bounded to the connected workspace; none reaches the
+          // public internet or an open-ended set of external entities.
+          openWorldHint: false
+        }
+      },
       async (args) => {
         try {
+          if (redactPii && action.id === "search_customers" && typeof args?.q === "string" && args.q.trim() !== "") {
+            return {
+              content: [{ type: "text", text: "Customer text search is not available over this connection, because names, emails, phone numbers and external ids are withheld. List customers by creation date (createdAfter/createdBefore), or open one by its Throttle id from an order, quote or subscription." }],
+              isError: true
+            };
+          }
           const result = await handler(ctx, args ?? {});
-          return { content: [{ type: "text", text: formatResult(result) }] };
+          const shown = redactPii ? redactShopperPii(project(result, OAUTH_PROJECTIONS[action.id])) : result;
+          return { content: [{ type: "text", text: formatResult(shown) }] };
         } catch (error) {
           return {
             content: [{ type: "text", text: formatError(error) }],
-            isError: true
+            isError: true,
+            ...options.authChallenge && isCredentialRejection(error) ? {
+              _meta: {
+                "mcp/www_authenticate": [
+                  `${options.authChallenge}, error="invalid_token", error_description="The connected credential was rejected. Sign in again to continue."`
+                ]
+              }
+            } : {}
           };
         }
       }
     );
   }
+  if (options.authChallenge) declareSecuritySchemes(server, actions);
   return server;
 }
+function isCredentialRejection(error) {
+  return error?.statusCode === 401;
+}
 function describeForModel(action) {
   const parts = [action.description];
   if (action.guardrails && action.guardrails.length > 0) {