From fac6e7e77e0f4ab889de234b1b9ef53436651b3f Mon Sep 17 00:00:00 2001
From: curo1305 <curo1305@proton.me>
Date: Tue, 19 May 2026 23:50:24 +0200
Subject: [PATCH] chore(email): sharpen tool descriptions and rename
 email_list_inbox
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename email_list_inbox → email_list_folder (works on any folder, not just inbox)
- email_list_folder / email_search: distinguish browse-by-recency vs filter-by-query
- email_move / email_delete: clarify single-email scope; point to email_bulk_action for multiple
- email_bulk_action: clarify it handles multiple emails; point to move/delete for single
- email_create_folder: remove redundant "ask user" instruction (requires_approval handles it)
- Update tests to reflect renamed tool

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/pyra/bundled_plugins/email/plugin.py | 22 +++++++++++++---------
 tests/unit/test_email_plugin.py          |  4 ++--
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/src/pyra/bundled_plugins/email/plugin.py b/src/pyra/bundled_plugins/email/plugin.py
index 4e97cdd..b7e9c83 100644
--- a/src/pyra/bundled_plugins/email/plugin.py
+++ b/src/pyra/bundled_plugins/email/plugin.py
@@ -927,8 +927,9 @@ class EmailPlugin(BasePlugin):
     def tools(self) -> list[Tool]:
         return [
             Tool(
-                "email_list_inbox",
-                "List recent emails from a folder. Returns sender, subject, date, read status.",
+                "email_list_folder",
+                "List recent emails from a folder by recency. Returns sender, subject, date, read status. "
+                "Use this to browse a folder. For filtering by sender, subject, or keyword, use email_search instead.",
                 {
                     "type": "object",
                     "properties": {
@@ -950,7 +951,7 @@ class EmailPlugin(BasePlugin):
                     "type": "object",
                     "required": ["uid"],
                     "properties": {
-                        "uid": {"type": "string", "description": "Email UID from email_list_inbox"},
+                        "uid": {"type": "string", "description": "Email UID from email_list_folder or email_search"},
                         "folder": {"type": "string", "default": "INBOX"},
                     },
                 },
@@ -1007,8 +1008,9 @@ class EmailPlugin(BasePlugin):
             ),
             Tool(
                 "email_move",
-                "Move an email to another folder. Returns an error message if the folder "
-                "does not exist — call email_create_folder first (with user approval).",
+                "Move a single email to another folder. Returns an error message if the folder "
+                "does not exist — call email_create_folder first (with user approval). "
+                "For multiple emails, use email_bulk_action.",
                 {
                     "type": "object",
                     "required": ["uid", "to_folder"],
@@ -1023,7 +1025,7 @@ class EmailPlugin(BasePlugin):
             ),
             Tool(
                 "email_delete",
-                "Move an email to the Trash.",
+                "Move a single email to the Trash. For multiple emails, use email_bulk_action.",
                 {
                     "type": "object",
                     "required": ["uid"],
@@ -1052,8 +1054,9 @@ class EmailPlugin(BasePlugin):
             ),
             Tool(
                 "email_search",
-                "Search emails by a natural language query. Examples: "
-                "'from:boss@company.com', 'unread invoices', 'subject:meeting'.",
+                "Search emails by filtering on sender, subject, or keyword. Examples: "
+                "'from:boss@company.com', 'unread invoices', 'subject:meeting'. "
+                "For browsing a folder by recency without a filter, use email_list_folder instead.",
                 {
                     "type": "object",
                     "required": ["query"],
@@ -1075,7 +1078,7 @@ class EmailPlugin(BasePlugin):
             ),
             Tool(
                 "email_create_folder",
-                "Create a new email folder. Always ask the user for confirmation before calling.",
+                "Create a new email folder.",
                 {
                     "type": "object",
                     "required": ["name"],
@@ -1142,6 +1145,7 @@ class EmailPlugin(BasePlugin):
             Tool(
                 "email_bulk_action",
                 "Apply an action to all emails matching a search query. "
+                "Use for multiple emails; for a single email use email_move or email_delete. "
                 "Actions: 'delete', 'mark_read', 'move:<folder_name>'.",
                 {
                     "type": "object",
diff --git a/tests/unit/test_email_plugin.py b/tests/unit/test_email_plugin.py
index eac5ee7..fedc138 100644
--- a/tests/unit/test_email_plugin.py
+++ b/tests/unit/test_email_plugin.py
@@ -351,7 +351,7 @@ def test_plugin_exposes_16_tools():
     assert len(tools) == 16
 
     expected = {
-        "email_list_inbox", "email_read", "email_send", "email_reply",
+        "email_list_folder", "email_read", "email_send", "email_reply",
         "email_forward", "email_move", "email_delete", "email_mark_read",
         "email_search", "email_list_folders", "email_create_folder",
         "email_inbox_summary", "email_list_rules", "email_create_rule",
@@ -378,7 +378,7 @@ def test_read_tools_no_approval():
     plugin.on_load(lambda _: None)
     tools = {t.name: t for t in plugin.tools()}
 
-    for name in ["email_list_inbox", "email_read", "email_mark_read",
+    for name in ["email_list_folder", "email_read", "email_mark_read",
                  "email_search", "email_list_folders", "email_inbox_summary",
                  "email_list_rules"]:
         assert not tools[name].requires_approval, f"{name} should NOT require approval"