diff --git a/hive-matrix-mcp/src/bin/mcp.rs b/hive-matrix-mcp/src/bin/mcp.rs
index 88fe5407..9adb8ff6 100644
--- a/hive-matrix-mcp/src/bin/mcp.rs
+++ b/hive-matrix-mcp/src/bin/mcp.rs
@@ -567,7 +567,18 @@ impl MatrixBridge {
         room with `join_room`. Room references accept ids (!abc:server) \
         or aliases (#name:server); user references use @user:server. Every \
         tool takes an optional `account` (a name from the agent's matrix \
-        accounts) — omit it to act as the primary account.")]
+        accounts) — omit it to act as the primary account. \
+        `send_file` uploads a local file and posts it as a room attachment \
+        (MIME inferred from extension, 50 MiB cap); `send_file` is rejected \
+        with a hint if the room has unread messages — read_room then mark_read \
+        first. `download_file` downloads an attachment from a message event \
+        to a local file and returns its path; pair with `read_room` which \
+        surfaces attachments as `[file: name]`, `[image: name]`, \
+        `[audio: name]`, `[video: name]` markers. \
+        IMPORTANT: `send_message`, `send_dm`, `send_file`, `send_reply` are \
+        all rejected if the room has unread messages — always call `read_room` \
+        then `mark_read` on the latest event before sending to a room you \
+        haven't read yet.")]
 impl ServerHandler for MatrixBridge {}
 
 #[tokio::main]