From 0b66aa6f8a428ce6e5cc6a81ccf83831f99db062 Mon Sep 17 00:00:00 2001
From: Henry Park <henrypark133@gmail.com>
Date: Fri, 27 Mar 2026 14:51:35 -0700
Subject: [PATCH] Clarify search and message tool edge cases

---
 src/tools/builtin/extension_tools.rs | 9 +++++----
 src/tools/builtin/message.rs         | 7 +++++--
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/src/tools/builtin/extension_tools.rs b/src/tools/builtin/extension_tools.rs
index ea29fae8..6d6efa4b 100644
--- a/src/tools/builtin/extension_tools.rs
+++ b/src/tools/builtin/extension_tools.rs
@@ -32,9 +32,10 @@ impl Tool for ToolSearchTool {
     fn description(&self) -> &str {
         "Search for available extensions to add new capabilities. Extensions include \
          channels (Telegram, Slack, Discord — connect messaging platforms so IronClaw can \
-         receive and reply there), tools, and MCP servers. Install and activate channels here; \
-         use the `message` tool for proactive outbound sends. Use discover:true to search online \
-         if the built-in registry has no results."
+         receive and reply there), tools, and MCP servers. Use `tool_install` and \
+         `tool_activate` to install and enable channels; use the `message` tool for proactive \
+         outbound sends. Use discover:true to search online if the built-in registry has no \
+         results."
     }
 
     fn parameters_schema(&self) -> serde_json::Value {
@@ -643,7 +644,7 @@ mod tests {
         };
 
         let description = tool.description();
-        assert!(description.contains("Install and activate channels here"));
+        assert!(description.contains("Use `tool_install` and `tool_activate`"));
         assert!(description.contains("use the `message` tool for proactive outbound sends"));
     }
 
diff --git a/src/tools/builtin/message.rs b/src/tools/builtin/message.rs
index 3868a8de..36e21ff6 100644
--- a/src/tools/builtin/message.rs
+++ b/src/tools/builtin/message.rs
@@ -185,9 +185,11 @@ impl Tool for MessageTool {
          active conversation; use this tool for proactive notifications, routine/background \
          follow-ups, attachments, or sending to a different channel/recipient. If channel/target \
          are omitted, reuses the current conversation's channel and sender/group when available. \
+         If you provide `target` without `channel` and no scoped channel can be resolved, the \
+         message may be broadcast across connected channels instead of sent to just one. \
          Supports file attachments: first download the file with the http tool using save_to \
-         (e.g., http GET https://picsum.photos/800/600 save_to=/tmp/photo.jpg), then pass \
-         the file path in the attachments array. Images are sent as photos on Telegram. \
+         (e.g., http GET https://picsum.photos/800/600 save_to=/tmp/photo.jpg), then pass the \
+         file path in the attachments array. Images are sent as photos on Telegram. \
          - Signal: target accepts E.164 (+1234567890) or group ID \
          - Telegram: target accepts username or chat ID \
          - Slack: target accepts channel (#general) or user ID"
@@ -457,6 +459,7 @@ mod tests {
         assert!(!description.is_empty());
         assert!(description.contains("Use normal assistant output to reply"));
         assert!(description.contains("proactive notifications"));
+        assert!(description.contains("provide `target` without `channel`"));
     }
 
     #[test]