@honkio/mcp 1.4.0 → 1.6.0

package/dist/tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { HonkioError } from './client.js';
+import { meta } from './toolMeta.js';
 const DNCL_EXEMPTIONS = [
     'existing_business_relationship',
     'registered_charity',
@@ -8,7 +9,11 @@ const DNCL_EXEMPTIONS = [
     'newspaper_subscription',
     'personal',
 ];
-const WEBHOOK_EVENTS = [
+// Copied from api/src/services/webhookDelivery.ts (WebhookEventType) minus
+// the email.*/email_domain.* events — the email product has no MCP surface
+// yet. Keep the two lists in step (see webhookEvents.test.ts). Exported so
+// that test can compare it against the API source without duplicating it.
+export const WEBHOOK_EVENTS = [
     'message.queued',
     'message.sending',
     'message.sent',
@@ -21,14 +26,84 @@ const WEBHOOK_EVENTS = [
     'account.delivery_warning',
     'account.sending_paused',
     'account.spend_warning',
+    'phone_number.suspended',
+    'phone_number.released',
 ];
+// Copied from api/src/permissions.ts (RESOURCES) — the resource names an API
+// key's permissions object may name. Keep the two lists in step (see
+// permissionResources.test.ts). Exported so that test can compare it against
+// the API source without duplicating it.
+export const PERMISSION_RESOURCES = [
+    'messages',
+    'phone_numbers',
+    'contacts',
+    'contact_groups',
+    'lists',
+    'compliance',
+    'webhooks',
+    'verify',
+    'account',
+    'api_keys',
+    'emails',
+    'email_domains',
+    'email_suppressions',
+];
+const PERMISSIONS_ARG = z
+    .record(z.string(), z.string())
+    .refine((perms) => Object.entries(perms).every(([resource, ops]) => PERMISSION_RESOURCES.includes(resource) && /^[rwmd]*$/.test(ops)), { message: `Resource names must be one of: ${PERMISSION_RESOURCES.join(', ')}. Each value is a string made only of r, w, m, d.` })
+    .optional()
+    .describe('Per-resource permissions: each key is a resource name (' + PERMISSION_RESOURCES.join(', ') +
+    '), each value a string of allowed operations (r=read, w=write, m=modify, d=delete). Omit a resource to deny it. ' +
+    'Omit this whole field to default to the calling key\'s own permissions. A key can only be created with permissions the calling key itself holds.');
 function ok(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
-function formatError(err) {
+// Since Task 8.1, a VALIDATION_ERROR's top-level `message` is the generic
+// bilingual sentence ("Request validation failed."); the field-specific text
+// an agent needs to self-correct a bad call moved into `details` — an AJV
+// array of `{instancePath, message, ...}` entries. Other error codes (e.g.
+// the suspended/closed 403) carry an ad hoc object there instead
+// (`{reason: 'account_suspended'}`). Render whichever shape it is, so that
+// text isn't lost.
+const DETAILS_CHAR_CAP = 1000;
+function isAjvDetails(details) {
+    return Array.isArray(details) && details.length > 0 &&
+        details.every((d) => d && typeof d === 'object' && 'instancePath' in d && 'message' in d);
+}
+function formatDetails(details) {
+    const rendered = isAjvDetails(details)
+        ? details.map((d) => `${d.instancePath} ${d.message}`).join('\n')
+        : JSON.stringify(details);
+    return rendered.length > DETAILS_CHAR_CAP ? `${rendered.slice(0, DETAILS_CHAR_CAP)}…` : rendered;
+}
+// The response body's own standard fields (see api/src/i18n/errors.ts'
+// buildError): everything else is a code-specific extra the API attached at
+// the top level rather than under `details` — e.g. `attempts_remaining` on a
+// verify-check 422 (api/src/routes/verify/index.ts). HonkioError.details
+// only ever holds `details`; the raw body (HonkioError.body) is what carries
+// these, so render whatever's left over from it too.
+const KNOWN_ERROR_BODY_FIELDS = new Set(['code', 'message', 'messageEn', 'messageFr', 'statusCode', 'details', 'error']);
+function formatExtraFields(body) {
+    if (!body)
+        return undefined;
+    const lines = Object.entries(body)
+        .filter(([key]) => !KNOWN_ERROR_BODY_FIELDS.has(key))
+        .map(([key, value]) => `${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    if (lines.length === 0)
+        return undefined;
+    const rendered = lines.join('\n');
+    return rendered.length > DETAILS_CHAR_CAP ? `${rendered.slice(0, DETAILS_CHAR_CAP)}…` : rendered;
+}
+export function formatError(err) {
     if (err instanceof HonkioError) {
+        const parts = [`Error [${err.code}]: ${err.message}`];
+        if (err.details !== undefined)
+            parts.push(formatDetails(err.details));
+        const extra = formatExtraFields(err.body);
+        if (extra !== undefined)
+            parts.push(extra);
         return {
-            content: [{ type: 'text', text: `Error [${err.code}]: ${err.message}` }],
+            content: [{ type: 'text', text: parts.join('\n') }],
             isError: true,
         };
     }
@@ -39,40 +114,31 @@ function formatError(err) {
 }
 export function registerTools(server, client) {
     /**
-     * Account-scoped tools take an account_id, but an API key does not carry one
-     * and nothing used to return it, so an agent could not call them without the
-     * user pasting an id from the dashboard. Omitting it now resolves the caller
-     * from the key. Cached because it cannot change for the life of the process —
-     * the key is fixed at startup.
+     * Account-scoped tools take an optional account_id. Omitting it resolves the
+     * caller from the key; the client memoizes that per instance.
      */
-    let cachedAccountId;
-    const resolveAccountId = async (provided) => {
-        if (provided)
-            return provided;
-        if (cachedAccountId)
-            return cachedAccountId;
-        const me = await client.getCurrentAccount();
-        cachedAccountId = me.account.id;
-        return cachedAccountId;
-    };
+    const resolveAccountId = (provided) => provided ? Promise.resolve(provided) : client.currentAccountId();
     const ACCOUNT_ID_ARG = z
         .string()
         .optional()
         .describe('Your account ID. Omit it and it is resolved from your API key.');
     // ── Messages ──────────────────────────────────────────────
-    server.tool('send_sms', 'Send an SMS message from one of your provisioned Canadian numbers. Automatically checks CASL consent (CRTC DNCL checking is coming soon and not yet enforced) unless overridden. Billed per SMS part as the carrier splits the body (get_pricing → message_cost_cents; typographic quotes and dashes count as GSM-7, emoji force Unicode parts); the charge is settled to the carrier\'s part count after the send. A send the carrier rejects outright costs nothing; a message the carrier accepts but cannot deliver keeps its charge, and so does a send to a reserved exchange (555-XXXX, N11 exchanges, carrier test codes) — those are blocked here, never reach the carrier, and come back 201 with status "FAILED" and error_code "RESERVED_DESTINATION", in test mode too. A number the carrier has failed three times running, for any customer, is refused for free as 422 UNDELIVERABLE_NUMBER for 90 days. Use test-mode keys (mk_test_...) to send without real delivery or charges. A test-mode send still returns status "DELIVERED" — check the "mode" field, not the status, to tell a simulation from a real send. ' +
-        'Live sends are subject to sending limits (get_send_limit): a daily cap, a cap on identical messages to distinct recipients, a per-number rate, a per-recipient cap (30 an hour and 100 a day to one number), ' +
-        'and an automatic pause on high opt-out or failure rates — refusals come back as DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_RATE_LIMITED, RECIPIENT_RATE_LIMITED or SENDING_PAUSED with details. ' +
-        'Link shorteners (bit.ly and similar) are refused in both modes (LINK_SHORTENER_BLOCKED); use the full URL. ' +
-        'When you retry a send, pass the same idempotency_key: the API returns the original message instead of sending and charging again. ' +
-        'A 503 CARRIER_UNAVAILABLE means the carrier could not be reached — nothing was sent or charged; retry shortly.', {
-        from: z.string().describe('Sending phone number in E.164 format (e.g. +14165551234). Must be a number provisioned on your account.'),
-        to: z.string().describe('Recipient phone number in E.164 format. Must be a Canadian number.'),
-        body: z.string().max(1600).describe('Message body text. Maximum 1600 characters and 10 SMS parts (about 1,530 GSM-7 or 670 Unicode characters); a longer body is rejected with 422 MESSAGE_TOO_LONG before anything is charged. Billing is per part, counted the way the carrier splits it.'),
-        skip_consent_check: z.boolean().optional().describe('Skip the CASL consent gate. Use only when you have consent recorded outside HonkIO.'),
-        dncl_exemptions: z.array(z.enum(DNCL_EXEMPTIONS)).optional().describe('DNCL exemption reasons. Required if the recipient is on the CRTC Do Not Call List.'),
-        idempotency_key: z.string().min(1).max(255).optional().describe('Sent as the Idempotency-Key header. Reuse the same key on a retry so it can never become a second send or a second charge.'),
-    }, async (input) => {
+    server.registerTool('send_sms', { ...meta('send_sms'), description: 'Send an SMS message from one of your provisioned Canadian numbers. Automatically checks CASL consent (CRTC DNCL checking is coming soon and not yet enforced) unless overridden. Billed per SMS part as the carrier splits the body (get_pricing → message_cost_cents; typographic quotes and dashes count as GSM-7, emoji force Unicode parts); the charge is settled to the carrier\'s part count after the send. A send the carrier rejects outright costs nothing; a message the carrier accepts but cannot deliver keeps its charge. A send to a reserved exchange (555-XXXX, N11 exchanges, carrier test codes) is refused for free as 422 RESERVED_DESTINATION, in test mode too; use a real recipient. A number the carrier has failed three times running, for any customer, is refused for free as 422 UNDELIVERABLE_NUMBER for 90 days. Use test-mode keys (mk_test_...) to simulate a send: it runs the same compliance checks as a live send (consent, opt-out, allow/deny lists, reserved and undeliverable destinations) but does not require owning the from number, and nothing is sent or charged. A test-mode send still returns status "DELIVERED": check the "mode" field, not the status, to tell a simulation from a real send. ' +
+            'Live sends are subject to sending limits (get_send_limit): a daily cap, a cap on identical messages to distinct recipients, a per-number rate, a per-recipient cap (30 an hour and 100 a day to one number), ' +
+            'and an automatic pause on high opt-out or failure rates: refusals come back as DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_RATE_LIMITED, RECIPIENT_RATE_LIMITED or SENDING_PAUSED with details. ' +
+            'Link shorteners (bit.ly and similar) are refused in both modes (LINK_SHORTENER_BLOCKED); use the full URL. ' +
+            'When you retry a send, pass the same idempotency_key: the API returns the original message instead of sending and charging again. ' +
+            'A 503 CARRIER_UNAVAILABLE means the carrier could not be reached: nothing was sent or charged; retry shortly. ' +
+            'A 503 CARRIER_TIMEOUT means the carrier did not answer in time: the message may or may not have been sent and nothing is charged; check list_messages before sending again. A retry with the same idempotency_key returns the failed message instead of sending it again. ' +
+            'A 422 NOT_A_MOBILE_NUMBER means the destination is a landline or VoIP number: the carrier refuses it before sending, nothing is charged, and three such refusals list the number as undeliverable. ' +
+            'A 422 NON_CANADIAN_NUMBER means the recipient is not a Canadian number, and a 422 INVALID_PHONE_NUMBER means the carrier found the number invalid; neither costs anything.', inputSchema: z.object({
+            from: z.string().describe('Sending phone number in E.164 format (e.g. +14165551234). Must be a number provisioned on your account.'),
+            to: z.string().describe('Recipient phone number in E.164 format. Must be a Canadian number.'),
+            body: z.string().max(1600).describe('Message body text. Maximum 1600 characters and 10 SMS parts (about 1,530 GSM-7 or 670 Unicode characters); a longer body is rejected with 422 MESSAGE_TOO_LONG before anything is charged. Billing is per part, counted the way the carrier splits it.'),
+            skip_consent_check: z.boolean().optional().describe('Skip the CASL consent gate. Test-mode keys only: a live key gets 403 FORBIDDEN. Use only when you have consent recorded outside HonkIO.'),
+            dncl_exemptions: z.array(z.enum(DNCL_EXEMPTIONS)).optional().describe('DNCL exemption reasons. Required if the recipient is on the CRTC Do Not Call List.'),
+            idempotency_key: z.string().min(1).max(255).optional().describe('Sent as the Idempotency-Key header. Reuse the same key on a retry so it can never become a second send or a second charge.'),
+        }) }, async (input) => {
         try {
             const result = await client.sendMessage(input);
             return ok(result);
@@ -81,16 +147,16 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('list_messages', 'List SMS messages for your account with optional filters. Returns paginated results. On each message, cost_cents is what it actually cost in CAD cents (settled to the carrier\'s part count; 0 on a TEST simulation or when the carrier refused the send outright — a message the carrier accepted but could not deliver, or one blocked as a reserved destination, keeps its charge; inbound messages carry the inbound charge) and segment_count is the carrier\'s part count. On a FAILED or UNDELIVERED message, error_code and error_message carry the carrier\'s reason (or RESERVED_DESTINATION for a reserved exchange blocked by the platform).', {
-        from: z.string().optional().describe('Filter by sending phone number (E.164).'),
-        to: z.string().optional().describe('Filter by recipient phone number (E.164).'),
-        status: z.enum(['QUEUED', 'SENDING', 'SENT', 'DELIVERED', 'FAILED', 'UNDELIVERED', 'RECEIVED']).optional().describe('Filter by message status.'),
-        direction: z.enum(['OUTBOUND', 'INBOUND']).optional().describe('Filter by message direction.'),
-        page: z.number().int().min(1).optional().describe('Page number (default: 1).'),
-        limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 20, max: 100).'),
-        date_from: z.string().optional().describe('Filter messages from this date (YYYY-MM-DD).'),
-        date_to: z.string().optional().describe('Filter messages to this date (YYYY-MM-DD).'),
-    }, async (input) => {
+    server.registerTool('list_messages', { ...meta('list_messages'), description: 'List SMS messages for your account with optional filters. Returns paginated results. On each message, cost_cents is what it actually cost in CAD cents (settled to the carrier\'s part count; 0 on a TEST simulation or when the carrier refused the send outright: a message the carrier accepted but could not deliver keeps its charge; inbound messages carry the inbound charge) and segment_count is the carrier\'s part count. On a FAILED or UNDELIVERED message, error_code and error_message carry the carrier\'s reason.', inputSchema: z.object({
+            from: z.string().optional().describe('Filter by sending phone number (E.164).'),
+            to: z.string().optional().describe('Filter by recipient phone number (E.164).'),
+            status: z.enum(['QUEUED', 'SENDING', 'SENT', 'DELIVERED', 'FAILED', 'UNDELIVERED', 'RECEIVED']).optional().describe('Filter by message status.'),
+            direction: z.enum(['OUTBOUND', 'INBOUND']).optional().describe('Filter by message direction.'),
+            page: z.number().int().min(1).optional().describe('Page number (default: 1).'),
+            limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 20, max: 100).'),
+            date_from: z.string().optional().describe('Filter messages from this date (YYYY-MM-DD).'),
+            date_to: z.string().optional().describe('Filter messages to this date (YYYY-MM-DD).'),
+        }) }, async (input) => {
         try {
             const result = await client.listMessages(input);
             return ok(result);
@@ -99,9 +165,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('get_message', 'Get full details of a single SMS message by its ID, including delivery events. cost_cents is what it actually cost in CAD cents (settled to the carrier\'s part count; 0 on a TEST simulation or when the carrier refused the send outright; an undelivered or reserved-destination message keeps its charge) and segment_count is the carrier\'s part count. On a FAILED or UNDELIVERED message, error_code and error_message carry the carrier\'s reason.', {
-        id: z.string().describe('Message ID.'),
-    }, async ({ id }) => {
+    server.registerTool('get_message', { ...meta('get_message'), description: 'Get full details of a single SMS message by its ID. cost_cents is what it actually cost in CAD cents (settled to the carrier\'s part count; 0 on a TEST simulation or when the carrier refused the send outright; an undelivered message keeps its charge) and segment_count is the carrier\'s part count. On a FAILED or UNDELIVERED message, error_code and error_message carry the carrier\'s reason.', inputSchema: z.object({
+            id: z.string().describe('Message ID.'),
+        }) }, async ({ id }) => {
         try {
             const result = await client.getMessage(id);
             return ok(result);
@@ -111,30 +177,45 @@ export function registerTools(server, client) {
         }
     });
     // ── Phone Numbers ─────────────────────────────────────────
-    server.tool('search_phone_numbers', 'Search available Canadian phone numbers you can provision. Filter by area code to find numbers in a specific province.', {
-        area_code: z.string().regex(/^\d{3}$/).optional().describe('Canadian area code to filter by (e.g. "416" for Toronto, "514" for Montreal, "604" for Vancouver).'),
-        limit: z.number().int().min(1).max(50).optional().describe('Number of results to return (default: 10, max: 50).'),
-    }, async (input) => {
+    const AREA_CODE = z.string().regex(/^\d{3}$/);
+    server.registerTool('list_area_codes', { ...meta('list_area_codes'), description: 'List the provinces HonkIO has numbers in and the active Canadian area codes within each. Use this to see what is available before calling search_phone_numbers with an area_code.', inputSchema: z.object({}) }, async () => {
+        try {
+            const result = await client.listAreaCodes();
+            return ok(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.registerTool('search_phone_numbers', { ...meta('search_phone_numbers'), description: 'Search available Canadian phone numbers you can provision. Filter by one area code (area_code) or up to five (area_codes) to find numbers in specific provinces; omit both to search everywhere. See list_area_codes for what is active.', inputSchema: z.object({
+            area_code: AREA_CODE.optional().describe('A single Canadian area code to filter by (e.g. "416" for Toronto, "514" for Montreal, "604" for Vancouver). Combined with area_codes if both are given.'),
+            area_codes: z.array(AREA_CODE).max(5).optional().describe('Up to 5 Canadian area codes to filter by.'),
+            limit: z.number().int().min(1).max(50).optional().describe('Number of results to return (default: 10, max: 50).'),
+        }) }, async ({ area_code, area_codes, limit }) => {
         try {
-            const result = await client.searchPhoneNumbers(input);
+            const codes = [...(area_code ? [area_code] : []), ...(area_codes ?? [])];
+            const result = await client.searchPhoneNumbers({
+                area_codes: codes.length ? codes.join(',') : undefined,
+                limit,
+            });
             return ok(result);
         }
         catch (err) {
             return formatError(err);
         }
     });
-    server.tool('provision_phone_number', 'Provision (purchase) a Canadian phone number to your account. Get the phone_number value from search_phone_numbers first. ' +
-        'On a live key this spends real money: the first month\'s rent plus a one-time activation fee are debited together the ' +
-        'moment the number is bought (search results and get_pricing show both amounts), and rent recurs monthly until ' +
-        'release_phone_number. A balance that cannot cover the total returns 402 INSUFFICIENT_BALANCE with nothing charged. ' +
-        'Accounts are capped on how many numbers they may hold at once — a per-account limit that falls back to a platform-wide ' +
-        'default staff can change at runtime — exceeding it returns NUMBER_LIMIT_REACHED, and a higher allowance is requested from ' +
-        'the HonkIO dashboard, not through this API. May also return a 409 PURCHASE_IN_PROGRESS if another purchase for this ' +
-        'account is already running; this is transient and safe to retry after a short delay — unlike the terminal 409 returned ' +
-        'when the number is already owned, it does not mean the purchase failed. Firing several provision_phone_number calls in ' +
-        'parallel will produce these; retry rather than dropping them.', {
-        phone_number: z.string().describe('E.164 phone number to provision (e.g. +14165551234). Must be from the search_phone_numbers results.'),
-    }, async ({ phone_number }) => {
+    server.registerTool('provision_phone_number', { ...meta('provision_phone_number'), description: 'Provision (purchase) a Canadian phone number to your account. Get the phone_number value from search_phone_numbers first. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. ' +
+            'This spends real money: the first month\'s rent plus a one-time activation fee are debited together the ' +
+            'moment the number is bought (search results and get_pricing show both amounts), and rent recurs monthly until ' +
+            'release_phone_number. A balance that cannot cover the total returns 402 INSUFFICIENT_BALANCE with nothing charged. ' +
+            'Accounts are capped on how many numbers they may hold at once: a per-account limit that falls back to a platform-wide ' +
+            'default staff can change at runtime. Exceeding it returns NUMBER_LIMIT_REACHED, and a higher allowance is requested with ' +
+            'request_number_allowance. May also return a 409 PURCHASE_IN_PROGRESS if another purchase for this ' +
+            'account is already running; this is transient and safe to retry after a short delay, unlike the terminal 409 returned ' +
+            'when the number is already owned, it does not mean the purchase failed. Firing several provision_phone_number calls in ' +
+            'parallel will produce these; retry rather than dropping them.', inputSchema: z.object({
+            phone_number: z.string().describe('E.164 phone number to provision (e.g. +14165551234). Must be from the search_phone_numbers results.'),
+        }) }, async ({ phone_number }) => {
         try {
             const result = await client.provisionPhoneNumber(phone_number);
             return ok(result);
@@ -143,7 +224,7 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('list_phone_numbers', "List all phone numbers provisioned on your account.", {}, async () => {
+    server.registerTool('list_phone_numbers', { ...meta('list_phone_numbers'), description: "List all phone numbers provisioned on your account.", inputSchema: z.object({}) }, async () => {
         try {
             const result = await client.listPhoneNumbers();
             return ok(result);
@@ -152,9 +233,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('get_phone_number', 'Get details for a specific provisioned phone number.', {
-        id: z.string().describe('Phone number record ID.'),
-    }, async ({ id }) => {
+    server.registerTool('get_phone_number', { ...meta('get_phone_number'), description: 'Get details for a specific provisioned phone number.', inputSchema: z.object({
+            id: z.string().describe('Phone number record ID.'),
+        }) }, async ({ id }) => {
         try {
             const result = await client.getPhoneNumber(id);
             return ok(result);
@@ -163,9 +244,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('release_phone_number', 'Release (cancel) a provisioned phone number. This will stop monthly billing for the number; the one-time activation fee and the current month are not refunded. This action cannot be undone.', {
-        id: z.string().describe('Phone number record ID to release.'),
-    }, async ({ id }) => {
+    server.registerTool('release_phone_number', { ...meta('release_phone_number'), description: 'Release (cancel) a provisioned phone number. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. This will stop monthly billing for the number; the one-time activation fee and the current month are not refunded. This action cannot be undone.', inputSchema: z.object({
+            id: z.string().describe('Phone number record ID to release.'),
+        }) }, async ({ id }) => {
         try {
             await client.releasePhoneNumber(id);
             return ok({ status: 'released', id });
@@ -174,17 +255,38 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
+    server.registerTool('request_number_allowance', { ...meta('request_number_allowance'), description: 'File a request to raise how many phone numbers this account may hold at once, for HonkIO staff to review. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. Only one request may be pending at a time (a second returns 409 ALLOWANCE_REQUEST_PENDING); the owner is emailed when it is decided.', inputSchema: z.object({
+            requested_limit: z.number().int().min(2).max(100).describe('Total numbers you want to be able to hold, not an increment. Must exceed the current limit (see get_account → phone_number_limit).'),
+            reason: z.string().min(10).max(1000).describe('What the numbers are for. Staff decide on this.'),
+        }) }, async (input) => {
+        try {
+            const result = await client.requestNumberAllowance(input);
+            return ok(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.registerTool('list_number_allowance_requests', { ...meta('list_number_allowance_requests'), description: 'List past and pending phone-number allowance requests for this account.', inputSchema: z.object({}) }, async () => {
+        try {
+            const result = await client.listNumberAllowanceRequests();
+            return ok(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
     // ── Compliance: CASL Consents ─────────────────────────────
-    server.tool('record_consent', 'Record CASL consent for a phone number before sending commercial messages. Express consent requires source_description. Implied consent requires relationship_type and is valid for 2 years from last_transaction_date.', {
-        phone_number: z.string().describe('E.164 phone number of the subscriber granting consent.'),
-        consent_type: z.enum(['express', 'implied']).describe('Type of CASL consent. "express" = subscriber explicitly opted in. "implied" = business relationship exists.'),
-        source_description: z.string().optional().describe('[Required for express] How/where the subscriber gave consent (e.g. "Website signup form at honkio.ca/signup on 2024-01-15").'),
-        source_ip: z.string().optional().describe('[Optional, express] IP address of the subscriber at time of consent.'),
-        source_url: z.string().optional().describe('[Optional, express] URL where consent was captured.'),
-        relationship_type: z.string().optional().describe('[Required for implied] Business relationship type (e.g. "purchase", "inquiry", "membership").'),
-        last_transaction_date: z.string().optional().describe('[Optional, implied] Date of last transaction (YYYY-MM-DD). Implied consent expires 2 years after this date.'),
-        expires_at: z.string().optional().describe('[Optional, implied] Explicit expiry (ISO 8601 date or date-time). Overrides the expiry derived from last_transaction_date. Rejected for express consent, which never expires.'),
-    }, async (input) => {
+    server.registerTool('record_consent', { ...meta('record_consent'), description: 'Record CASL consent for a phone number before sending commercial messages. Express consent requires source_description. Implied consent requires relationship_type and is valid for 2 years from last_transaction_date.', inputSchema: z.object({
+            phone_number: z.string().describe('E.164 phone number of the subscriber granting consent.'),
+            consent_type: z.enum(['express', 'implied']).describe('Type of CASL consent. "express" = subscriber explicitly opted in. "implied" = business relationship exists.'),
+            source_description: z.string().optional().describe('[Required for express] How/where the subscriber gave consent (e.g. "Website signup form at honkio.ca/signup on 2024-01-15").'),
+            source_ip: z.string().optional().describe('[Optional, express] IP address of the subscriber at time of consent.'),
+            source_url: z.string().optional().describe('[Optional, express] URL where consent was captured.'),
+            relationship_type: z.string().optional().describe('[Required for implied] Business relationship type (e.g. "purchase", "inquiry", "membership").'),
+            last_transaction_date: z.string().optional().describe('[Optional, implied] Date of last transaction (YYYY-MM-DD). Implied consent expires 2 years after this date.'),
+            expires_at: z.string().optional().describe('[Optional, implied] Explicit expiry (ISO 8601 date or date-time). Overrides the expiry derived from last_transaction_date. Rejected for express consent, which never expires.'),
+        }) }, async (input) => {
         try {
             const result = await client.recordConsent(input);
             return ok(result);
@@ -193,12 +295,12 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('list_consents', 'List CASL consent records for your account, optionally filtered by phone number or status.', {
-        phone_number: z.string().optional().describe('Filter consents for a specific phone number (E.164).'),
-        status: z.enum(['ACTIVE', 'EXPIRED', 'REVOKED']).optional().describe('Filter by consent status.'),
-        page: z.number().int().min(1).optional().describe('Page number (default: 1).'),
-        limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 20).'),
-    }, async (input) => {
+    server.registerTool('list_consents', { ...meta('list_consents'), description: 'List CASL consent records for your account, optionally filtered by phone number or status.', inputSchema: z.object({
+            phone_number: z.string().optional().describe('Filter consents for a specific phone number (E.164).'),
+            status: z.enum(['ACTIVE', 'EXPIRED', 'REVOKED']).optional().describe('Filter by consent status.'),
+            page: z.number().int().min(1).optional().describe('Page number (default: 1).'),
+            limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 20).'),
+        }) }, async (input) => {
         try {
             const result = await client.listConsents(input);
             return ok(result);
@@ -207,9 +309,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('check_consent', 'Check whether a phone number has valid CASL consent before sending a message.', {
-        phone_number: z.string().describe('E.164 phone number to check consent for.'),
-    }, async ({ phone_number }) => {
+    server.registerTool('check_consent', { ...meta('check_consent'), description: 'Check whether a phone number has valid CASL consent before sending a message.', inputSchema: z.object({
+            phone_number: z.string().describe('E.164 phone number to check consent for.'),
+        }) }, async ({ phone_number }) => {
         try {
             const result = await client.checkConsent(phone_number);
             return ok(result);
@@ -218,9 +320,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('revoke_consent', 'Revoke CASL consent for a phone number. Future messages to this number will be blocked unless new consent is recorded.', {
-        phone_number: z.string().describe('E.164 phone number to revoke consent for.'),
-    }, async ({ phone_number }) => {
+    server.registerTool('revoke_consent', { ...meta('revoke_consent'), description: 'Revoke CASL consent for a phone number. Future messages to this number will be blocked unless new consent is recorded.', inputSchema: z.object({
+            phone_number: z.string().describe('E.164 phone number to revoke consent for.'),
+        }) }, async ({ phone_number }) => {
         try {
             await client.revokeConsent(phone_number);
             return ok({ status: 'revoked', phone_number });
@@ -230,10 +332,10 @@ export function registerTools(server, client) {
         }
     });
     // ── Compliance: Opt-Outs ──────────────────────────────────
-    server.tool('record_opt_out', 'Manually record an opt-out for a subscriber. Use this when a subscriber contacts you directly to opt out rather than replying STOP to a message.', {
-        phone_number: z.string().describe('E.164 phone number of the subscriber opting out.'),
-        from_number: z.string().describe('E.164 number the subscriber is opting out from (your sending number).'),
-    }, async (input) => {
+    server.registerTool('record_opt_out', { ...meta('record_opt_out'), description: 'Manually record an opt-out for a subscriber. Use this when a subscriber contacts you directly to opt out rather than replying STOP to a message. A live key must own from_number: opting a subscriber out of a number you don\'t hold is refused with 403 PHONE_NUMBER_NOT_OWNED. A test key skips that check.', inputSchema: z.object({
+            phone_number: z.string().describe('E.164 phone number of the subscriber opting out.'),
+            from_number: z.string().describe('E.164 number the subscriber is opting out from (your sending number).'),
+        }) }, async (input) => {
         try {
             const result = await client.recordOptOut(input);
             return ok(result);
@@ -242,12 +344,12 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('list_opt_outs', 'List opt-out records for your account.', {
-        phone_number: z.string().optional().describe('Filter opt-outs for a specific subscriber number (E.164).'),
-        from_number: z.string().optional().describe('Filter opt-outs from a specific sending number (E.164).'),
-        page: z.number().int().min(1).optional().describe('Page number (default: 1).'),
-        limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 20).'),
-    }, async (input) => {
+    server.registerTool('list_opt_outs', { ...meta('list_opt_outs'), description: 'List opt-out records for your account.', inputSchema: z.object({
+            phone_number: z.string().optional().describe('Filter opt-outs for a specific subscriber number (E.164).'),
+            from_number: z.string().optional().describe('Filter opt-outs from a specific sending number (E.164).'),
+            page: z.number().int().min(1).optional().describe('Page number (default: 1).'),
+            limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 20).'),
+        }) }, async (input) => {
         try {
             const result = await client.listOptOuts(input);
             return ok(result);
@@ -257,9 +359,9 @@ export function registerTools(server, client) {
         }
     });
     // ── Compliance: DNCL ─────────────────────────────────────
-    server.tool('check_dncl', "Coming soon: check if a Canadian phone number is on the CRTC Do Not Call List. CRTC DNCL checking is not available yet — this endpoint currently returns 501 (DNCL_COMING_SOON).", {
-        phone_number: z.string().describe('Canadian phone number to check in E.164 format.'),
-    }, async ({ phone_number }) => {
+    server.registerTool('check_dncl', { ...meta('check_dncl'), description: "Coming soon: check if a Canadian phone number is on the CRTC Do Not Call List. CRTC DNCL checking is not available yet: this endpoint currently returns 501 (DNCL_COMING_SOON).", inputSchema: z.object({
+            phone_number: z.string().describe('Canadian phone number to check in E.164 format.'),
+        }) }, async ({ phone_number }) => {
         try {
             const result = await client.checkDncl(phone_number);
             return ok(result);
@@ -268,9 +370,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('batch_check_dncl', 'Coming soon: check up to 100 Canadian phone numbers against the CRTC Do Not Call List in a single request. CRTC DNCL checking is not available yet — this endpoint currently returns 501 (DNCL_COMING_SOON).', {
-        phone_numbers: z.array(z.string()).min(1).max(100).describe('Array of Canadian phone numbers in E.164 format.'),
-    }, async ({ phone_numbers }) => {
+    server.registerTool('batch_check_dncl', { ...meta('batch_check_dncl'), description: 'Coming soon: check up to 100 Canadian phone numbers against the CRTC Do Not Call List in a single request. CRTC DNCL checking is not available yet: this endpoint currently returns 501 (DNCL_COMING_SOON).', inputSchema: z.object({
+            phone_numbers: z.array(z.string()).min(1).max(100).describe('Array of Canadian phone numbers in E.164 format.'),
+        }) }, async ({ phone_numbers }) => {
         try {
             const result = await client.batchCheckDncl(phone_numbers);
             return ok(result);
@@ -280,10 +382,10 @@ export function registerTools(server, client) {
         }
     });
     // ── Compliance: Erasure ───────────────────────────────────
-    server.tool('request_erasure', 'Execute a PIPEDA/Quebec Law 25 right-to-erasure request for a phone number. Purges message bodies, consent records, and opt-out records for the specified number. Creates an immutable audit log entry.', {
-        phone_number: z.string().describe('E.164 phone number to erase data for.'),
-        reason: z.string().optional().describe('Reason for the erasure request (recorded in the audit log).'),
-    }, async (input) => {
+    server.registerTool('request_erasure', { ...meta('request_erasure'), description: 'Execute a PIPEDA/Quebec Law 25 right-to-erasure request for a phone number. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. Erases message bodies (keeping message metadata), consent records, verifications, contacts, non-DENY contact-list entries, and webhook dead letters referencing the number. Opt-out records are NOT erased (CASL requires keeping them as compliance evidence), and any DENY-list block on the number is kept so the number stays blocked; the response reports opt_outs_preserved: true. Creates an immutable audit log entry.', inputSchema: z.object({
+            phone_number: z.string().describe('E.164 phone number to erase data for.'),
+            reason: z.string().optional().describe('Reason for the erasure request (recorded in the audit log).'),
+        }) }, async (input) => {
         try {
             const result = await client.requestErasure(input);
             return ok(result);
@@ -293,10 +395,10 @@ export function registerTools(server, client) {
         }
     });
     // ── Webhooks ──────────────────────────────────────────────
-    server.tool('create_webhook', 'Register a webhook endpoint to receive HonkIO event notifications. The signing_secret in the response is shown once — store it to verify X-HonkIO-Signature on incoming requests.', {
-        url: z.string().url().describe('HTTPS URL to deliver events to.'),
-        events: z.array(z.enum(WEBHOOK_EVENTS)).min(1).describe('Event types to subscribe to.'),
-    }, async (input) => {
+    server.registerTool('create_webhook', { ...meta('create_webhook'), description: 'Register a webhook endpoint to receive HonkIO event notifications. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. The signing_secret in the response is shown once; store it to verify X-HonkIO-Signature on incoming requests.', inputSchema: z.object({
+            url: z.string().url().describe('HTTPS URL to deliver events to.'),
+            events: z.array(z.enum(WEBHOOK_EVENTS)).min(1).describe('Event types to subscribe to.'),
+        }) }, async (input) => {
         try {
             const result = await client.createWebhook(input);
             return ok(result);
@@ -305,7 +407,7 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('list_webhooks', 'List all registered webhook endpoints for your account.', {}, async () => {
+    server.registerTool('list_webhooks', { ...meta('list_webhooks'), description: 'List all registered webhook endpoints for your account.', inputSchema: z.object({}) }, async () => {
         try {
             const result = await client.listWebhooks();
             return ok(result);
@@ -314,12 +416,23 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('update_webhook', 'Update a webhook endpoint URL, event subscriptions, or active status.', {
-        id: z.string().describe('Webhook ID to update.'),
-        url: z.string().url().optional().describe('New HTTPS URL.'),
-        events: z.array(z.enum(WEBHOOK_EVENTS)).optional().describe('New event subscriptions (replaces existing).'),
-        active: z.boolean().optional().describe('Enable or disable the webhook.'),
-    }, async ({ id, ...updates }) => {
+    server.registerTool('get_webhook', { ...meta('get_webhook'), description: 'Get details for a single registered webhook endpoint by ID.', inputSchema: z.object({
+            id: z.string().describe('Webhook ID.'),
+        }) }, async ({ id }) => {
+        try {
+            const result = await client.getWebhook(id);
+            return ok(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.registerTool('update_webhook', { ...meta('update_webhook'), description: 'Update a webhook endpoint URL, event subscriptions, or active status. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED.', inputSchema: z.object({
+            id: z.string().describe('Webhook ID to update.'),
+            url: z.string().url().optional().describe('New HTTPS URL.'),
+            events: z.array(z.enum(WEBHOOK_EVENTS)).min(1).optional().describe('New event subscriptions (replaces existing). Cannot be an empty array: that would silently mute the webhook, so it is refused with 422.'),
+            active: z.boolean().optional().describe('Enable or disable the webhook.'),
+        }) }, async ({ id, ...updates }) => {
         try {
             const result = await client.updateWebhook(id, updates);
             return ok(result);
@@ -328,9 +441,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('delete_webhook', 'Delete a registered webhook endpoint.', {
-        id: z.string().describe('Webhook ID to delete.'),
-    }, async ({ id }) => {
+    server.registerTool('delete_webhook', { ...meta('delete_webhook'), description: 'Delete a registered webhook endpoint. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED.', inputSchema: z.object({
+            id: z.string().describe('Webhook ID to delete.'),
+        }) }, async ({ id }) => {
         try {
             await client.deleteWebhook(id);
             return ok({ status: 'deleted', id });
@@ -339,10 +452,10 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('list_webhook_deliveries', 'List recent delivery attempts for a webhook (success/failure, HTTP status, duration, timestamp). Use this to debug why customer events are not arriving or why a webhook was auto-disabled.', {
-        webhook_id: z.string().describe('Webhook ID.'),
-        limit: z.number().int().min(1).max(200).optional().describe('Max attempts to return (default 50).'),
-    }, async ({ webhook_id, limit }) => {
+    server.registerTool('list_webhook_deliveries', { ...meta('list_webhook_deliveries'), description: 'List recent delivery attempts for a webhook (success/failure, HTTP status, duration, timestamp). Use this to debug why customer events are not arriving or why a webhook was auto-disabled.', inputSchema: z.object({
+            webhook_id: z.string().describe('Webhook ID.'),
+            limit: z.number().int().min(1).max(200).optional().describe('Max attempts to return (default 50).'),
+        }) }, async ({ webhook_id, limit }) => {
         try {
             const result = await client.listWebhookDeliveries(webhook_id, limit ? { limit } : undefined);
             return ok(result);
@@ -351,9 +464,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('reactivate_webhook', 'Re-enable a webhook that was auto-disabled by repeated delivery failures. The destination URL is re-validated (SSRF check) before reactivation.', {
-        webhook_id: z.string().describe('Webhook ID to reactivate.'),
-    }, async ({ webhook_id }) => {
+    server.registerTool('reactivate_webhook', { ...meta('reactivate_webhook'), description: 'Re-enable a webhook that was auto-disabled by repeated delivery failures. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. The destination URL is re-validated (SSRF check) before reactivation.', inputSchema: z.object({
+            webhook_id: z.string().describe('Webhook ID to reactivate.'),
+        }) }, async ({ webhook_id }) => {
         try {
             const result = await client.reactivateWebhook(webhook_id);
             return ok(result);
@@ -362,11 +475,11 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('list_webhook_dead_letters', 'List events that exhausted all retry attempts (dead-letter queue). These are events that failed delivery and were never received by your endpoint. Use replay_webhook_dead_letter to retry after fixing the issue.', {
-        webhook_id: z.string().describe('Webhook ID.'),
-        limit: z.number().int().min(1).max(200).optional().describe('Max rows (default 50).'),
-        include_replayed: z.boolean().optional().describe('Include events that have been successfully replayed (default false).'),
-    }, async ({ webhook_id, ...query }) => {
+    server.registerTool('list_webhook_dead_letters', { ...meta('list_webhook_dead_letters'), description: 'List events that exhausted all retry attempts (dead-letter queue). Live keys only: a test key gets 403 LIVE_KEY_REQUIRED, since a dead letter carries the failed payload. These are events that failed delivery and were never received by your endpoint. Use replay_webhook_dead_letter to retry after fixing the issue.', inputSchema: z.object({
+            webhook_id: z.string().describe('Webhook ID.'),
+            limit: z.number().int().min(1).max(200).optional().describe('Max rows (default 50).'),
+            include_replayed: z.boolean().optional().describe('Include events that have been successfully replayed (default false).'),
+        }) }, async ({ webhook_id, ...query }) => {
         try {
             const result = await client.listWebhookDeadLetters(webhook_id, query);
             return ok(result);
@@ -375,9 +488,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('replay_webhook_dead_letter', 'Resend a dead-lettered event against the original webhook URL. The event is re-signed with the current timestamp; on success the dead-letter row is marked as replayed.', {
-        dead_letter_id: z.string().describe('Dead-letter row ID (from list_webhook_dead_letters).'),
-    }, async ({ dead_letter_id }) => {
+    server.registerTool('replay_webhook_dead_letter', { ...meta('replay_webhook_dead_letter'), description: 'Resend a dead-lettered event against the original webhook URL. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. The event is re-signed with the current timestamp; on success the dead-letter row is marked as replayed.', inputSchema: z.object({
+            dead_letter_id: z.string().describe('Dead-letter row ID (from list_webhook_dead_letters).'),
+        }) }, async ({ dead_letter_id }) => {
         try {
             const result = await client.replayWebhookDeadLetter(dead_letter_id);
             return ok(result);
@@ -386,9 +499,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('discard_webhook_dead_letter', 'Permanently discard a dead-lettered event without replaying it. Use when the event is no longer relevant (e.g. the underlying message has expired).', {
-        dead_letter_id: z.string().describe('Dead-letter row ID.'),
-    }, async ({ dead_letter_id }) => {
+    server.registerTool('discard_webhook_dead_letter', { ...meta('discard_webhook_dead_letter'), description: 'Permanently discard a dead-lettered event without replaying it. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. Use when the event is no longer relevant (e.g. the underlying message has expired).', inputSchema: z.object({
+            dead_letter_id: z.string().describe('Dead-letter row ID.'),
+        }) }, async ({ dead_letter_id }) => {
         try {
             await client.discardWebhookDeadLetter(dead_letter_id);
             return ok({ status: 'discarded', dead_letter_id });
@@ -398,7 +511,7 @@ export function registerTools(server, client) {
         }
     });
     // ── Pricing ───────────────────────────────────────────────
-    server.tool('get_pricing', 'Current HonkIO prices in CAD cents: per-SMS-segment cost for outbound messages, the per-segment cost charged for inbound SMS received on a provisioned number (STOP/START/HELP keywords are free), the verification upcharge, what a typical single-segment verification costs, phone-number upfront (first month) and monthly rent, and the one-time activation fee charged with the first month on every number. Call this before quoting a cost to a user or deciding whether an operation is worth its price — these are set at runtime and change without a release, so never assume a figure.', {}, async () => {
+    server.registerTool('get_pricing', { ...meta('get_pricing'), description: 'Current HonkIO prices in CAD cents: per-SMS-segment cost for outbound messages, the per-segment cost charged for inbound SMS received on a provisioned number (STOP/START/HELP keywords are free), the verification upcharge, what a typical single-segment verification costs, phone-number upfront (first month) and monthly rent, and the one-time activation fee charged with the first month on every number. Call this before quoting a cost to a user or deciding whether an operation is worth its price: these are set at runtime and change without a release, so never assume a figure.', inputSchema: z.object({}) }, async () => {
         try {
             const result = await client.getPricing();
             return ok(result);
@@ -408,13 +521,13 @@ export function registerTools(server, client) {
         }
     });
     // ── Verify (OTP) ──────────────────────────────────────────
-    server.tool('start_verification', 'Send a phone-number verification code (OTP) via SMS. The recipient receives a 4/6/8-digit numeric code. With a live key (mk_live_...) this sends a real SMS and charges the per-part message cost (one part unless app_name is long or non-GSM; settled to the carrier\'s part count) plus the verification upcharge — call get_pricing for the current amount; a rejected OTP is refunded in full. With a test-mode key (mk_test_...) nothing is sent and nothing is charged: the code is always zeros for the chosen length (000000 for 6 digits), and the returned verification has mode "TEST". Check the "mode" field to confirm which happened.', {
-        from: z.string().describe('Your HonkIO number (E.164, must be active on your account).'),
-        to: z.string().describe('The phone number to verify (E.164, Canadian numbers only).'),
-        code_length: z.union([z.literal(4), z.literal(6), z.literal(8)]).optional().describe('OTP digit length (default 6).'),
-        ttl_minutes: z.number().int().min(1).max(60).optional().describe('Minutes until the code expires (default 10).'),
-        app_name: z.string().max(64).optional().describe('Brand name shown in the SMS body (default HonkIO).'),
-    }, async (input) => {
+    server.registerTool('start_verification', { ...meta('start_verification'), description: 'Send a phone-number verification code (OTP) via SMS. The recipient receives a 4/6/8-digit numeric code. With a live key (mk_live_...) this sends a real SMS and charges the per-part message cost (one part unless app_name is long or non-GSM; settled to the carrier\'s part count) plus the verification upcharge: call get_pricing for the current amount; a rejected OTP is refunded in full. With a test-mode key (mk_test_...) nothing is sent and nothing is charged: the code is always zeros for the chosen length (000000 for 6 digits), and the returned verification has mode "TEST". Check the "mode" field to confirm which happened.', inputSchema: z.object({
+            from: z.string().describe('Your HonkIO number (E.164, must be active on your account).'),
+            to: z.string().describe('The phone number to verify (E.164, Canadian numbers only).'),
+            code_length: z.union([z.literal(4), z.literal(6), z.literal(8)]).optional().describe('OTP digit length (default 6).'),
+            ttl_minutes: z.number().int().min(1).max(60).optional().describe('Minutes until the code expires (default 10).'),
+            app_name: z.string().max(64).optional().describe('Brand name shown in the SMS body (default HonkIO).'),
+        }) }, async (input) => {
         try {
             const result = await client.startVerification(input);
             return ok(result);
@@ -423,10 +536,10 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('check_verification', 'Submit the OTP a user entered to complete verification. Returns the verification status (verified, invalid_code, expired, max_attempts).', {
-        verification_id: z.string().describe('Verification ID returned from start_verification.'),
-        code: z.string().regex(/^\d{4,8}$/).describe('The 4/6/8-digit code the user submitted.'),
-    }, async ({ verification_id, code }) => {
+    server.registerTool('check_verification', { ...meta('check_verification'), description: 'Submit the OTP a user entered to complete verification. On success, returns the verification with status "verified" and attempts_remaining: 0. A wrong code comes back as a 422 VERIFICATION_INVALID_CODE error carrying attempts_remaining (5 attempts total); an expired verification is a 410 VERIFICATION_EXPIRED error; five failed attempts is a 429 VERIFICATION_MAX_ATTEMPTS error; checking one already completed is a 409 VERIFICATION_ALREADY_VERIFIED error. These come back as tool errors to catch, not a status value to branch on.', inputSchema: z.object({
+            verification_id: z.string().describe('Verification ID returned from start_verification.'),
+            code: z.string().regex(/^\d{4,8}$/).describe('The 4/6/8-digit code the user submitted.'),
+        }) }, async ({ verification_id, code }) => {
         try {
             const result = await client.checkVerification(verification_id, code);
             return ok(result);
@@ -435,9 +548,9 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('get_verification', 'Look up the current state of a verification (status, attempts, expiry, and whether it was real). The "mode" field is "LIVE" for a real billed SMS or "TEST" for a simulation; cost_cents is 0 on a TEST verification.', {
-        verification_id: z.string().describe('Verification ID.'),
-    }, async ({ verification_id }) => {
+    server.registerTool('get_verification', { ...meta('get_verification'), description: 'Look up the current state of a verification (status, attempts, expiry, and whether it was real). The "mode" field is "LIVE" for a real billed SMS or "TEST" for a simulation; cost_cents is 0 on a TEST verification.', inputSchema: z.object({
+            verification_id: z.string().describe('Verification ID.'),
+        }) }, async ({ verification_id }) => {
         try {
             const result = await client.getVerification(verification_id);
             return ok(result);
@@ -446,12 +559,11 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('list_verifications', 'List recent verifications for your account, optionally filtered by phone number or status.', {
-        phone_number: z.string().optional().describe('Filter to verifications for this E.164 number.'),
-        status: z.enum(['pending', 'verified', 'expired', 'max_attempts']).optional().describe('Filter by status.'),
-        page: z.number().int().min(1).optional(),
-        limit: z.number().int().min(1).max(200).optional(),
-    }, async (input) => {
+    server.registerTool('list_verifications', { ...meta('list_verifications'), description: 'List verifications for your account, newest first, optionally filtered by status.', inputSchema: z.object({
+            status: z.enum(['pending', 'verified', 'expired', 'max_attempts']).optional().describe('Filter by status.'),
+            limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 50, max: 100).'),
+            offset: z.number().int().min(0).optional().describe('Number of records to skip (default: 0).'),
+        }) }, async (input) => {
         try {
             const result = await client.listVerifications(input);
             return ok(result);
@@ -462,11 +574,11 @@ export function registerTools(server, client) {
     });
     // ── Account ───────────────────────────────────────────────
     // ─── Sending limits ──────────────────────────────────────────
-    server.tool('get_send_limit', 'Your account\'s sending limits and current usage: the daily cap (a rolling 24 hours, 250/day for new accounts until a volume request is approved), ' +
-        'how many live messages were sent in the last 24 hours and how many remain, the probation status that gates "request a higher volume" ' +
-        '(it opens 30 days after the first live send), the per-recipient cap (recipient_rate_per_hour / recipient_rate_per_day — a breach comes back as RECIPIENT_RATE_LIMITED with Retry-After), ' +
-        'whether live sending is currently paused and until when, and past volume requests. ' +
-        'Check this when a send is refused with DAILY_LIMIT_REACHED, RECIPIENT_RATE_LIMITED or SENDING_PAUSED, or before a batch of sends.', {}, async () => {
+    server.registerTool('get_send_limit', { ...meta('get_send_limit'), description: 'Your account\'s sending limits and current usage: the daily cap (a rolling 24 hours, 250/day for new accounts until a volume request is approved), ' +
+            'how many live messages were sent in the last 24 hours and how many remain, the probation status that gates "request a higher volume" ' +
+            '(it opens 30 days after the first live send), the per-recipient cap (recipient_rate_per_hour / recipient_rate_per_day: a breach comes back as RECIPIENT_RATE_LIMITED with Retry-After), ' +
+            'whether live sending is currently paused and until when, and past volume requests. ' +
+            'Check this when a send is refused with DAILY_LIMIT_REACHED, RECIPIENT_RATE_LIMITED or SENDING_PAUSED, or before a batch of sends.', inputSchema: z.object({}) }, async () => {
         try {
             const result = await client.getSendLimit();
             return ok(result);
@@ -475,13 +587,13 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('request_send_limit', 'File a "request a higher volume" for HonkIO staff to review. Only available once the account has completed its probation period ' +
-        '(get_send_limit → probation.eligible_to_request); one request may be pending at a time. Omit requested_limit to ask for the standard ' +
-        'approved volume (get_send_limit → approved_daily_limit), or name a target above the current cap. The owner is emailed when it is decided. ' +
-        'HonkIO is for transactional and relationship messaging: describe what is sent, to whom, and roughly how many a day — bulk marketing is not approved.', {
-        requested_limit: z.number().int().min(1).optional().describe('Messages per day wanted (a total, not an increment). Must exceed the current daily limit. Omit for the standard approved volume.'),
-        reason: z.string().min(10).max(1000).describe('What is sent and to whom, and the expected daily volume. Staff decide on this.'),
-    }, async (input) => {
+    server.registerTool('request_send_limit', { ...meta('request_send_limit'), description: 'File a "request a higher volume" for HonkIO staff to review. Live keys only: a test key gets 403 LIVE_KEY_REQUIRED. Only available once the account has completed its probation period ' +
+            '(get_send_limit → probation.eligible_to_request); one request may be pending at a time (a second returns 409 SEND_LIMIT_REQUEST_PENDING). Omit requested_limit to ask for the standard ' +
+            'approved volume (get_send_limit → approved_daily_limit), or name a target above the current cap. The owner is emailed when it is decided. ' +
+            'HonkIO is for transactional and relationship messaging: describe what is sent, to whom, and roughly how many a day; bulk marketing is not approved.', inputSchema: z.object({
+            requested_limit: z.number().int().min(1).optional().describe('Messages per day wanted (a total, not an increment). Must exceed the current daily limit. Omit for the standard approved volume.'),
+            reason: z.string().min(10).max(1000).describe('What is sent and to whom, and the expected daily volume. Staff decide on this.'),
+        }) }, async (input) => {
         try {
             const result = await client.requestSendLimit(input);
             return ok(result);
@@ -490,11 +602,20 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('get_topup_allowance', 'How much credit can be added to the account right now. Top-ups are capped by a maximum balance and a rolling 30-day total ' +
-        '(platform defaults $500 and $1,000 CAD, raisable per account); a checkout above max_topup_now_cents is refused with TOPUP_LIMIT_REACHED. ' +
-        'Returns the caps, the current balance, the 30-day total so far, and the amount that fits now, all in CAD cents.', {
-        account_id: ACCOUNT_ID_ARG,
-    }, async ({ account_id }) => {
+    server.registerTool('list_send_limit_requests', { ...meta('list_send_limit_requests'), description: 'List past and pending "higher volume" sending requests for this account.', inputSchema: z.object({}) }, async () => {
+        try {
+            const result = await client.listSendLimitRequests();
+            return ok(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.registerTool('get_topup_allowance', { ...meta('get_topup_allowance'), description: 'How much credit can be added to the account right now. Top-ups are capped by a maximum balance and a rolling 30-day total ' +
+            '(platform defaults $500 and $1,000 CAD, raisable per account); a checkout above max_topup_now_cents is refused with TOPUP_LIMIT_REACHED. ' +
+            'Returns the caps, the current balance, the 30-day total so far, and the amount that fits now, all in CAD cents.', inputSchema: z.object({
+            account_id: ACCOUNT_ID_ARG,
+        }) }, async ({ account_id }) => {
         try {
             const result = await client.getTopupAllowance(await resolveAccountId(account_id));
             return ok(result);
@@ -503,7 +624,7 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('whoami', 'Identify the HonkIO account the configured API key belongs to. Returns the account ID, name, credit balance and status. Call this first when you need an account ID, or to confirm which account and mode (live or test) the key is for.', {}, async () => {
+    server.registerTool('whoami', { ...meta('whoami'), description: 'Identify the HonkIO account the configured API key belongs to: the account (ID, name, credit balance, status) and its list of API keys (each with its own prefix, mode and label). It does not say which of those keys is the one you are calling with (the API never identifies the calling key back to itself), so track your own key\'s mode (mk_live_... or mk_test_...) separately. Call this first when you need an account ID.', inputSchema: z.object({}) }, async () => {
         try {
             const result = await client.getCurrentAccount();
             return ok(result);
@@ -512,11 +633,11 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('get_account', 'Get details for your HonkIO account including name, credit balance, status, and active API keys. ' +
-        'Also returns phone_number_limit and phone_numbers_used — check these before calling ' +
-        'provision_phone_number, since a purchase past the limit is rejected with NUMBER_LIMIT_REACHED.', {
-        account_id: ACCOUNT_ID_ARG,
-    }, async ({ account_id }) => {
+    server.registerTool('get_account', { ...meta('get_account'), description: 'Get details for your HonkIO account including name, credit balance, status, and active API keys. ' +
+            'Also returns phone_number_limit and phone_numbers_used: check these before calling ' +
+            'provision_phone_number, since a purchase past the limit is rejected with NUMBER_LIMIT_REACHED.', inputSchema: z.object({
+            account_id: ACCOUNT_ID_ARG,
+        }) }, async ({ account_id }) => {
         try {
             const result = await client.getAccount(await resolveAccountId(account_id));
             return ok(result);
@@ -525,10 +646,10 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('update_account', 'Update your HonkIO account name.', {
-        account_id: ACCOUNT_ID_ARG,
-        name: z.string().min(1).max(200).describe('New account name.'),
-    }, async ({ account_id, name }) => {
+    server.registerTool('update_account', { ...meta('update_account'), description: 'Update your HonkIO account name.', inputSchema: z.object({
+            account_id: ACCOUNT_ID_ARG,
+            name: z.string().min(1).max(200).describe('New account name.'),
+        }) }, async ({ account_id, name }) => {
         try {
             const result = await client.updateAccount(await resolveAccountId(account_id), { name });
             return ok(result);
@@ -537,11 +658,11 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('get_usage', 'Get usage statistics for your account including message counts, spending, and live delivery health: "delivery" (liveOutbound, delivered, failed, undelivered, pending, failureRatePct) and "byNumber" (the same per sending number). A rising failure rate usually means wrong numbers, landlines, or a script retrying one recipient. Defaults to the current calendar month.', {
-        account_id: ACCOUNT_ID_ARG,
-        from: z.string().optional().describe('Start date (YYYY-MM-DD). Defaults to start of current month.'),
-        to: z.string().optional().describe('End date (YYYY-MM-DD). Defaults to today.'),
-    }, async ({ account_id, from, to }) => {
+    server.registerTool('get_usage', { ...meta('get_usage'), description: 'Get usage statistics for your account including message counts, spending, and live delivery health: "delivery" (liveOutbound, delivered, failed, undelivered, pending, failureRatePct) and "byNumber" (the same per sending number). A rising failure rate usually means wrong numbers, landlines, or a script retrying one recipient. Defaults to the current calendar month.', inputSchema: z.object({
+            account_id: ACCOUNT_ID_ARG,
+            from: z.string().optional().describe('Start date (YYYY-MM-DD). Defaults to start of current month.'),
+            to: z.string().optional().describe('End date (YYYY-MM-DD). Defaults to today.'),
+        }) }, async ({ account_id, from, to }) => {
         try {
             const result = await client.getUsage(await resolveAccountId(account_id), { from, to });
             return ok(result);
@@ -550,23 +671,37 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('create_api_key', 'Issue a new API key for your account. The raw key is shown once — store it securely.', {
-        account_id: ACCOUNT_ID_ARG,
-        mode: z.enum(['live', 'test']).optional().describe('Key mode: "live" (real SMS, charges apply) or "test" (sandbox, no charges). Default: "live".'),
-        label: z.string().max(100).optional().describe('Human-readable label to identify this key (e.g. "Production server", "CI pipeline").'),
-    }, async ({ account_id, mode, label }) => {
+    server.registerTool('list_transactions', { ...meta('list_transactions'), description: 'List the account\'s balance transaction ledger, newest first: top-ups, refunds, disputes, phone rent, provisioning fees, activation fees, and verification upcharges. Per-message SMS costs are NOT included here: see list_messages/get_message for those.', inputSchema: z.object({
+            account_id: ACCOUNT_ID_ARG,
+            limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 50, max: 100).'),
+            before: z.string().optional().describe('Id of the oldest transaction already seen: returns the next (older) page.'),
+        }) }, async ({ account_id, limit, before }) => {
+        try {
+            const result = await client.listTransactions(await resolveAccountId(account_id), { limit, before });
+            return ok(result);
+        }
+        catch (err) {
+            return formatError(err);
+        }
+    });
+    server.registerTool('create_api_key', { ...meta('create_api_key'), description: 'Issue a new API key for your account. The raw key is shown once: store it securely. A key can only be created with permissions the calling key itself holds: asking for more is refused with 403 PERMISSION_ESCALATION. A test key can only create test keys (mode "live" from a test key is refused with 403 LIVE_KEY_REQUIRED).', inputSchema: z.object({
+            account_id: ACCOUNT_ID_ARG,
+            mode: z.enum(['live', 'test']).optional().describe('Key mode: "live" or "test". Defaults to the calling key\'s own mode.'),
+            label: z.string().max(100).optional().describe('Human-readable label to identify this key (e.g. "Production server", "CI pipeline").'),
+            permissions: PERMISSIONS_ARG,
+        }) }, async ({ account_id, mode, label, permissions }) => {
         try {
-            const result = await client.createApiKey(await resolveAccountId(account_id), { mode, label });
+            const result = await client.createApiKey(await resolveAccountId(account_id), { mode, label, permissions });
             return ok(result);
         }
         catch (err) {
             return formatError(err);
         }
     });
-    server.tool('revoke_api_key', 'Revoke an API key, immediately blocking all requests using that key. This cannot be undone.', {
-        account_id: ACCOUNT_ID_ARG,
-        key_id: z.string().describe('The API key record ID to revoke (from get_account api_keys list).'),
-    }, async ({ account_id, key_id }) => {
+    server.registerTool('revoke_api_key', { ...meta('revoke_api_key'), description: 'Revoke an API key, immediately blocking all requests using that key. This cannot be undone. A test key can revoke any of the account\'s keys except a live one: revoking a live key needs a live key (403 LIVE_KEY_REQUIRED).', inputSchema: z.object({
+            account_id: ACCOUNT_ID_ARG,
+            key_id: z.string().describe('The API key record ID to revoke (from get_account api_keys list).'),
+        }) }, async ({ account_id, key_id }) => {
         try {
             await client.revokeApiKey(await resolveAccountId(account_id), key_id);
             return ok({ status: 'revoked', key_id });
@@ -575,10 +710,10 @@ export function registerTools(server, client) {
             return formatError(err);
         }
     });
-    server.tool('rotate_api_key', 'Atomically issue a replacement API key inheriting the same permissions/label/mode as the source key, and revoke the source key in the same transaction. Returns the new raw key ONCE.', {
-        account_id: ACCOUNT_ID_ARG,
-        key_id: z.string().describe('The API key record ID to rotate.'),
-    }, async ({ account_id, key_id }) => {
+    server.registerTool('rotate_api_key', { ...meta('rotate_api_key'), description: 'Atomically issue a replacement API key inheriting the same permissions, label, mode, allow/deny lists and default-deny flag as the source key, and revoke the source key in the same transaction. Returns the new raw key ONCE. A test key can only rotate a test key (403 LIVE_KEY_REQUIRED otherwise). A dashboard session key can never be the source: it always expires on its own (409 CONFLICT). Rotating a key into more permissions than the calling key holds, or calling this tool with a session key, is refused with 403 PERMISSION_ESCALATION.', inputSchema: z.object({
+            account_id: ACCOUNT_ID_ARG,
+            key_id: z.string().describe('The API key record ID to rotate.'),
+        }) }, async ({ account_id, key_id }) => {
         try {
             const result = await client.rotateApiKey(await resolveAccountId(account_id), key_id);
             return ok(result);