feat: enforce single invocation for tool actions across various services

- Added a guideline to ensure that each tool (Gmail, Google Calendar, Google Drive, Linear, Notion) is called only once per user request.
- Updated documentation to clarify that the system will automatically select the most relevant match when multiple items share the same title or subject, enhancing user experience and preventing redundant calls.

surfsense_backend/app/agents/new_chat/tools/gmail/trash_email.py

@@ -47,6 +47,11 @@ def create_trash_gmail_email_tool(
               to verify the email subject or check if it has been indexed.
             - If status is "insufficient_permissions", the connector lacks the required OAuth scope.
               Inform the user they need to re-authenticate and do NOT retry this tool.
+            - ONLY call this tool ONCE per user request. The system automatically picks the
+              most relevant match when multiple emails share the same subject. The user will
+              see the exact email details (sender, date) in the approval card and can reject
+              if it is not the right one. Do NOT call this tool multiple times for the same
+              email subject.
 
         Examples:
             - "Delete the email about 'Meeting Cancelled'"

surfsense_backend/app/agents/new_chat/tools/gmail/update_draft.py

@@ -63,6 +63,10 @@ def create_update_gmail_draft_tool(
               Respond with a brief acknowledgment and do NOT retry or suggest alternatives.
             - If status is "not_found", relay the exact message to the user and ask them
               to verify the draft subject or check if it has been indexed.
+            - ONLY call this tool ONCE per user request. The system automatically picks the
+              most relevant match when multiple drafts share the same subject. The user will
+              see the exact draft details in the approval card and can reject if it is not
+              the right one. Do NOT call this tool multiple times for the same draft subject.
             - If status is "insufficient_permissions", the connector lacks the required OAuth scope.
               Inform the user they need to re-authenticate and do NOT retry the action.
 

surfsense_backend/app/agents/new_chat/tools/google_calendar/delete_event.py

@@ -46,6 +46,11 @@ def create_delete_calendar_event_tool(
               acknowledgment and do NOT retry or suggest alternatives.
             - If status is "not_found", relay the exact message to the user and ask them
               to verify the event name or check if it has been indexed.
+            - ONLY call this tool ONCE per user request. The system automatically picks the
+              most relevant match when multiple events share the same name. The user will
+              see the exact event details (date, time, location) in the approval card and
+              can reject if it is not the right one. Do NOT call this tool multiple times
+              for the same event name.
 
         Examples:
             - "Delete the team standup event"

surfsense_backend/app/agents/new_chat/tools/google_calendar/update_event.py

@@ -54,6 +54,11 @@ def create_update_calendar_event_tool(
               acknowledgment and do NOT retry or suggest alternatives.
             - If status is "not_found", relay the exact message to the user and ask them
               to verify the event name or check if it has been indexed.
+            - ONLY call this tool ONCE per user request. The system automatically picks the
+              most relevant match when multiple events share the same name. The user will
+              see the exact event details (date, time, location) in the approval card and
+              can reject if it is not the right one. Do NOT call this tool multiple times
+              for the same event name.
 
         Examples:
             - "Reschedule the team standup to 3pm"

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

@@ -47,6 +47,10 @@ def create_delete_google_drive_file_tool(
               to verify the file name or check if it has been indexed.
             - If status is "insufficient_permissions", the connector lacks the required OAuth scope.
               Inform the user they need to re-authenticate and do NOT retry this tool.
+            - ONLY call this tool ONCE per user request. The system automatically picks the
+              most relevant match when multiple files share the same name. The user will
+              see the exact file details in the approval card and can reject if it is not
+              the right one. Do NOT call this tool multiple times for the same file name.
 
         Examples:
             - "Delete the 'Meeting Notes' file from Google Drive"

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

@@ -64,6 +64,10 @@ def create_delete_linear_issue_tool(
             - If status is "not_found", inform the user conversationally using the exact message
               provided. Do NOT treat this as an error. Simply relay the message and ask the user
               to verify the issue title or identifier, or check if it has been indexed.
+            - ONLY call this tool ONCE per user request. The system automatically picks the
+              most relevant match when multiple issues share the same title. The user will
+              see the exact issue details in the approval card and can reject if it is not
+              the right one. Do NOT call this tool multiple times for the same issue reference.
 
         Examples:
             - "Delete the 'Fix login bug' Linear issue"

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

@@ -78,6 +78,10 @@ def create_update_linear_issue_tool(
             - If status is "not_found", inform the user conversationally using the exact message
               provided. Do NOT treat this as an error. Simply relay the message and ask the user
               to verify the issue title or identifier, or check if it has been indexed.
+            - ONLY call this tool ONCE per user request. The system automatically picks the
+              most relevant match when multiple issues share the same title. The user will
+              see the exact issue details in the approval card and can reject if it is not
+              the right one. Do NOT call this tool multiple times for the same issue reference.
 
         Examples:
             - "Mark the 'Fix login bug' issue as done"

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

@@ -54,6 +54,11 @@ def create_delete_notion_page_tool(
             - message: Success or error message
             - deleted_from_kb: Whether the page was also removed from knowledge base (if success)
 
+            ONLY call this tool ONCE per user request. The system automatically picks the
+            most relevant match when multiple pages share the same title. The user will
+            see the exact page details in the approval card and can reject if it is not
+            the right one. Do NOT call this tool multiple times for the same page title.
+
         Examples:
             - "Delete the 'Meeting Notes' Notion page"
             - "Remove the 'Old Project Plan' Notion page"

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

@@ -63,6 +63,10 @@ def create_update_notion_page_tool(
               Example: "I couldn't find the page '[page_title]' in your indexed Notion pages. [message details]"
               Do NOT treat this as an error. Do NOT invent information. Simply relay the message and
               ask the user to verify the page title or check if it's been indexed.
+            - ONLY call this tool ONCE per user request. The system automatically picks the
+              most relevant match when multiple pages share the same title. The user will
+              see the exact page details in the approval card and can reject if it is not
+              the right one. Do NOT call this tool multiple times for the same page title.
 
         Examples:
             - "Add today's meeting notes to the 'Meeting Notes' Notion page"

surfsense_backend/app/services/gmail/tool_metadata_service.py

@@ -436,6 +436,8 @@ class GmailToolMetadataService:
                     ),
                 )
             )
+            .order_by(Document.updated_at.desc().nullslast())
+            .limit(1)
         )
         row = result.first()
         if row:

surfsense_backend/app/services/google_calendar/tool_metadata_service.py

@@ -396,6 +396,8 @@ class GoogleCalendarToolMetadataService:
                     ),
                 )
             )
+            .order_by(Document.updated_at.desc().nullslast())
+            .limit(1)
         )
         row = result.first()
         if row:

surfsense_backend/app/services/google_drive/tool_metadata_service.py

@@ -111,6 +111,8 @@ class GoogleDriveToolMetadataService:
                     SearchSourceConnector.user_id == user_id,
                 )
             )
+            .order_by(Document.updated_at.desc().nullslast())
+            .limit(1)
         )
         document = result.scalars().first()
 

surfsense_backend/app/services/linear/tool_metadata_service.py

@@ -358,6 +358,7 @@ class LinearToolMetadataService:
                     ),
                 )
             )
+            .order_by(Document.updated_at.desc().nullslast())
             .limit(1)
         )
         return result.scalars().first()

surfsense_backend/app/services/notion/tool_metadata_service.py

@@ -135,6 +135,8 @@ class NotionToolMetadataService:
                     SearchSourceConnector.user_id == user_id,
                 )
             )
+            .order_by(Document.updated_at.desc().nullslast())
+            .limit(1)
         )
         document = result.scalars().first()