Skip to main content
Glama

IMAP: Connect

imap_connect
Destructive

Connect a generic IMAP/SMTP mailbox directly from the conversation with the mailbox credentials (credentials are entered in this tool; account_connect provides a secure browser form). Nilyo forwards the credentials once to the connection service and never stores them. Start with user + password only (servers are auto-detected); if the result says the IMAP or SMTP configuration is invalid, ask the user for the servers (e.g. OVH: imap ssl0.ovh.net:993 ssl, smtp ssl0.ovh.net:465 ssl; Gmail/Microsoft mailboxes should use the Google/Outlook connection instead). Use account_id to re-authenticate an existing disconnected IMAP account.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "user": "<user>",
      "password": "<password>"
    },
    "name": "imap_connect"
  }
}

Input Schema

NameRequiredDescriptionDefault
userYesMailbox login, usually the full email address.
passwordYesMailbox password or app password, exactly as given by the user.
imap_hostNo
imap_portNo
smtp_hostNo
smtp_portNo
account_idNoNilyo connection ID (unipile_account_id from list_connected_accounts) of an EXISTING account to re-authenticate. Omit to connect a new account.
initial_syncNoEnable the initial mailbox synchronization so account-wide listing/search (email_list_messages, email_resolve_message) works; without it, use email_list_folders + email_list_folder_messages. Default false (faster connection).
imap_encryptionNo
smtp_encryptionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare a non-read-only, destructive, non-idempotent write operation, so the bar is lower; the description still adds real context about credential handling (forwarded once to the connection service, never stored) and auto-detection plus the fallback to explicit server configuration. The gap is that it never explains the destructive side effect implied by the annotations, e.g. what re-authenticating with account_id does to the existing connection or whether a new account is created durably.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and alternative, then adds procedural detail in descending priority. It is dense but nearly every clause carries operational value (credential handling, auto-detect, error branch, Gmail/Microsoft exclusion); the OVH example is a slight digression but useful concrete syntax.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter connection tool with no output schema, the description covers the workflow, failure recovery, and credential lifecycle well. What is missing is the shape of a successful result — notably that a connection/account ID is returned and would be needed by follow-up tools like email_list_folders or list_connected_accounts.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 40% schema description coverage, the description carries meaningful weight: it establishes that user + password are the intended entry point and that imap/smtp hosts are optional due to auto-detection, gives concrete host/port/encryption semantics through the OVH example ('imap ssl0.ovh.net:993 ssl'), and clarifies account_id as an existing Nilyo connection ID for re-authentication. It does not cover the encryption enums or the trade-off behind initial_sync beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Connect a generic IMAP/SMTP mailbox directly from the conversation') and immediately distinguishes the tool from its closest sibling by naming account_connect and contrasting its browser form with in-conversation credential entry. It further narrows scope by redirecting Gmail/Microsoft mailboxes to the Google/Outlook connection instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance (generic IMAP/SMTP), when-not (Gmail/Microsoft), an alternative (account_connect for a secure form), a starting procedure ('start with user + password only'), a failure branch ('if the result says the IMAP or SMTP configuration is invalid, ask the user for the servers'), and the re-authentication case via account_id. Little is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.