@wabery/cli 0.14.0 → 0.14.2

package/dist/mcp-server.js

@@ -85,13 +85,13 @@ const toolOutputSchema = {
         .record(z.string(), z.unknown())
         .describe("The structured Wabery API result object. Its operation-specific fields are described by the tool and Wabery API documentation."),
 };
-const SERVER_INSTRUCTIONS = `Use Wabery tools as a developer platform for WhatsApp, Instagram, and Messenger messaging: channels, routing, contacts, registration intents, conversations, message history, outbound messages, inbound media metadata, WhatsApp Flows, templates, broadcasts, automations, webhooks, and Meta Business Agent extensions.
-Recommended order: read wabery_get_config_schema, select the project, call wabery_get_project_readiness, list channels only when more channel detail is needed, check Business Agent eligibility before adding business_agent config, create registration intents or enroll WhatsApp contacts as needed, store returned contact_id plus channel_id, validate and preview config diff, apply config only after review, publish flows only after explicit confirmation, then send messages or published flows with channel_id and contact_id/conversation_id.
-Always distinguish sandbox testing from production readiness: a project without its own connected phone number can often still be tested in the shared Wabery sandbox, but production inbound traffic requires a dedicated project channel. For WhatsApp templates and proactive reminders, inspect readiness before creation: template submission and proactive template sends require a dedicated non-sandbox WhatsApp channel, Meta business verification/account approval, a connected phone, and a Meta payment method. After sending a message, use wabery_get_message to inspect provider status and failures.
-For broadcasts, use only approved WhatsApp templates on a dedicated channel and only contacts with valid category-specific consent. Create a draft, prepare exactly one audience source, poll wabery_get_broadcast until it is ready, inspect its counts and excluded recipients, and send or schedule only after explicit user confirmation. Preparation freezes the recipient snapshot; create a new draft when the intended audience changes. CSV files are uploaded through the dashboard or CLI; use wabery_list_contact_imports and wabery_get_contact_import to select a completed import.
-Use wabery_list_conversations, wabery_get_conversation, and wabery_list_conversation_messages to inspect history. Inbound WhatsApp media appears on message records/webhooks as media/assets metadata with Wabery signed URLs when retained; download files promptly because URLs are short-lived and retention is plan-based.
-Config apply creates or updates Wabery flows, automations, webhook settings, and eligible Meta Business Agent declarations. It never publishes flows to Meta. Automations and Business Agent connector tools can trigger flows through references to flow config keys.
-High-risk tools require confirmation_token values shown in each tool description.`;
+const SERVER_INSTRUCTIONS = `Wabery is a developer platform for building and operating WhatsApp AI agents. Start discovery with wabery_list_projects, select the intended project, then call wabery_get_project_readiness; use channel readiness only for phone-number/provider detail.
+Use Wabery for WhatsApp contacts, opt-in, conversations and message history, approved templates, Flows, broadcasts, routing/human handoff, signed webhooks, hosted functions, and Meta Business Agent configuration.
+Keep sandbox and production readiness distinct: the shared sandbox supports controlled tests; production inbound, proactive templates, and broadcasts require an eligible dedicated WhatsApp channel. Enroll only controlled or explicitly opted-in contacts and retain the returned contact_id and channel_id.
+Read conversations and message history before replying. Validate and preview config before apply; config apply may replace resources but never publishes a Flow. Draft and validate Flows before separately confirming publish or send.
+For broadcasts, create a draft with approved templates, prepare exactly one audience source, poll until ready, review recipients/exclusions, then obtain explicit confirmation before send or schedule. Preparation freezes the audience.
+Use routing and thread-control tools for automation ownership and human handoff. Treat hosted function test/invoke as potentially side-effecting code.
+Obtain explicit user confirmation immediately before any external or irreversible action, including sends, publishes, deletions, secret rotation, provider updates, or function execution. After sending, call wabery_get_message, wabery_get_dispatch, or wabery_get_broadcast to report provider status; acceptance is not delivery.`;
 // The write gate differs by transport, and the model has to be told the truth
 // about the session it is actually in: a hosted OAuth client (ChatGPT, Claude)
 // cannot set an env var, so advertising the env gate there makes it refuse to
