Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server implements 10 well-named IMAP tools with clear naming conventions (all start with action verbs: list_, search_, get_, apply_, update_, manage_, cancel_). Input schemas are visible and properly typed with JSON Schema. (2) Output schemas are not documented, the return type is a generic ToolEnvelope wrapper, but the actual fields returned by each tool are not formally specified. (3) Tool descriptions are present but minimal (average ~40 chars), lacking guidance on when to use each tool or dependencies between tools. (4) No error handling guidance visible, errors are not categorized or recovery hints provided. The tools themselves show good separation of concerns (search vs get vs list), and the implementation includes pagination support (cursor-based), which is excellent for handling large result sets. Risk levels are appropriately declared (READ_ONLY, WRITE, DESTRUCTIVE). However, the rubric expects parameter descriptions to be explicit in schemas or documentation, and visible source shows none.
Parameter descriptions completely absent from all input schemas. Visible schemas show 'type' and 'items' but no 'description' field for parameters like account_id, mailbox, query, uids, action, destination, flags, mode, new_name. The rubric requires: 'Every parameter needs a description explaining what it controls.' Without these, LLMs cannot infer parameter semantics and will guess wrong.
Output schemas not documented. Tools return a generic ToolEnvelope<T> wrapper, but the actual schema of T (ListAccountsData, SearchResultData, GetMessageData, etc.) is not visible or formally specified. The rubric requires: 'Document the output schema. LLMs need to know what fields to expect.' Without this, agents cannot plan downstream operations or extract needed data for tool chaining.
Add explicit 'description' fields to all parameter definitions in schemas. For each parameter, write a 20-50 char description: 'account_id': 'The IMAP account identifier from list_accounts()', 'mailbox': 'The IMAP mailbox name (e.g., INBOX, Drafts, Sent)', 'query': 'IMAP SEARCH query (e.g., FROM [email protected], SINCE 1-Jan-2025)', 'limit': 'Max messages to return (1-100, default 20)', 'cursor': 'Pagination cursor from previous search result (for next page)'.
Expand tool descriptions to 100-200 chars. Include WHEN to use the tool, what it returns, and any dependencies. Example for imap_get_message: 'Retrieve fully parsed message details including headers, body text, and attachments. Call imap_search_messages() first to get UIDs. Returns sender, subject, date, body, and attachment metadata.'
Document output schemas explicitly. Create a data schema reference or add a 'Returns' section to each tool. Example: 'Returns: {accounts: [{account_id, host, port, secure}], next_action: string}'. Show field names and types so agents know what to extract.
Add error recovery guidance to write operations. When imap_apply_to_messages fails on delete, return: 'Failed to delete message: <reason>. The operation may be partially complete. Use imap_get_operation() to check status. This is retryable if the error is transient.' Categorize as [retryable|user_fixable|fatal].
Implement a dry-run mode for destructive operations. Add an optional 'dry_run': bool parameter to imap_manage_mailbox and imap_apply_to_messages. When true, return what would happen without making changes. Example: 'Dry run: would delete 5 messages from Trash.' Requires explicit confirmation (dry_run=false) to execute.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Tool descriptions are minimal (average ~40 chars). Examples: 'List configured IMAP accounts' (32 chars), 'List mailboxes for an account' (30 chars), 'Get parsed message details' (26 chars). The rubric baseline expects 194 chars on average, and requires descriptions to state WHAT, WHEN, and dependencies. Current descriptions lack context for when to use each tool instead of a similar one (e.g., imap_get_message vs imap_get_message_raw) and do not mention pagination or cursor handling.
No error handling guidance visible in tool definitions. The rubric requires: 'Error responses must tell the LLM what to do next' and 'Categorize errors as retryable, user-fixable, or fatal.' No evidence of recovery hints, error categorization, or actionable error messages in source code.
Destructive operations (imap_manage_mailbox with 'delete' action, imap_apply_to_messages with 'delete' action) lack confirmation or dry-run support. The rubric requires: 'Irreversible operations should support a dry-run or confirmation step. Agents make mistakes, a confirm_before_execute pattern prevents catastrophic errors.' Deleting mailboxes or messages is irreversible and should prompt for confirmation.
No evidence of idempotency guarantees. The rubric requires: 'Make tools produce the same result on repeated calls with the same input. Agents retry on ambiguous failures, non-idempotent tools risk duplicate side effects.' Write operations (imap_apply_to_messages, imap_update_message_flags, imap_manage_mailbox) do not declare idempotency or provide mechanisms to prevent duplication on retry.
Tool annotation hints (readOnlyHint, destructiveHint, idempotentHint) are declared in the server config but not visible as annotations in the tool definitions. Modern MCP (2026-07-28) rewards tool annotations in schemas. Risk levels are declared in metadata but should also appear in tool schema annotations.
Declare idempotency support. For imap_apply_to_messages and imap_update_message_flags, document that repeated calls with the same UIDs and action are idempotent (e.g., marking message as Seen twice is safe, moving to folder twice is safe). This guides agent retry logic.
Add tool annotation hints to schema. Register each tool with readOnlyHint (for list_, get_, search_ tools) or destructiveHint (for delete, manage_mailbox actions) in the JSON Schema. Example: {'type': 'object', 'description': '...', 'x-mcp-readOnlyHint': true}.
Clarify the distinction between imap_get_message (parsed) and imap_get_message_raw (RFC822). Add to descriptions: 'imap_get_message returns human-readable parsed fields (headers, body, attachments). imap_get_message_raw returns the raw RFC822 email source. Use get_message for normal access; use get_message_raw only if you need the original MIME structure.'
Document pagination behavior. For imap_search_messages, explain cursor-based pagination: 'Returns up to `limit` messages. If more exist, response includes a `cursor` value. Pass it as the `cursor` parameter in the next call to get the next page. Cursor is valid for 24 hours.'
Add parameter constraints and examples. For 'action' enums (copy, move, delete), include in parameter description: 'Action to apply: copy (duplicate to destination), move (transfer to destination), delete (permanently remove). Requires destination mailbox for copy/move.'
Document permission/scope requirements. Each tool should declare what permissions it needs. Example: imap_list_accounts requires 'read:account_config', imap_apply_to_messages requires 'write:mailbox', imap_manage_mailbox requires 'admin:mailbox'. This enables least-privilege configurations.