@honkio/mcp 1.4.0 → 1.5.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',
@@ -39,40 +40,29 @@ 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 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. ' +
+            '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.', 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. 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 +71,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 +89,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, 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 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,10 +101,10 @@ 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) => {
+    server.registerTool('search_phone_numbers', { ...meta('search_phone_numbers'), description: 'Search available Canadian phone numbers you can provision. Filter by area code to find numbers in a specific province.', inputSchema: z.object({
+            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) => {
         try {
             const result = await client.searchPhoneNumbers(input);
             return ok(result);
@@ -123,18 +113,18 @@ export function registerTools(server, client) {
             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. ' +
+            '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.', 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 +133,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 +142,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 +153,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. 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 });
@@ -175,16 +165,16 @@ export function registerTools(server, client) {
         }
     });
     // ── 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 +183,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 +197,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 +208,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 +220,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.', 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 +232,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 +247,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 +258,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 +270,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. Purges message bodies, consent records, and opt-out records for the specified number. 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 +283,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. 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 +295,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 +304,12 @@ 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('update_webhook', { ...meta('update_webhook'), description: 'Update a webhook endpoint URL, event subscriptions, or active status.', 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)).optional().describe('New event subscriptions (replaces existing).'),
+            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 +318,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.', 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 +329,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 +341,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. 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 +352,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). 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 +365,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. 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 +376,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. 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 +388,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 +398,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 +413,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. Returns the verification status (verified, invalid_code, expired, max_attempts).', 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 +425,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 +436,12 @@ 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 recent verifications for your account, optionally filtered by phone number or status.', inputSchema: z.object({
+            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) => {
         try {
             const result = await client.listVerifications(input);
             return ok(result);
@@ -462,11 +452,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 +465,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. 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.', 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 +480,11 @@ 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('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 +493,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. 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.', inputSchema: z.object({}) }, async () => {
         try {
             const result = await client.getCurrentAccount();
             return ok(result);
@@ -512,11 +502,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 +515,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 +527,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,11 +540,11 @@ 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('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.', inputSchema: z.object({
+            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 }) => {
         try {
             const result = await client.createApiKey(await resolveAccountId(account_id), { mode, label });
             return ok(result);
@@ -563,10 +553,10 @@ export function registerTools(server, client) {
             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.', 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 +565,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 as the source key, and revoke the source key in the same transaction. Returns the new raw key ONCE.', 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);