Document new triage tools and external summary model in README

README.md

@@ -257,12 +257,20 @@ General:
 
 - list_accounts
 
-Email:
+Email (listing, reading, and triage):
 
 - list_folders
 - search_messages
 - get_new_messages
 - sync_seen
+- get_unread_summary
+- list_unread_emails
+- get_email
+- summarize_email
+- get_thread
+
+Email (actions):
+
 - mark_as_read
 - flag_message
 - move_message
@@ -270,16 +278,24 @@ Email:
 - apply_label
 - remove_label
 - list_labels
-- get_unread_summary
+
+Email (send/reply/forward):
+
 - send_email
 - reply_to_message
 - forward_message
 - save_draft
+- schedule_send
+
+Attachments and threads:
+
 - list_attachments
 - download_attachment
 - search_attachments
-- schedule_send
 - export_conversation
+
+Legal-specific:
+
 - conflict_check_search
 - get_triage_config
 
@@ -291,3 +307,92 @@ Notes:
 - For production:
   - Always set API_KEY.
   - Use HTTPS and secure IMAP/SMTP settings.
+
+## New tools for efficient email triage
+
+These tools are designed to help LLMs triage many emails without overloading the context window.
+
+- list_unread_emails
+  - Purpose: List unread emails with minimal content (metadata + short snippet).
+  - Use this first when scanning a large inbox.
+  - Parameters:
+    - account: optional (uses default if omitted)
+    - folder: IMAP folder (default: INBOX)
+    - max_results: max emails to return (default: 50)
+    - include_body: if true, include full body (default: false)
+    - since: optional SINCE date, e.g. "01-Jan-2024"
+  - Returns:
+    - For each email: uid, subject, from, to, date, flags, snippet, has_attachments
+    - Plus total_unread and returned counts
+
+- get_email
+  - Purpose: Fetch the full content of a single email by UID.
+  - Use this after scanning with list_unread_emails or get_unread_summary.
+  - Parameters:
+    - folder: IMAP folder (default: INBOX)
+    - uid: message UID
+    - include_html: if true, include HTML body (default: false)
+  - Returns:
+    - subject, from, to, cc, date, body_plain, attachments
+    - body_html only if include_html=true
+
+- summarize_email
+  - Purpose: Get a concise summary of an email via an external model (if configured), instead of loading the full text into the main LLM context.
+  - Use this when you need to understand an email quickly without reading its full content.
+  - Parameters:
+    - folder: IMAP folder (default: INBOX)
+    - uid: message UID
+    - max_length: max summary length in words (default: 150)
+  - Behavior:
+    - If external summary model is configured, it sends the email to that model and returns its summary.
+    - If not configured or the call fails, it falls back to the first N words of the email.
+  - Returns:
+    - uid, subject, from, date, summary (including attachment note if present)
+
+- get_thread
+  - Purpose: Get a concise view of the conversation thread for a given email.
+  - Use this to understand context without loading all message bodies.
+  - Parameters:
+    - folder: IMAP folder (default: INBOX)
+    - uid: message UID to use as the anchor
+    - max_messages: max thread messages to return (default: 10)
+  - Returns:
+    - subject, participants, message_count
+    - For each message: uid, from, date, subject, snippet (short)
+
+Suggested LLM workflow:
+
+1) Call list_unread_emails(max_results=100) to scan metadata.
+2) For interesting emails:
+   - Use summarize_email(uid) for a quick summary, or
+   - Use get_email(uid) if you need the full content.
+3) For email threads:
+   - Use get_thread(uid) to see the conversation outline.
+   - Then selectively call get_email on key messages.
+
+## External summary model configuration
+
+Optional: configure an external LLM to summarize emails via summarize_email.
+This keeps long emails out of the main model’s context.
+
+Environment variables:
+
+- EXTERNAL_SUMMARY_MODEL_ENDPOINT:
+  - OpenAI-compatible /v1/chat/completions endpoint.
+  - Example: http://localhost:8080/v1
+- EXTERNAL_SUMMARY_MODEL_API_KEY:
+  - API key for the external model.
+- EXTERNAL_SUMMARY_MODEL_NAME:
+  - Model name (default: gpt-4o-mini).
+- EXTERNAL_SUMMARY_MAX_TOKENS:
+  - Max tokens for each summary (default: 400).
+
+Example (docker run):
+
+-e EXTERNAL_SUMMARY_MODEL_ENDPOINT='http://localhost:8080/v1' \
+-e EXTERNAL_SUMMARY_MODEL_API_KEY='your_summary_model_key' \
+-e EXTERNAL_SUMMARY_MODEL_NAME='gpt-4o-mini' \
+-e EXTERNAL_SUMMARY_MAX_TOKENS='400'
+
+If these are not set:
+- The summarize_email tool will still work, but will fall back to returning the first N words of the email instead of using an external model.