Twenty-three tools connect the agent with mail, calendars, weather, news, RSS feeds, and HTTP endpoints. Mail and calendar list and read tools usually use SoAI's local cache. Sync, search, and mutation calls contact the configured service and can act in your name.
Mail and calendar need setting up before they do anything. Weather, news, RSS, and http_request work as
soon as an agent has them enabled.
Connecting a mailbox
In the SoAI WebUI, select Open settings menu at the right of the header, then Settings and Mail & calendar. Select Add account under Mail accounts. Pick IMAP + SMTP or POP3 + SMTP, give the account a name, and fill in the inbound host and port, usually 993 for IMAP over TLS or 995 for POP3, along with the SMTP host and port for sending.
Inbound security and SMTP security accept TLS or STARTTLS, and the form offers no plaintext transport. Inbound mail uses IMAP or POP3, while outbound mail always uses SMTP.
For Authentication type, Password stores a secret and OAuth2 walks through an authorization flow instead. Providers that have turned off password logins need the OAuth2 path; fill in the client ID, endpoints, and scopes under OAuth configuration, save, then use Connect OAuth on the account.
Test checks the connection before you rely on it, and Sync now pulls mail straight away rather than waiting for the schedule. Each account shows its Last sync time and its Last error, which is the first place to look when the tools come back empty.
Mail tools
SoAI keeps a local cache of your folders and messages and syncs it in the background. Most tools read that cache rather than hitting the server, which is why they answer quickly and why the cache boundary matters.
| Tool | Reads cache | What it does |
|---|---|---|
mail_account_sync |
no | Forces a refresh, the same as Sync now |
mail_accounts_list |
yes | Your configured accounts |
mail_attachment_download |
yes | Saves one attachment into SoAI file storage |
mail_folder_backfill |
no | Pulls the next older batch of history into the cache |
mail_folder_update |
no |
One action: create, rename, delete,
subscribe, or unsubscribe. Destructive.
|
mail_folders_list |
yes | Cached folders for one account |
mail_message_compose |
no |
Sends or drafts. mode of new, reply, reply_all, or
forward; delivery of send or save_draft.
Destructive.
|
mail_message_read |
yes | One cached message, chunked for long bodies |
mail_message_update |
no |
One action: mark_read, mark_unread, flag,
unflag, archive, unarchive, move, copy,
delete, or restore. Destructive.
|
mail_messages_list |
yes | Cached messages in a folder, with filters |
mail_messages_remote_search |
no | Searches on the server and imports what it finds |
Most mail-list surprises come from the cache boundary. mail_messages_list sees only synchronized
messages, so an item older than the cache window will not appear no matter how the agent phrases the query. Use
mail_folder_backfill to pull more history, or mail_messages_remote_search to ask the
server directly.
Background sync runs every 120 seconds and keeps 30 days of history, excluding Junk and
Spam, with a limit of 5000 messages per folder. Reads cap at 50,000 characters per call, snippets at
500, and attachments at 25,000,000 bytes. To change these defaults, an administrator with
Configuration changes (CONFIG_PATCH) selects Open settings menu at the right of the header,
then Settings. Select Advanced in the Settings page header. The page becomes
Advanced settings and the control changes to Basic. Search for
INTEGRATIONS.MAIL, edit the required key,
and select Save.
SoAI requires every remote search to include a narrowing filter. A full-text search also needs a time bound. These requirements prevent an agent from starting an unbounded scan of a large mailbox.
mail_message_compose is the one to think hardest about. It sends real mail to real people from your own
address. Plan mode blocks it, Execute mode does not, and a mistake here is not something you can take back. Turn on
Require tool approval for any conversation that can compose, and read the arguments in the approval
dialog rather than clicking through.
Calendar
Calendar works over CalDAV with the same cache-first design. Select Open settings menu at the right of the header, then Settings and Mail & calendar. Under Calendar accounts, add an account with the CalDAV base URL and either a password or OAuth2.
Set Linked mail account while you are there. When an event names an organizer,
calendar_invite_respond requires an SMTP-ready linked account before it updates the event. It saves the
CalDAV attendee response first, then sends the organizer an email. If that send fails after the save, the tool
returns the updated event with a warning.
| Tool | What it does |
|---|---|
calendar_account_sync |
Rediscovers calendars and refreshes the cache |
calendar_accounts_list |
Configured calendar accounts |
calendar_calendars_list |
Cached calendars in one account |
calendar_event_read |
One cached event in full |
calendar_event_update |
Creates, changes, or deletes an event. Destructive. |
calendar_events_list |
Cached events in a time window |
calendar_invite_respond |
Replies accept, tentative, or decline, with an optional comment.
Destructive.
|
calendar_window_sync |
Refreshes one specific time window from the server |
The synced window runs 90 days back and 365 forward, refreshed every 300 seconds. Ask about a date outside it and
the agent needs calendar_window_sync first. Recurring events expand up to 500 occurrences each, which
is why a daily meeting with no end date does not produce an endless list. An administrator with
Configuration changes (CONFIG_PATCH) can change these defaults in Advanced settings: select
Open settings menu at the right of the header, then Settings, select
Advanced in the Settings page header, search for
INTEGRATIONS.CALENDAR, and select
Save after editing.
Weather
weather takes a location as a place name and returns current conditions plus a forecast.
forecast_days runs 1 to 14 and defaults to 3. hourly_hours adds hour-by-hour detail up to
48 and defaults to 0. units is metric or imperial, and
country_code settles a place name that exists in several countries.
It uses Open-Meteo and needs no key, so it works out of the box. Separate controls set the geocoding and forecast
URLs: TOOLS.MCP.WEATHER.GEOCODING_BASE_URL and TOOLS.MCP.WEATHER.FORECAST_BASE_URL, so
pointing SoAI at your own Open-Meteo instance means changing two settings.
News
news queries GDELT. Pass latest or today for current headlines, a
YYYY-MM-DD date for one day, or any phrase to search for it. language defaults to
en and country to US. max_results defaults to 10 and caps at 25.
SoAI raises any lower value to 10.
SoAI prefers GDELT's DOC 2.0 API for full-text country-filtered results and falls back to the Article List feed for global headlines when DOC is unavailable, so a query returns less precise results instead of failing. No key required.
RSS
rss_read fetches one RSS or Atom feed by url and returns structured items.
max_items defaults to 10 and caps at 100. There is no subscription list and no polling: an agent reads
a feed when asked. For a feed you want checked regularly, pair it with an automation from the
Automation page, described under
Planning and agent control tools.
HTTP requests
http_request handles APIs that have no dedicated SoAI tool. It supports GET, POST, PUT, PATCH, DELETE,
HEAD, and OPTIONS with custom headers and a body, then returns status, headers, body, and timing. Text comes back as
UTF-8 and binary content as Base64.
SoAI retries safe methods automatically. For a mutating method with retries above zero, SoAI requires a
nonempty Idempotency-Key header. That requirement prevents an agent from submitting the same order
twice after a timeout. session_mode returns an updated session payload containing cookies
and headers. Passing that payload into the next call carries the session through a multi-step API flow.
The remaining arguments are limits: timeout up to 120 seconds, max_response_bytes with a
truncation flag, follow_redirects, detect_blocked for bot and CAPTCHA responses, and the
backoff and jitter behind retries.
TOOLS.MCP.HTTP_REQUEST.BLOCK_PRIVATE_NETWORK_EGRESS defaults to true, the opposite of
web_fetch. So an agent with this tool cannot reach your LAN or SoAI's own admin interface until you
turn that off. Weigh that before you do: after the change, the tool can send a described request to permitted
private addresses, including internal services.