refactor: edit HITL prompts to be more expressive

surfsense_backend/app/agents/new_chat/tools/google_drive/create_file.py

@@ -32,13 +32,15 @@ def create_create_google_drive_file_tool(
         """Create a new Google Doc or Google Sheet in Google Drive.
 
         Use this tool when the user explicitly asks to create a new document
-        or spreadsheet in Google Drive.
+        or spreadsheet in Google Drive. The user MUST specify a topic before
+        you call this tool. If the request is vague, ask what the file should
+        contain. Never call this tool without a clear topic from the user.
 
         Args:
-            name: The file name (without extension).
+            name: The file name (without extension). Infer from the user's request.
             file_type: Either "google_doc" or "google_sheet".
-            content: Optional initial content. For google_doc, provide markdown text.
-                     For google_sheet, provide CSV-formatted text.
+            content: Optional initial content. Generate from the user's topic.
+                     For google_doc, provide markdown text. For google_sheet, provide CSV-formatted text.
 
         Returns:
             Dictionary with:
@@ -55,8 +57,8 @@ def create_create_google_drive_file_tool(
               Inform the user they need to re-authenticate and do NOT retry the action.
 
         Examples:
-            - "Create a Google Doc called 'Meeting Notes'"
-            - "Create a spreadsheet named 'Budget 2026' with some sample data"
+            - "Create a Google Doc with today's meeting notes"
+            - "Create a spreadsheet for the 2026 budget"
         """
         logger.info(
             f"create_google_drive_file called: name='{name}', type='{file_type}'"

surfsense_backend/app/agents/new_chat/tools/linear/create_issue.py

@@ -38,11 +38,13 @@ def create_create_linear_issue_tool(
         """Create a new issue in Linear.
 
         Use this tool when the user explicitly asks to create, add, or file
-        a new issue / ticket / task in Linear.
+        a new issue / ticket / task in Linear. The user MUST describe the issue
+        before you call this tool. If the request is vague, ask what the issue
+        should be about. Never call this tool without a clear topic from the user.
 
         Args:
-            title: Short, descriptive issue title.
-            description: Optional markdown body for the issue.
+            title: Short, descriptive issue title. Infer from the user's request.
+            description: Optional markdown body for the issue. Generate from context.
 
         Returns:
             Dictionary with:
@@ -57,9 +59,9 @@ def create_create_linear_issue_tool(
             and move on. Do NOT retry, troubleshoot, or suggest alternatives.
 
         Examples:
-            - "Create a Linear issue titled 'Fix login bug'"
-            - "Add a ticket for the payment timeout problem"
-            - "File an issue about the broken search feature"
+            - "Create a Linear issue for the login bug"
+            - "File a ticket about the payment timeout problem"
+            - "Add an issue for the broken search feature"
         """
         logger.info(f"create_linear_issue called: title='{title}'")
 

surfsense_backend/app/agents/new_chat/tools/notion/create_page.py

@@ -33,17 +33,21 @@ def create_create_notion_page_tool(
     @tool
     async def create_notion_page(
         title: str,
-        content: str,
+        content: str | None = None,
     ) -> dict[str, Any]:
         """Create a new page in Notion with the given title and content.
 
         Use this tool when the user asks you to create, save, or publish
         something to Notion. The page will be created in the user's
-        configured Notion workspace.
+        configured Notion workspace. The user MUST specify a topic before you
+        call this tool. If the request does not contain a topic (e.g. "create a
+        notion page"), ask what the page should be about. Never call this tool
+        without a clear topic from the user.
 
         Args:
             title: The title of the Notion page.
-            content: The markdown content for the page body (supports headings, lists, paragraphs).
+            content: Optional markdown content for the page body (supports headings, lists, paragraphs).
+                     Generate this yourself based on the user's topic.
 
         Returns:
             Dictionary with:
@@ -58,8 +62,8 @@ def create_create_notion_page_tool(
             and move on. Do NOT troubleshoot or suggest alternatives.
 
         Examples:
-            - "Create a Notion page titled 'Meeting Notes' with content 'Discussed project timeline'"
-            - "Save this to Notion with title 'Research Summary'"
+            - "Create a Notion page about our Q2 roadmap"
+            - "Save a summary of today's discussion to Notion"
         """
         logger.info(f"create_notion_page called: title='{title}'")
 

surfsense_backend/app/agents/new_chat/tools/notion/update_page.py

@@ -33,16 +33,19 @@ def create_update_notion_page_tool(
     @tool
     async def update_notion_page(
         page_title: str,
-        content: str,
+        content: str | None = None,
     ) -> dict[str, Any]:
         """Update an existing Notion page by appending new content.
 
         Use this tool when the user asks you to add content to, modify, or update
         a Notion page. The new content will be appended to the existing page content.
+        The user MUST specify what to add before you call this tool. If the
+        request is vague, ask what content they want added.
 
         Args:
             page_title: The title of the Notion page to update.
-            content: The markdown content to append to the page body (supports headings, lists, paragraphs).
+            content: Optional markdown content to append to the page body (supports headings, lists, paragraphs).
+                     Generate this yourself based on the user's request.
 
         Returns:
             Dictionary with:
@@ -62,8 +65,8 @@ def create_update_notion_page_tool(
               ask the user to verify the page title or check if it's been indexed.
 
         Examples:
-            - "Add 'New meeting notes from today' to the 'Meeting Notes' Notion page"
-            - "Append the following to the 'Project Plan' Notion page: '# Status Update\n\nCompleted phase 1'"
+            - "Add today's meeting notes to the 'Meeting Notes' Notion page"
+            - "Update the 'Project Plan' page with a status update on phase 1"
         """
         logger.info(
             f"update_notion_page called: page_title='{page_title}', content_length={len(content) if content else 0}"