A Django-based conversational AI platform with Gmail integration, memory management, and multi-modal chat capabilities supporting agent, coaching, and conversational modes
Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
The LifeLine server exposes 3 Gmail-related tools with basic schemas and descriptions. All tools have non-empty descriptions and visible input schemas, but descriptions are generic and lack actionable guidance. Parameters are documented but lack format constraints, enums, or range specifications. Output schemas are not documented. Error handling is minimal, tools return generic error messages rather than recovery guidance. The tools themselves are well-named (search_emails, read_email, send_email) and avoid ambiguity, but lack the depth and LLM-optimization needed for production agent use. This is a C-grade server, functional but requiring significant improvements for reliable agent integration.
Tools (3)
read_emailread onlyauthsource verified67/100
Reads the full content of a specific email by its message ID.
search_emailsread onlyauthsource verified70/100
Searches for emails in the user's Gmail account based on a query.
Output schemas are not documented. LLMs cannot infer what fields search_emails, read_email, and send_email return, making downstream tool composition and data extraction error-prone.
Parameter descriptions lack format constraints and enums. 'query' in search_emails has no guidance on length, syntax, or valid operators. 'to' in send_email is an array but no max length or validation rules are documented.
Error handling is generic and non-actionable. Both read_email and send_email return {'error': '...'} with no guidance on what the LLM should do next (retry, ask user, use alternative tool). Per pattern:recovery-guide, errors should include recovery hints.
read_emailsend_emailsearch_emails
MEDIUM
Recommendations
Document the output schema for each tool. For search_emails, specify: [{message_id: string, from: string, subject: string, snippet: string, date: string}, ...], total_count: int, next_page_token?: string. For read_email, specify: {message_id: string, from: string, to: string[], cc?: string[], subject: string, body: string, date: string, attachments?: [{filename: string, mime_type: string, size: int}]}. For send_email, specify: {message_id: string, timestamp: string}.
Add format constraints to parameters. search_emails query should note: 'Gmail search syntax (e.g., from:user@example.com, subject:report, is:unread). See https://support.google.com/mail/answer/7190 for operators.' max_results should specify: '1-100 (default 5). Note: returning >50 results may exceed context window; use pagination if expecting large result sets.' send_email's to/cc/bcc should specify: 'Valid email addresses; max 50 recipients per field.'
Expand tool descriptions to 150-250 chars with WHEN guidance. search_emails: 'Search Gmail by keywords, sender, date, or status. Use when the user wants to find specific emails. Returns subject, sender, preview; call read_email to get full message body.' read_email: 'Retrieve the full content of an email by message ID (obtained from search_emails). Use when the user wants to read, forward, or reply to a specific email.' send_email: 'Send a new email from the user's account. Use when composing and sending messages. Requires subject and body; cc/bcc optional. Returns message ID.'
Add pagination to search_emails. Change signature to: search_emails(query: str, max_results: int = 20, page_token?: str). Return {results: [...], total_count: int, next_page_token?: str}. Document: 'Pagination required for large result sets. If total_count > max_results, use next_page_token to fetch subsequent pages.'
search_emails lacks pagination. The max_results=5 default suggests unbounded result sets are possible, but no total_count, next_cursor, or offset mechanism is documented. Large result sets will blow the context window.
Tool descriptions are under 100 characters and lack context on WHEN to use each tool vs alternatives. 'Searches for emails in the user's Gmail account based on a query' does not explain when to call search_emails vs read_email, or what query format is expected.
send_email lacks confirmation or dry-run support. Sending email is an irreversible operation, agents can make mistakes. Per pattern:confirmation-request, this tool should support a dry-run or require explicit confirmation before executing.
Credentials are managed server-side (GmailMCPServer calls initialize_service), but no documentation exists explaining how OAuth tokens are stored, refreshed, or secured. Per pattern:secret-injection, audit logs must track authentication state changes.
search_emailsread_emailsend_email
Implement dry-run mode for send_email. Add optional parameter: dry_run: bool = False. When true, validate recipients and body without sending; return {validation_status: 'ok'|'error', errors?: {field: string, message: string}[]}. Document: 'When uncertain, call with dry_run=true first to validate before sending.'
Add actionable error messages. Instead of {'error': 'Gmail service not initialized...'}, return {error: 'Gmail_NotAuthenticated', message: 'Authentication required. User must complete OAuth flow.', recovery: 'Redirect to /api/auth/gmail/oauth or ask user to re-authenticate.'}. For invalid email addresses in send_email, return {error: 'Invalid_Recipients', invalid: ['badaddr@'], message: 'One or more recipient addresses are invalid.', recovery: 'Verify email addresses and retry.'}.
Document the Gmail API quota limits and rate-limit behavior. Add to send_email description: 'Rate limited by Gmail API (e.g., 500 calls/user/100s). If rate-limited, return error with Retry-After header.' Implement exponential backoff in the tool handler.
Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to signal operation safety. search_emails and read_email: {readOnlyHint: true}. send_email: {destructiveHint: true, idempotentHint: false}. This tells agents which tools are safe to call speculatively and which require careful confirmation.
Specify required permissions for each tool. Add to schema metadata: {permissions: ['Gmail.read']} for search_emails/read_email, {permissions: ['Gmail.send']} for send_email. Include in description: 'Requires Gmail.read scope' or 'Requires Gmail.send scope.'
Add parameter type validation and coercion guidance. For search_emails.max_results, if the LLM passes a string '5' or invalid value, return: {error: 'InvalidParameter', parameter: 'max_results', received: '5', expected: 'integer 1-100', recovery: 'Correct parameter type and retry.'}. This prevents silent misuse.