@@ -113,6 +113,7 @@ const MCP_SENSITIVE_OUTPUT_KEY_SUFFIXES = [
     "credentials",
     "idtoken",
     "jwt",
+    "oauthtoken",
     "password",
     "passwordhash",
     "privatekey",
@@ -350,7 +351,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }));
     registerTool("wabery_check_connection", {
         title: "Check Wabery connection",
-        description: "Verify the configured API key can reach Wabery projects, channels, and the config schema before making changes.",
+        description: "Use this when you need to verify that the current credential can reach Wabery projects, WhatsApp channels, and the config schema before other work.",
         inputSchema: {},
         annotations: {
             readOnlyHint: true,
@@ -361,7 +362,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async () => jsonResult(await checkWaberyConnection(client)));
     registerTool("wabery_get_config_example", {
         title: "Get example Wabery config",
-        description: "Return a starter wabery.config.json with one flow and one automation that triggers it with a send_flow step.",
+        description: "Use this when you need a starter wabery.config.json with one WhatsApp Flow and one send_flow automation; optional project_id comes from wabery_list_projects.",
         inputSchema: {
             project_id: z
                 .string()
@@ -378,7 +379,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ project_id }) => jsonResult(createExampleConfig(project_id)));
     registerTool("wabery_get_config_schema", {
         title: "Get Wabery config schema",
-        description: "Return the JSON Schema for wabery.config.json. Use this before generating flows, automations, webhooks, or business_agent declarations.",
+        description: "Use this when you need the current JSON Schema before generating a wabery.config.json with Flows, automations, webhooks, or business_agent declarations.",
         inputSchema: {},
         annotations: {
             readOnlyHint: true,
@@ -389,7 +390,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async () => jsonResult(await client.get("/config/schema")));
     registerTool("wabery_export_config", {
         title: "Export Wabery config",
-        description: "Export the organization's flows, automations, webhook settings, and Business Agent declarations as a config object.",
+        description: "Use this when you need the selected project's current Flows, automations, webhook settings, and Business Agent declarations as declarative config. Do not use it to inspect live provider status.",
         inputSchema: {},
         annotations: {
             readOnlyHint: true,
@@ -400,7 +401,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async () => jsonResult(await client.get("/config")));
     registerTool("wabery_validate_config", {
         title: "Validate Wabery config",
-        description: "Validate a declarative config object without changing flows or automations.",
+        description: "Use this when you need to validate a complete declarative config without changing resources. Use wabery_preview_config_diff next to inspect effects.",
         inputSchema: {
             config: configSchema.describe("The full wabery.config.json object."),
         },
@@ -413,7 +414,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ config }) => apiResult(client.post("/config/validate", config)));
     registerTool("wabery_preview_config_diff", {
         title: "Preview Wabery config diff",
-        description: "Preview which flows, automations, webhook settings, Business Agents, connectors, and tools would be created, updated, deleted, or left unchanged.",
+        description: "Use this when you need to preview what a complete config would create, update, delete, or leave unchanged without applying it. Use wabery_apply_config only after reviewing this diff.",
         inputSchema: {
             config: configSchema.describe("The full wabery.config.json object."),
         },
@@ -426,7 +427,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ config }) => apiResult(client.post("/config/diff", config)));
     registerTool("wabery_apply_config", {
         title: "Apply Wabery config",
-        description: "Create, update, or remove Wabery flows, automations, webhook settings, and eligible Business Agent declarations from config. This does not publish flows to Meta; call wabery_publish_flow explicitly after review.",
+        description: "Use this when you need to apply a reviewed complete config, creating, overwriting, or removing Wabery Flows, automations, webhooks, and eligible Business Agent resources. Do not use it for one resource update when a narrow update tool fits. It never publishes Flows; use wabery_publish_flow separately.",
         inputSchema: {
             config: configSchema.describe("The full wabery.config.json object."),
             confirmation_token: z
@@ -438,7 +439,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
-            openWorldHint: false,
+            openWorldHint: true,
         },
     }, async (input) => {
         const { config, confirmation_token } = input;
@@ -468,7 +469,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_list_business_agents", {
         title: "List Meta Business Agents",
-        description: "List Meta Business Agent records for the selected Wabery project.",
+        description: "Use this when you need the selected project's Meta Business Agent records and business_agent_id values. Do not use it for live settings; use wabery_get_business_agent_settings.",
         inputSchema: {
             channel_id: z.string().min(1).optional(),
         },
@@ -483,22 +484,22 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     })));
     registerTool("wabery_check_business_agent_eligibility", {
         title: "Check Meta Business Agent eligibility",
-        description: "Check whether a WhatsApp channel is eligible for Meta Business Agent.",
+        description: "Use this when you need to query Meta eligibility for a WhatsApp channel_id from wabery_list_channels before provisioning a Business Agent. This also caches the provider result in Wabery.",
         inputSchema: {
             channel_id: z.string().min(1),
         },
         annotations: {
-            readOnlyHint: true,
+            readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
         },
     }, async ({ channel_id }) => jsonResult(await client.get("/business-agents/eligibility", {
         channel_id,
     })));
     registerTool("wabery_apply_business_agent", {
         title: "Apply Meta Business Agent settings",
-        description: "Provision or update a Meta Business Agent for a WhatsApp channel. Prefer wabery_apply_config when managing the whole project declaratively.",
+        description: "Use this when you need to provision or overwrite Meta Business Agent settings for a channel_id from wabery_list_channels. Prefer wabery_apply_config for reviewed project-wide declarative changes.",
         inputSchema: {
             channel_id: z.string().min(1),
             enabled: z.boolean().optional(),
@@ -513,9 +514,9 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
-            openWorldHint: false,
+            openWorldHint: true,
         },
     }, async (input) => {
         const { confirmation_token, ...body } = input;
@@ -526,7 +527,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_get_business_agent_settings", {
         title: "Get Meta Business Agent settings",
-        description: "Retrieve live Meta Business Agent settings.",
+        description: "Use this when you need live Meta settings for a business_agent_id from wabery_list_business_agents. Do not use it for the cached Wabery record.",
         inputSchema: {
             business_agent_id: z.string().min(1),
         },
@@ -539,7 +540,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ business_agent_id }) => jsonResult(await client.get(`/business-agents/${encodeURIComponent(business_agent_id)}/settings`)));
     registerTool("wabery_update_business_agent_settings", {
         title: "Update Meta Business Agent settings",
-        description: "Update live Meta Business Agent settings.",
+        description: "Use this when you need to overwrite live Meta settings for a business_agent_id from wabery_list_business_agents. Prefer wabery_apply_business_agent when provisioning by channel.",
         inputSchema: {
             business_agent_id: z.string().min(1),
             enabled: z.boolean().optional(),
@@ -554,7 +555,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: true,
         },
@@ -567,7 +568,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_list_business_agent_connectors", {
         title: "List Meta Business Agent connectors",
-        description: "List connector records for Meta Business Agents in the selected Wabery project.",
+        description: "Use this when you need connector records and connector_id values for the selected project, optionally filtered by a business_agent_id from wabery_list_business_agents.",
         inputSchema: {
             business_agent_id: z.string().min(1).optional(),
         },
@@ -582,7 +583,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     })));
     registerTool("wabery_create_business_agent_connector", {
         title: "Create Meta Business Agent connector",
-        description: "Create a connector on a provisioned Meta Business Agent. Prefer wabery_apply_config for declarative project-wide changes.",
+        description: "Use this when you need to create a connector in Meta for a provisioned business_agent_id from wabery_list_business_agents. Prefer wabery_apply_config for reviewed project-wide declarative changes.",
         inputSchema: {
             business_agent_id: z.string().min(1),
             name: z.string().min(1).max(120),
@@ -597,8 +598,8 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
         },
     }, async (input) => {
         const { confirmation_token, ...body } = input;
@@ -609,7 +610,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_create_business_agent_connector_tool", {
         title: "Create Meta Business Agent connector tool",
-        description: "Create a connector tool backed by a Wabery Flow, hosted function, API endpoint, or no-op placeholder.",
+        description: "Use this when you need to create a Meta connector tool for a connector_id from wabery_list_business_agent_connectors. backing_type is FLOW, HOSTED_FUNCTION, API_ENDPOINT, or NOOP; use the matching id from wabery_list_flows or wabery_list_functions.",
         inputSchema: {
             connector_id: z.string().min(1),
             name: z.string().min(1).max(120),
@@ -632,8 +633,8 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
         },
     }, async (input) => {
         const { connector_id, confirmation_token, ...body } = input;
@@ -644,7 +645,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_list_business_agent_connector_tools", {
         title: "List Meta Business Agent connector tools",
-        description: "List tools for a Meta Business Agent connector.",
+        description: "Use this when you need local connector-tool records and tool_id values for a connector_id from wabery_list_business_agent_connectors.",
         inputSchema: {
             connector_id: z.string().min(1),
         },
@@ -657,7 +658,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ connector_id }) => jsonResult(await client.get(`/business-agents/connectors/${encodeURIComponent(connector_id)}/tools`)));
     registerTool("wabery_get_business_agent_connector_tool", {
         title: "Get Meta Business Agent connector tool",
-        description: "Fetch one Meta Business Agent connector tool.",
+        description: "Use this when you need one connector tool by connector_id and tool_id from wabery_list_business_agent_connector_tools.",
         inputSchema: {
             connector_id: z.string().min(1),
             tool_id: z.string().min(1),
@@ -671,7 +672,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ connector_id, tool_id }) => jsonResult(await client.get(`/business-agents/connectors/${encodeURIComponent(connector_id)}/tools/${encodeURIComponent(tool_id)}`)));
     registerTool("wabery_update_business_agent_connector_tool", {
         title: "Update Meta Business Agent connector tool",
-        description: "Update one Meta Business Agent connector tool.",
+        description: "Use this when you need to overwrite a Meta connector tool identified by connector_id and tool_id from wabery_list_business_agent_connector_tools. Use create only for a new tool.",
         inputSchema: {
             connector_id: z.string().min(1),
             tool_id: z.string().min(1),
@@ -691,9 +692,9 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
-            openWorldHint: false,
+            openWorldHint: true,
         },
     }, async (input) => {
         const { connector_id, tool_id, confirmation_token, ...body } = input;
@@ -704,7 +705,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_delete_business_agent_connector_tool", {
         title: "Delete Meta Business Agent connector tool",
-        description: "Delete one Meta Business Agent connector tool.",
+        description: "Use this when you need to permanently delete a Meta connector tool identified by connector_id and tool_id from wabery_list_business_agent_connector_tools.",
         inputSchema: {
             connector_id: z.string().min(1),
             tool_id: z.string().min(1),
@@ -717,7 +718,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
-            openWorldHint: false,
+            openWorldHint: true,
         },
     }, async ({ connector_id, tool_id, confirmation_token }) => {
         const blocked = await requireWrite("wabery_delete_business_agent_connector_tool", confirmation_token, "delete_business_agent_connector_tool");
@@ -727,7 +728,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_get_business_agent_thread_control", {
         title: "Get Meta Business Agent thread control",
-        description: "Inspect WhatsApp thread control for a channel/contact pair without changing its owner.",
+        description: "Use this when you need to inspect current WhatsApp thread ownership for a channel_id from wabery_list_channels and contact_id from wabery_list_contacts. Use the set tool for handoff.",
         inputSchema: {
             channel_id: z.string().min(1),
             contact_id: z.string().min(1),
@@ -735,9 +736,9 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             thread_id: z.string().min(1).optional(),
         },
         annotations: {
-            readOnlyHint: true,
+            readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
+            idempotentHint: false,
             openWorldHint: true,
         },
     }, async (input) => jsonResult(await client.post("/business-agents/thread-control", {
@@ -746,7 +747,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     })));
     registerTool("wabery_set_business_agent_thread_control", {
         title: "Set Meta Business Agent thread control",
-        description: "Take or pass WhatsApp thread control for a channel/contact pair. Use the separate get tool to inspect current ownership.",
+        description: "Use this when you need to take or pass WhatsApp thread control for a channel_id and contact_id, changing automation or human ownership. Inspect first with wabery_get_business_agent_thread_control.",
         inputSchema: {
             action: z.enum(["take", "pass"]),
             channel_id: z.string().min(1),
@@ -762,7 +763,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: true,
         },
@@ -775,22 +776,31 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_test_business_agent", {
         title: "Test Meta Business Agent",
-        description: "Run a Meta Business Agent test scenario.",
+        description: "Use this when you need to submit a controlled test scenario to Meta for a business_agent_id from wabery_list_business_agents. This is a remote provider operation, not a read or a real-recipient message send.",
         inputSchema: {
             business_agent_id: z.string().min(1),
             input: z.string().min(1).optional(),
             scenario: z.record(z.string(), z.unknown()).optional(),
+            confirmation_token: z
+                .string()
+                .optional()
+                .describe("Required when write mode is enabled: test_business_agent"),
         },
         annotations: {
-            readOnlyHint: true,
+            readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async (body) => jsonResult(await client.post("/business-agents/test", body)));
+    }, async ({ confirmation_token, ...body }) => {
+        const blocked = await requireWrite("wabery_test_business_agent", confirmation_token, "test_business_agent");
+        if (blocked)
+            return blocked;
+        return jsonResult(await client.post("/business-agents/test", body));
+    });
     registerTool("wabery_get_business_agent_eval", {
         title: "Get Meta Business Agent eval summary",
-        description: "Retrieve the Meta Business Agent eval summary.",
+        description: "Use this when you need the live Meta evaluation summary for a business_agent_id from wabery_list_business_agents. Do not use it to run a test scenario.",
         inputSchema: {
             business_agent_id: z.string().min(1),
         },
@@ -805,7 +815,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     })));
     registerTool("wabery_list_business_agent_skills", {
         title: "List Meta Business Agent skills",
-        description: "List configured Meta Business Agent skills.",
+        description: "Use this when you need the current Meta skill list for a business_agent_id from wabery_list_business_agents. Use the set tool only to replace the full list.",
         inputSchema: {
             business_agent_id: z.string().min(1),
         },
@@ -820,7 +830,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     })));
     registerTool("wabery_set_business_agent_skills", {
         title: "Set Meta Business Agent skills",
-        description: "Replace configured Meta Business Agent skills.",
+        description: "Use this when you need to replace the entire Meta skill list for a business_agent_id from wabery_list_business_agents. Do not use it to append one skill without first preserving existing entries.",
         inputSchema: {
             business_agent_id: z.string().min(1),
             skills: z.array(z.unknown()),
@@ -843,7 +853,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_list_projects", {
         title: "List Wabery projects",
-        description: "List projects and their project_id values. Use project_id when creating flows or enrolling WhatsApp contacts.",
+        description: "Use this when you need to discover Wabery projects and their project_id values before selecting a project or passing an explicit project_id.",
         inputSchema: {},
         annotations: {
             readOnlyHint: true,
@@ -855,7 +865,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     if (options.projectSelection) {
         registerTool("wabery_get_selected_project", {
             title: "Get selected Wabery project",
-            description: "Return the project currently selected for this MCP session. If no project has been selected, Wabery uses the credential's default project.",
+            description: "Use this when you need to confirm which project this MCP session will use. A null selection means the credential's default project remains active.",
             inputSchema: {},
             annotations: {
                 readOnlyHint: true,
@@ -870,7 +880,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         }));
         registerTool("wabery_select_project", {
             title: "Select Wabery project",
-            description: "Select the project that subsequent Wabery MCP tools should use in this session. Call wabery_list_projects first, then pass the project_id.",
+            description: "Use this when you need subsequent tools in this MCP session to target a project_id returned by wabery_list_projects. This changes session state, not the project itself.",
             inputSchema: {
                 project_id: z.string().min(1),
             },
@@ -892,7 +902,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }
     registerTool("wabery_get_project_readiness", {
         title: "Get Wabery project readiness",
-        description: "Explain what the selected project can do now: sandbox testing, production inbound, flow publish/send, templates, proactive messages, routing, opt-in, and submission handling. Call before building, after wabery_apply_config, before template/reminder work, and before the final creator summary.",
+        description: "Use this when you need capability readiness for the selected project or a project_id from wabery_list_projects: sandbox_test, production_inbound, flow_publish, flow_send, templates, proactive_messages, or submission_handling. Use channel readiness only for provider-specific phone details.",
         inputSchema: {
             project_id: z.string().min(1).optional(),
             requirements: z.array(readinessRequirementSchema).optional(),
@@ -906,7 +916,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ project_id, requirements }) => jsonResult(await getReadiness(project_id, requirements)));
     registerTool("wabery_get_project", {
         title: "Get a Wabery project",
-        description: "Fetch a single project's user-safe configuration. Secrets and provider credentials are omitted from MCP results.",
+        description: "Use this when you need one project's user-safe settings by project_id from wabery_list_projects. Do not use it for capability readiness; use wabery_get_project_readiness.",
         inputSchema: { project_id: z.string().min(1) },
         annotations: {
             readOnlyHint: true,
@@ -917,7 +927,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ project_id }) => jsonResult(await client.get(`/projects/${encodeURIComponent(project_id)}`)));
     registerTool("wabery_update_project", {
         title: "Update a Wabery project",
-        description: "Update name, description, routing_mode, require_opt_in, or webhook config (url, signing on/off, or a bring-your-own secret) of an existing project. Set require_opt_in=false on a dedicated production number so inbound senders can be replied to and messaged without the invite/opt-in step.",
+        description: "Use this when you need to overwrite project name, description, routing_mode, require_opt_in, or signed-webhook settings for a project_id from wabery_list_projects. Prefer wabery_apply_config for reviewed project-wide declarative changes.",
         inputSchema: {
             project_id: z.string().min(1),
             name: z.string().min(1).max(100).optional(),
@@ -927,25 +937,33 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             webhook_url: z.string().url().nullable().optional(),
             webhook_signing_enabled: z.boolean().optional(),
             webhook_secret: z.string().min(16).max(256).optional(),
+            confirmation_token: z
+                .string()
+                .optional()
+                .describe("Required when write mode is enabled: update_project"),
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_id, ...body }) => {
-        const blocked = await requireWrite("wabery_update_project");
+    }, async ({ project_id, confirmation_token, ...body }) => {
+        const blocked = await requireWrite("wabery_update_project", confirmation_token, "update_project");
         if (blocked)
             return blocked;
         return jsonResult(await client.patch(`/projects/${encodeURIComponent(project_id)}`, body));
     });
     registerTool("wabery_rotate_webhook_secret", {
         title: "Rotate a project's webhook secret",
-        description: "Set a new signing secret (server-generated, or a provided one) and invalidate the previous secret. MCP confirms the rotation but omits the secret value; retrieve or manage sensitive credentials in the Wabery dashboard.",
+        description: "Use this when you need to invalidate and replace the signed-webhook secret for a project_id from wabery_list_projects. The MCP result never returns the new secret; manage it in the Wabery dashboard.",
         inputSchema: {
             project_id: z.string().min(1),
             webhook_secret: z.string().min(16).max(256).optional(),
+            confirmation_token: z
+                .string()
+                .optional()
+                .describe("Required when write mode is enabled: rotate_webhook_secret"),
         },
         annotations: {
             readOnlyHint: false,
@@ -953,15 +971,15 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ project_id, webhook_secret }) => {
-        const blocked = await requireWrite("wabery_rotate_webhook_secret");
+    }, async ({ project_id, webhook_secret, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_rotate_webhook_secret", confirmation_token, "rotate_webhook_secret");
         if (blocked)
             return blocked;
         return jsonResult(await client.post(`/projects/${encodeURIComponent(project_id)}/rotate-webhook-secret`, webhook_secret ? { webhook_secret } : undefined));
     });
     registerTool("wabery_list_channels", {
         title: "List Wabery channels",
-        description: "List connected messaging channels. Use a WhatsApp channel_id when sending a published flow. For WhatsApp templates or proactive template sends, inspect publish_readiness and tell the creator when a dedicated phone number, verified business, approved account, connected phone, or Meta payment method is missing.",
+        description: "Use this when you need WhatsApp channel_id values, connection state, routing warnings, or provider publish_readiness. Use project readiness first for capability-level discovery.",
         inputSchema: {},
         annotations: {
             readOnlyHint: true,
@@ -972,7 +990,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async () => jsonResult(await client.get("/channels")));
     registerTool("wabery_get_channel", {
         title: "Get a Wabery channel",
-        description: "Fetch a single channel, including routing_warning and WhatsApp publish_readiness. If can_submit_templates is false, explain the blockers before attempting template creation or proactive template sends.",
+        description: "Use this when you need routing_warning and WhatsApp publish_readiness for a channel_id from wabery_list_channels. Do not use it as a substitute for project-level readiness.",
         inputSchema: { channel_id: z.string().min(1) },
         annotations: {
             readOnlyHint: true,
@@ -983,19 +1001,23 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ channel_id }) => jsonResult(await client.get(`/channels/${encodeURIComponent(channel_id)}`)));
     registerTool("wabery_update_channel", {
         title: "Update a Wabery channel's routing",
-        description: "Set a dedicated channel's routing_mode (NONE | FLOWS | EXTERNAL). Use EXTERNAL so inbound to this channel is forwarded to the project webhook. The shared sandbox channel routes per-participant and cannot be updated this way.",
+        description: "Use this when you need to overwrite a dedicated channel's routing_mode with NONE, FLOWS, or EXTERNAL using a channel_id from wabery_list_channels. Do not use it for the shared sandbox; update project routing instead.",
         inputSchema: {
             channel_id: z.string().min(1),
             routing_mode: z.enum(["NONE", "FLOWS", "EXTERNAL"]),
+            confirmation_token: z
+                .string()
+                .optional()
+                .describe("Required when write mode is enabled: update_channel"),
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ channel_id, routing_mode }) => {
-        const blocked = await requireWrite("wabery_update_channel");
+    }, async ({ channel_id, routing_mode, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_update_channel", confirmation_token, "update_channel");
         if (blocked)
             return blocked;
         return jsonResult(await client.patch(`/channels/${encodeURIComponent(channel_id)}`, {
@@ -1004,7 +1026,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_create_registration_intent", {
         title: "Create registration intent",
-        description: "Mint a single-use wa.me registration link so an end-customer can connect over WhatsApp.",
+        description: "Use this when you need a single-use wa.me link for an end customer to register with a project_id from wabery_list_projects. This creates the link but does not contact the customer.",
         inputSchema: {
             project_id: z
                 .string()
@@ -1035,7 +1057,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_get_registration_intent", {
         title: "Get registration intent",
-        description: "Poll a registration intent's status. Works with a publishable key or a scoped secret key.",
+        description: "Use this when you need to poll a registration intent by intent_id returned by wabery_create_registration_intent. Do not create another intent merely to check status.",
         inputSchema: {
             intent_id: z.string().min(1),
         },
@@ -1048,7 +1070,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ intent_id }) => jsonResult(await client.get(`/registration-intents/${encodeURIComponent(intent_id)}`)));
     registerTool("wabery_get_limits", {
         title: "Get Wabery API limits",
-        description: "Return the enforced public API rate limit and monthly request quota for the configured API key.",
+        description: "Use this when you need the current credential's enforced public API rate limit and monthly request quota. Do not use it for product-plan feature readiness.",
         inputSchema: {},
         annotations: {
             readOnlyHint: true,
@@ -1059,7 +1081,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async () => jsonResult(await client.get("/limits")));
     registerTool("wabery_list_flows", {
         title: "List Wabery flows",
-        description: "List flows, including ids, config keys, project ids, and Meta publish status.",
+        description: "Use this when you need WhatsApp Flow ids, config keys, project ids, or Meta publish statuses before get, publish, send, dispatch, or submission operations.",
         inputSchema: {},
         annotations: {
             readOnlyHint: true,
@@ -1070,7 +1092,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async () => jsonResult(await client.get("/flows")));
     registerTool("wabery_get_flow", {
         title: "Get Wabery flow",
-        description: "Fetch one flow by id, including status and field schema.",
+        description: "Use this when you need one WhatsApp Flow's draft, field schema, and publish status by flow_id from wabery_list_flows.",
         inputSchema: {
             flow_id: z.string().min(1),
         },
@@ -1083,7 +1105,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ flow_id }) => jsonResult(await client.get(`/flows/${flow_id}`)));
     registerTool("wabery_publish_flow", {
         title: "Publish Wabery flow",
-        description: "Publish a Wabery draft flow to Meta. Only call after validate/diff/apply and explicit user confirmation.",
+        description: "Use this when you need to publish a reviewed draft WhatsApp Flow to Meta using a flow_id from wabery_list_flows. Do not use it to save a draft; use config apply, and obtain explicit confirmation first.",
         inputSchema: {
             flow_id: z.string().min(1),
             confirmation_token: z
@@ -1105,7 +1127,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_enroll_contact", {
         title: "Enroll WhatsApp contact",
-        description: "Register a phone number against a Wabery project. Returns contact_id, which is the stable id used in flow submissions and future sends.",
+        description: "Use this when you need to register a controlled or explicitly opted-in WhatsApp phone number for a project_id from wabery_list_projects. It returns stable contact_id and channel_id values for later sends.",
         inputSchema: {
             phone: z.string().min(5).describe("E.164 phone number."),
             project_id: z.string().min(1),
@@ -1127,7 +1149,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
+            idempotentHint: false,
             openWorldHint: false,
         },
     }, async (input) => {
@@ -1138,7 +1160,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_list_contacts", {
         title: "List Wabery contacts",
-        description: "List enrolled contacts and their stable contact_id values.",
+        description: "Use this when you need enrolled WhatsApp contacts, stable contact_id values, and opt-in metadata before a targeted send or audience preparation.",
         inputSchema: {
             limit: z.number().int().min(1).max(100).optional(),
             starting_after: z.string().optional(),
@@ -1152,7 +1174,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ limit, starting_after }) => jsonResult(await client.get("/contacts", { limit, starting_after })));
     registerTool("wabery_get_contact", {
         title: "Get Wabery contact",
-        description: "Fetch one enrolled contact by stable contact_id before sending or unenrolling.",
+        description: "Use this when you need one enrolled WhatsApp contact and consent state by contact_id from wabery_list_contacts or wabery_enroll_contact.",
         inputSchema: {
             contact_id: z.string().min(1),
         },
@@ -1165,7 +1187,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ contact_id }) => jsonResult(await client.get(`/contacts/${contact_id}`)));
     registerTool("wabery_list_contact_imports", {
         title: "List Wabery contact imports",
-        description: "List CSV contact imports and their processing counts. Upload files in the dashboard or CLI, then use a completed import_id as a broadcast audience source.",
+        description: "Use this when you need CSV import_id values and processing counts after uploading through the dashboard or CLI. Only a completed import belongs in wabery_prepare_broadcast_audience.",
         inputSchema: {
             limit: z.number().int().min(1).max(100).optional(),
             starting_after: z.string().optional(),
@@ -1179,7 +1201,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async (query) => apiResult(client.get("/contact-imports", query)));
     registerTool("wabery_get_contact_import", {
         title: "Get Wabery contact import",
-        description: "Inspect one CSV contact import's status and row counts. Wait for completed before using its import_id to prepare a broadcast.",
+        description: "Use this when you need status and row counts for an import_id from wabery_list_contact_imports. Wait for completed before broadcast preparation.",
         inputSchema: {
             import_id: z.string().min(1),
         },
@@ -1192,7 +1214,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ import_id }) => apiResult(client.get(`/contact-imports/${import_id}`)));
     registerTool("wabery_unenroll_contact", {
         title: "Unenroll Wabery contact",
-        description: "Remove a contact phone's sandbox authorization for this organization. Pass erase=true for irreversible org-scoped contact data deletion.",
+        description: "Use this when you need to remove sandbox authorization for a contact_id from wabery_list_contacts. Set erase=true only for confirmed, irreversible organization-scoped contact-data deletion.",
         inputSchema: {
             contact_id: z.string().min(1),
             erase: z.boolean().optional(),
@@ -1215,7 +1237,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_list_broadcasts", {
         title: "List Wabery broadcasts",
-        description: "List broadcast campaigns and delivery counts. Filter by lifecycle status when monitoring preparation or delivery.",
+        description: "Use this when you need WhatsApp broadcast_id values, lifecycle states, or aggregate delivery counts. Filter by status when monitoring preparation or delivery.",
         inputSchema: {
             limit: z.number().int().min(1).max(100).optional(),
             starting_after: z.string().optional(),
@@ -1230,7 +1252,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async (query) => apiResult(client.get("/broadcasts", query)));
     registerTool("wabery_get_broadcast", {
         title: "Get Wabery broadcast",
-        description: "Fetch one broadcast with its lifecycle status and recipient counts. Poll while status is preparing, and review counts before requesting send or schedule confirmation.",
+        description: "Use this when you need lifecycle status and recipient counts for a broadcast_id from wabery_list_broadcasts. Poll while preparing and review counts before send or schedule confirmation.",
         inputSchema: {
             broadcast_id: z.string().min(1),
         },
@@ -1243,7 +1265,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ broadcast_id }) => apiResult(client.get(`/broadcasts/${broadcast_id}`)));
     registerTool("wabery_create_broadcast", {
         title: "Create Wabery broadcast draft",
-        description: "Create a draft from approved WhatsApp template variants. This does not select recipients or send messages. Use a dedicated WhatsApp channel and category-specific consent.",
+        description: "Use this when you need a new WhatsApp broadcast draft from approved template variants and a channel_id from wabery_list_channels. This does not select recipients or send; use prepare next.",
         inputSchema: {
             name: z.string().min(1).max(120),
             channel_id: z.string().min(1),
@@ -1286,7 +1308,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_prepare_broadcast_audience", {
         title: "Prepare Wabery broadcast audience",
-        description: "Resolve and freeze a draft broadcast's recipients from exactly one source: contact_ids, import_id, or filter. Preparation is asynchronous and does not send messages. Poll wabery_get_broadcast until ready, then inspect counts and recipients.",
+        description: "Use this when you need to start asynchronous audience resolution and overwrite the frozen recipient snapshot for a draft broadcast_id. Supply exactly one source: contact_ids from wabery_list_contacts, a completed import_id, or filter. This does not send; poll wabery_get_broadcast.",
         inputSchema: {
             broadcast_id: z.string().min(1),
             contact_ids: z.array(z.string().min(1)).max(1000).optional(),
@@ -1296,8 +1318,8 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
+            destructiveHint: true,
+            idempotentHint: false,
             openWorldHint: false,
         },
     }, async ({ broadcast_id, contact_ids, import_id, filter, exclude_contact_ids, }) => {
@@ -1332,7 +1354,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_list_broadcast_recipients", {
         title: "List Wabery broadcast recipients",
-        description: "Inspect the prepared recipient snapshot, language selection, skips, failures, and delivery state. Use before confirmation and while monitoring delivery.",
+        description: "Use this when you need the frozen recipients, language selection, exclusions, failures, or delivery state for a prepared broadcast_id from wabery_list_broadcasts.",
         inputSchema: {
             broadcast_id: z.string().min(1),
             limit: z.number().int().min(1).max(100).optional(),
@@ -1348,7 +1370,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ broadcast_id, ...query }) => apiResult(client.get(`/broadcasts/${broadcast_id}/recipients`, query)));
     registerTool("wabery_send_broadcast", {
         title: "Send Wabery broadcast",
-        description: "Start sending a ready broadcast to its frozen recipient snapshot. This creates real external WhatsApp messages and requires explicit user confirmation with confirmation_token send_broadcast:<broadcast_id>.",
+        description: "Use this when you need to start real WhatsApp delivery for a ready broadcast_id after reviewing its frozen audience and counts. Do not use it for preparation; explicit confirmation is required.",
         inputSchema: {
             broadcast_id: z.string().min(1),
             confirmation_token: z
@@ -1370,7 +1392,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_schedule_broadcast", {
         title: "Schedule Wabery broadcast",
-        description: "Schedule a ready broadcast for future delivery to its frozen recipient snapshot. Requires explicit user confirmation with confirmation_token schedule_broadcast:<broadcast_id>.",
+        description: "Use this when you need future WhatsApp delivery for a ready broadcast_id after reviewing its frozen audience, scheduled_at, and IANA timezone. Do not use it for immediate delivery; explicit confirmation is required.",
         inputSchema: {
             broadcast_id: z.string().min(1),
             scheduled_at: z.string().datetime(),
@@ -1397,7 +1419,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_cancel_broadcast", {
         title: "Cancel Wabery broadcast",
-        description: "Cancel a draft, ready, scheduled, or sending broadcast and stop recipients that have not been dispatched. Already accepted messages cannot be recalled. Requires confirmation_token cancel_broadcast:<broadcast_id>.",
+        description: "Use this when you need to cancel a broadcast_id and stop recipients not yet dispatched. Already accepted WhatsApp messages cannot be recalled; explicit confirmation is required.",
         inputSchema: {
             broadcast_id: z.string().min(1),
             confirmation_token: z
@@ -1409,7 +1431,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
-            openWorldHint: false,
+            openWorldHint: true,
         },
     }, async ({ broadcast_id, confirmation_token }) => {
         const blocked = await requireBroadcastApproval("wabery_cancel_broadcast", `Cancel broadcast ${broadcast_id}? Messages already accepted by WhatsApp cannot be recalled.`, confirmation_token, `cancel_broadcast:${broadcast_id}`);
@@ -1419,7 +1441,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_duplicate_broadcast", {
         title: "Duplicate Wabery broadcast",
-        description: "Create a new draft with the source broadcast's channel, template variants, and parameter mappings. The recipient snapshot is not copied; prepare a new audience before sending.",
+        description: "Use this when you need a new draft copied from a broadcast_id's channel, template variants, and mappings. The audience is never copied; prepare a new controlled audience.",
         inputSchema: {
             broadcast_id: z.string().min(1),
         },
@@ -1437,7 +1459,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_list_conversations", {
         title: "List Wabery conversations",
-        description: "List organization-scoped conversations for inbox, support, or analytics tooling.",
+        description: "Use this when you need organization-scoped WhatsApp conversation_id values for inbox review, support, or message-history lookup. Filter by contact_id when known.",
         inputSchema: {
             contact_id: z.string().optional(),
             active: z.boolean().optional(),
@@ -1456,7 +1478,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     })));
     registerTool("wabery_get_conversation", {
         title: "Get Wabery conversation",
-        description: "Fetch one organization-scoped conversation by id.",
+        description: "Use this when you need one organization-scoped WhatsApp conversation by conversation_id from wabery_list_conversations.",
         inputSchema: {
             conversation_id: z.string().min(1),
         },
@@ -1469,7 +1491,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ conversation_id }) => jsonResult(await client.get(`/conversations/${conversation_id}`)));
     registerTool("wabery_list_conversation_messages", {
         title: "List Wabery conversation messages",
-        description: "Fetch message history for a conversation. Cached inbound WhatsApp media includes short-lived Wabery signed URLs; expires_at is the retention deadline.",
+        description: "Use this when you need message history for a conversation_id from wabery_list_conversations. Retained inbound media may include short-lived signed URLs; expires_at is the retention deadline.",
         inputSchema: {
             conversation_id: z.string().min(1),
             limit: z.number().int().min(1).max(100).optional(),
@@ -1484,10 +1506,16 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
     }, async ({ conversation_id, ...query }) => jsonResult(await client.get(`/conversations/${conversation_id}/messages`, query)));
     registerTool("wabery_send_message", {
-        title: "Send Wabery message",
-        description: "Send a WhatsApp text, approved template, media, or interactive message. The body must match POST /messages and should include an idempotency_key for retries.",
+        title: "Send WhatsApp message",
+        description: "Use this when you need to send one real WhatsApp text, approved template, media, or interactive message. Do not use it to send a Flow; use wabery_send_flow. The body must identify channel and recipient using ids from list tools and should include idempotency_key; explicit confirmation is required.",
         inputSchema: {
-            body: z.record(z.string(), z.unknown()),
+            body: z
+                .record(z.string(), z.unknown())
+                .describe("POST /messages body. Include channel_id plus contact_id, conversation_id, or to; include type-specific content and an idempotency_key for safe retries."),
+            confirmation_token: z
+                .string()
+                .optional()
+                .describe("Required when write mode is enabled: send_message"),
         },
         annotations: {
             readOnlyHint: false,
@@ -1495,15 +1523,15 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ body }) => {
-        const blocked = await requireWrite("wabery_send_message");
+    }, async ({ body, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_send_message", confirmation_token, "send_message");
         if (blocked)
             return blocked;
         return apiResult(client.post("/messages", body));
     });
     registerTool("wabery_get_message", {
         title: "Get Wabery message",
-        description: "Fetch one message by message_id to inspect queued/provider status, delivery state, and Meta failure details after wabery_send_message.",
+        description: "Use this when you need queued, provider, delivery, or failure status for a message_id returned by wabery_send_message or message history. An accepted send is not proof of delivery.",
         inputSchema: {
             message_id: z.string().min(1),
         },
@@ -1516,7 +1544,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ message_id }) => jsonResult(await client.get(`/messages/${message_id}`)));
     registerTool("wabery_list_templates", {
         title: "List WhatsApp templates",
-        description: "List WhatsApp message templates and approval statuses for dedicated WhatsApp channels.",
+        description: "Use this when you need WhatsApp template_id values and approval states, optionally for a channel_id from wabery_list_channels, before template sends or broadcasts.",
         inputSchema: {
             channel_id: z.string().optional(),
             status: z.string().optional(),
@@ -1530,25 +1558,31 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async (query) => jsonResult(await client.get("/templates", query)));
     registerTool("wabery_get_template", {
         title: "Get WhatsApp template",
-        description: "Fetch one WhatsApp template and its Meta approval status. Set refresh=true to force a live Meta status check.",
+        description: "Use this when you need one template by template_id from wabery_list_templates. Set refresh=true only for a live Meta check that also updates Wabery's cached status.",
         inputSchema: {
             template_id: z.string().min(1),
             refresh: z.boolean().optional(),
         },
         annotations: {
-            readOnlyHint: true,
+            readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
         },
     }, async ({ template_id, refresh }) => jsonResult(await client.get(`/templates/${template_id}`, {
         refresh: refresh ? "true" : undefined,
     })));
     registerTool("wabery_create_template", {
         title: "Create WhatsApp template",
-        description: "Create and submit a WhatsApp message template to Meta for approval. Only dedicated, non-sandbox WhatsApp channels with Meta-verified business accounts and a Meta payment method can submit templates. Check channel publish_readiness first.",
+        description: "Use this when you need to submit a new WhatsApp template to Meta for approval after checking channel publish_readiness. Do not use it to inspect or send an existing template; explicit confirmation is required.",
         inputSchema: {
-            body: z.record(z.string(), z.unknown()),
+            body: z
+                .record(z.string(), z.unknown())
+                .describe("Template submission body including a dedicated WhatsApp channel_id, name, category, language, and components accepted by POST /templates."),
+            confirmation_token: z
+                .string()
+                .optional()
+                .describe("Required when write mode is enabled: create_template"),
         },
         annotations: {
             readOnlyHint: false,
@@ -1556,33 +1590,33 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ body }) => {
-        const blocked = await requireWrite("wabery_create_template");
+    }, async ({ body, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_create_template", confirmation_token, "create_template");
         if (blocked)
             return blocked;
         return apiResult(client.post("/templates", body));
     });
     registerTool("wabery_wait_template", {
         title: "Wait for WhatsApp template approval",
-        description: "Poll a WhatsApp template until Meta reports APPROVED. Fails if Meta rejects/disables it or if timeout_seconds elapses.",
+        description: "Use this when you need to poll Meta for a template_id from wabery_list_templates until APPROVED or timeout. This repeatedly refreshes Wabery's cached provider status; do not use it for a single cached read.",
         inputSchema: {
             template_id: z.string().min(1),
             timeout_seconds: z.number().int().min(1).max(86_400).optional(),
             interval_seconds: z.number().int().min(1).max(300).optional(),
         },
         annotations: {
-            readOnlyHint: true,
+            readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
         },
     }, async ({ template_id, timeout_seconds, interval_seconds }) => jsonResult(await waitUntilTemplateApproved(client, template_id, {
         timeoutMs: (timeout_seconds ?? 86_400) * 1000,
         intervalMs: (interval_seconds ?? 60) * 1000,
     })));
     registerTool("wabery_send_flow", {
-        title: "Send Wabery flow",
-        description: "Send a published WhatsApp Flow to an enrolled contact, existing conversation, or phone number. Returns flow_token and dispatch info.",
+        title: "Send WhatsApp Flow",
+        description: "Use this when you need to send one published WhatsApp Flow using flow_id and channel_id from list tools plus exactly one controlled contact_id, conversation_id, or phone number. Do not use wabery_send_message for a Flow; explicit confirmation is required.",
         inputSchema: {
             flow_id: z.string().min(1),
             channel_id: z.string().min(1),
@@ -1595,6 +1629,10 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             footer_text: z.string().max(60).optional(),
             first_screen: z.string().optional(),
             screen_data: z.record(z.string(), z.unknown()).optional(),
+            confirmation_token: z
+                .string()
+                .optional()
+                .describe("Required when write mode is enabled: send_flow:<flow_id>"),
         },
         annotations: {
             readOnlyHint: false,
@@ -1602,15 +1640,15 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ flow_id, ...body }) => {
-        const blocked = await requireWrite("wabery_send_flow");
+    }, async ({ flow_id, confirmation_token, ...body }) => {
+        const blocked = await requireWrite("wabery_send_flow", confirmation_token, `send_flow:${flow_id}`);
         if (blocked)
             return blocked;
         return apiResult(client.post(`/flows/${flow_id}/send`, body));
     });
     registerTool("wabery_list_submissions", {
         title: "List Wabery submissions",
-        description: "List completed WhatsApp Flow submissions for the organization.",
+        description: "Use this when you need completed WhatsApp Flow submissions, optionally filtered by project agent_id or flow_id from wabery_list_flows.",
         inputSchema: {
             agent_id: z.string().optional(),
             flow_id: z.string().optional(),
@@ -1626,7 +1664,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async (query) => jsonResult(await client.get("/submissions", query)));
     registerTool("wabery_list_dispatches", {
         title: "List Wabery dispatches",
-        description: "List sent flow dispatches. Use this to inspect flow_token status across sends.",
+        description: "Use this when you need sent WhatsApp Flow dispatches and flow_token values, optionally filtered by flow_id or contact_id. Use wabery_get_dispatch for one token.",
         inputSchema: {
             flow_id: z.string().optional(),
             contact_id: z.string().optional(),
@@ -1643,7 +1681,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async (query) => jsonResult(await client.get("/dispatches", query)));
     registerTool("wabery_get_dispatch", {
         title: "Get Wabery dispatch",
-        description: "Get one flow dispatch by flow_token.",
+        description: "Use this when you need provider and completion status for one WhatsApp Flow dispatch by flow_token returned by wabery_send_flow or wabery_list_dispatches.",
         inputSchema: {
             flow_token: z.string().min(1),
         },
@@ -1657,7 +1695,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     // ─── Hosted functions (serverless logic the agent authors) ───────────
     registerTool("wabery_list_functions", {
         title: "List hosted functions",
-        description: "List the project's hosted functions (serverless handlers that run on send/tool triggers).",
+        description: "Use this when you need hosted function_id values, deployment state, or exposure settings for the selected project before get, deploy, test, invoke, update, or delete operations.",
         inputSchema: {},
         annotations: {
             readOnlyHint: true,
@@ -1668,7 +1706,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async () => jsonResult(await client.get("/functions")));
     registerTool("wabery_get_function", {
         title: "Get a hosted function",
-        description: "Fetch one hosted function including its current source.",
+        description: "Use this when you need metadata and current source for a function_id from wabery_list_functions. Do not use it to execute the function.",
         inputSchema: { function_id: z.string().min(1) },
         annotations: {
             readOnlyHint: true,
@@ -1679,7 +1717,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ function_id }) => jsonResult(await client.get(`/functions/${function_id}`)));
     registerTool("wabery_create_function", {
         title: "Create a hosted function",
-        description: "Create a hosted function (metadata only). Deploy source separately with wabery_deploy_function. trigger_type is an AutomationTriggerType, e.g. KEYWORD, WELCOME, ANY_MESSAGE.",
+        description: "Use this when you need a new hosted-function record without deploying source. trigger_type accepts values such as KEYWORD, WELCOME, or ANY_MESSAGE; use wabery_deploy_function next.",
         inputSchema: {
             slug: z
                 .string()
@@ -1708,7 +1746,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_deploy_function", {
         title: "Deploy a hosted function",
-        description: "Bundle and upload TypeScript source for a hosted function. Returns { status, version_id?, diagnostics? } — read diagnostics on error, fix, and redeploy.",
+        description: "Use this when you need to bundle and overwrite the active TypeScript deployment for a function_id from wabery_list_functions. Do not use it to execute code; use test or invoke after reviewing diagnostics.",
         inputSchema: {
             function_id: z.string().min(1),
             source: z.string().min(1),
@@ -1719,9 +1757,9 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
         },
     }, async ({ function_id, source, confirmation_token }) => {
         const blocked = await requireWrite("wabery_deploy_function", confirmation_token, "deploy_function");
@@ -1731,7 +1769,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_test_function", {
         title: "Test a hosted function",
-        description: "Invoke a hosted function with a sample message event (no real send) and return its result plus logs.",
+        description: "Use this when you need to execute a function_id with a synthetic message event and inspect its result and logs. Do not use it as a side-effect-free preview: function code can persist data or call external APIs; use wabery_invoke_function for a real structured tool call.",
         inputSchema: {
             function_id: z.string().min(1),
             text: z.string().max(4000).optional(),
@@ -1742,9 +1780,9 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
         },
     }, async ({ function_id, text, confirmation_token }) => {
         const blocked = await requireWrite("wabery_test_function", confirmation_token, "test_function");
@@ -1754,7 +1792,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_tail_function_logs", {
         title: "Tail hosted function logs",
-        description: "Recent invocations of a hosted function (status, cpu, error, captured logs) for debugging.",
+        description: "Use this when you need recent invocation status, CPU, errors, or captured logs for a function_id from wabery_list_functions. This does not execute the function.",
         inputSchema: { function_id: z.string().min(1) },
         annotations: {
             readOnlyHint: true,
@@ -1765,7 +1803,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ function_id }) => jsonResult(await client.get(`/functions/${function_id}/logs`)));
     registerTool("wabery_delete_function", {
         title: "Delete a hosted function",
-        description: "Delete a hosted function and its deployed Worker.",
+        description: "Use this when you need to permanently delete a function_id from wabery_list_functions and its deployed Worker. Do not use update to simulate deletion.",
         inputSchema: {
             function_id: z.string().min(1),
             confirmation_token: z
@@ -1777,7 +1815,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             readOnlyHint: false,
             destructiveHint: true,
             idempotentHint: true,
-            openWorldHint: false,
+            openWorldHint: true,
         },
     }, async ({ function_id, confirmation_token }) => {
         const blocked = await requireWrite("wabery_delete_function", confirmation_token, "delete_function");
@@ -1787,7 +1825,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_update_function", {
         title: "Update a hosted function",
-        description: "Update a hosted function: rename, set expose_as_mcp_tool (make it callable by external agents), toggle is_active, or set input_schema (the tool schema used for agent/MCP calls).",
+        description: "Use this when you need to overwrite metadata for a function_id from wabery_list_functions: name, expose_as_mcp_tool, is_active, or input_schema. Do not use it to deploy source or invoke code.",
         inputSchema: {
             function_id: z.string().min(1),
             name: z.string().min(1).max(120).optional(),
@@ -1801,7 +1839,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: false,
         },
@@ -1814,7 +1852,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     });
     registerTool("wabery_invoke_function", {
         title: "Invoke a hosted function as a tool",
-        description: "Call a hosted function as a tool (mcp_call) with structured arguments and return its result. Optionally target a specific contact.",
+        description: "Use this when you need a real structured mcp_call to an exposed function_id from wabery_list_functions, optionally with contact_id from wabery_list_contacts. Do not use it for synthetic testing; arbitrary function code can persist data, call APIs, or send messages.",
         inputSchema: {
             function_id: z.string().min(1),
             arguments: z.record(z.string(), z.unknown()).optional(),
@@ -1826,8 +1864,8 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
+            destructiveHint: true,
+            idempotentHint: false,
             openWorldHint: true,
         },
     }, async ({ function_id, arguments: args, contact_id, confirmation_token, }) => {