# atbridge — MCP tool reference

> Every MCP tool the atbridge server exposes, in plain text for AI agents
> (Claude Desktop, Cursor, any MCP client). Work READ tools are always available;
> WRITE tools require ATBRIDGE_ALLOW_WRITES=1; the account/system ADMIN tools
> require ATBRIDGE_ADMIN_TOOLS=1 (both off by default). Start the server with
> `atbridge mcp` (stdio). Generated from the live server, so it never drifts
> from the real toolset. Companion: llms-cli.txt (the same operations as a CLI).
>
> ID convention: a param named `identifier` is a FUZZY multi-key lookup — it
> accepts several forms (a numeric id, an email, a name, or an RFC Message-ID,
> as the field says). A param named `id` is an EXACT opaque id returned by a
> prior list/search/get call — pass it back verbatim, don't construct it.
> Sender convention: mail_send/reply/forward/compose take `from` (the sending
> address or identity id); `identity` is a deprecated alias.

## accounts

### accounts_list
List Thunderbird accounts and their identities. Use this to pick an identity id for mail_send / mail_compose `identity` (the sending address) instead of guessing.
Parameters: none.

## auto

### auto_update_set  [ADMIN — needs ATBRIDGE_ADMIN_TOOLS=1]
Enable or disable automatic atbridge updates (FR-UPDATE-07). Default off; when on, detected updates apply automatically.
Parameters:
  - enabled (boolean, required) — true to auto-apply detected updates, false to require manual one-click updates.

### auto_update_status  [ADMIN — needs ATBRIDGE_ADMIN_TOOLS=1]
Whether automatic atbridge updates are enabled (the opt-in FR-UPDATE-07 preference; default off).
Parameters: none.

## calendar

### calendar_clash_check
Check whether a proposed time slot clashes with existing events.
Parameters:
  - end (string, required) — Proposed slot end. Same formats as start.
  - exclude_id (string, optional) — Event id to ignore (e.g. when rescheduling it).
  - start (string, required) — Proposed slot start. YYYY-MM-DD or ISO 8601 (e.g. 2026-01-01T14:00:00Z).

### calendar_events_create  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Create a calendar event (clash-checked unless force). Pass attendees to invite, recurrence (RRULE) for a series.
Parameters:
  - all_day (boolean, optional)
  - attachments (array<object>, optional) — Attachments: uri (link) or dataBase64+filename (inline).
  - attendees (array<object>, optional) — Invitees: [{email, role?}] — role required|optional|chair.
  - calendar_id (string, required) — REQUIRED target calendar id — call calendar_list to find it. Never defaults to a calendar (FR-IDENT-03).
  - categories (array<string>, optional) — Category labels.
  - count (integer, optional) — Number of occurrences (alternative to until).
  - description (string, optional)
  - end (string, required) — Event end. Same formats as start.
  - force (boolean, optional) — Create even if it clashes.
  - location (string, optional)
  - privacy (string, optional) — public | private | confidential.
  - recurrence (string, optional) — RRULE body, e.g. FREQ=WEEKLY;BYDAY=MO — makes a recurring series.
  - reminders (array<object>, optional) — Alarms: minutesBefore (+ relativeTo start|end) or at (ISO).
  - send_invites (boolean, optional) — Email iTIP invitations to the attendees.
  - start (string, required) — Event start. YYYY-MM-DD (all-day) or ISO 8601 (e.g. 2026-01-01T14:00:00Z). A bad value is rejected.
  - title (string, required)
  - until (string, optional) — Recurrence end date (alternative to count). YYYY-MM-DD or ISO 8601.

### calendar_events_delete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Delete a calendar event (scope=this drops one occurrence of a recurring series).
Parameters:
  - id (string, required)
  - occurrence (string, optional) — When scope=this: the ISO start of the single occurrence to delete (YYYY-MM-DD or ISO 8601).
  - scope (string, optional) — this | all (default all). 'this' drops one occurrence of a series.

### calendar_events_get
Get a single calendar event by id.
Parameters:
  - id (string, required) — Exact event id from calendar_events_search (pass it back verbatim — not a title).

### calendar_events_rsvp  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Respond to a received invite (accepted | declined | tentative).
Parameters:
  - email (string, optional) — Which attendee is you, if ambiguous.
  - id (string, required)
  - response (string, required) — accepted | declined | tentative.

### calendar_events_search
Search calendar events in a time window (across all calendars by default).
Parameters:
  - calendar_id (string, optional) — Restrict to one calendar id.
  - count (boolean, optional) — Return only {total, approx} — the event count in the window — instead of the items.
  - from (string, optional) — Window start (inclusive). YYYY-MM-DD or ISO 8601 (e.g. 2026-01-01T00:00:00Z). A bad value is rejected, not ignored.
  - limit (integer, optional) — Max events. Default 0 = all in the window (the window bounds the set).
  - offset (integer, optional) — Skip the first N events (pagination; default 0).
  - query (string, optional) — Free-text filter on title/location/description/categories/attendees.
  - to (string, optional) — Window end. Same formats as from.
  - verbose (boolean, optional) — Include the calendar UUID, description, attendees + reminders per event. OFF by default — lean rows (id, calendarName, title, start, end, location) are enough to pick an event; fetch full detail with calendar_events_get by id.

### calendar_events_update  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Update a calendar event (attendees, recurrence; scope=this edits one occurrence of a series).
Parameters:
  - all_day (boolean, optional)
  - attachments (array<object>, optional) — Replace attachments ([] clears).
  - attendees (array<object>, optional) — Replace the attendee list (omit to leave unchanged; [] to clear).
  - categories (array<string>, optional) — Replace categories ([] clears).
  - count (integer, optional)
  - description (string, optional)
  - end (string, optional)
  - force (boolean, optional)
  - id (string, required)
  - location (string, optional)
  - occurrence (string, optional) — When scope=this: the ISO start of the single occurrence to edit (YYYY-MM-DD or ISO 8601).
  - privacy (string, optional) — public | private | confidential ('' clears).
  - recurrence (string, optional) — Set the series RRULE ("" clears it). Omit to leave unchanged.
  - reminders (array<object>, optional) — Replace alarms ([] clears).
  - scope (string, optional) — this | following | all (default all). 'this' edits one occurrence.
  - send_invites (boolean, optional)
  - start (string, optional)
  - title (string, optional)
  - until (string, optional)

### calendar_find_slots
Find free time slots in a window (honours existing events + optional working hours). The #1 scheduling-assistant query.
Parameters:
  - calendar_id (string, optional) — Restrict the busy lookup to one calendar (default: all).
  - duration_minutes (integer, optional) — Minimum opening length in minutes. Default 30.
  - from (string, required) — Search-window start (inclusive). YYYY-MM-DD or ISO 8601 (e.g. 2026-01-01T00:00:00Z). Empty = no lower bound; a bad value is rejected, not ignored.
  - limit (integer, optional) — Max slots. Default 20.
  - to (string, required) — Search-window end. Same formats as from. Empty = no upper bound.
  - working_hours (string, optional) — Daily local-time band HH:MM-HH:MM (e.g. 09:00-18:00); omit for none.

### calendar_list
List all calendars (id, name, colour, read-only).
Parameters: none.

### calendar_refresh
Trigger a re-sync of every refresh-capable calendar (CalDAV/ICS) NOW instead of waiting its update interval. Use before querying for very recent remote changes.
Parameters:
  - calendar_id (string, optional) — Refresh only this calendar id (from calendar_list). Default: every refresh-capable calendar.

### calendar_settings
The user's Thunderbird calendar settings: working hours (day start/end), working days, and timezone. Use these to reason about scheduling, 'my day', and free/busy in the user's own time.
Parameters: none.

## compose

### compose_templates
List the @bridge Branded Email starter templates (marketing, newsletter, invoice, proposal, cold-outreach, follow-up, project-update, meeting-invite, welcome, feedback-request), or fetch one by `name` to get a ready spec (subject + blocks). Fill in the {placeholders}, then pass the blocks to mail_compose.
Parameters:
  - name (string, optional) — A template name to fetch its ready-to-fill spec; omit to list all templates.

### compose_templates_delete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Delete one of your saved @bridge Branded Email templates by name or id.
Parameters:
  - name (string, required) — The saved template to delete (name or id).

### compose_templates_save  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Save a reusable @bridge Branded Email template (Pro/Enterprise). Provide `blocks` (an @bridge Branded Email layout — see mail_compose) and a `name`, or set `from_last` to save the email most recently composed. Recipients are never stored. Reusable later via compose_templates.
Parameters:
  - blocks (array<object>, optional) — The template layout — an array of @bridge Branded Email blocks (see mail_compose). Omit to save the email most recently composed.
  - description (string, optional) — Optional one-line description.
  - from_last (boolean, optional) — Save the email most recently composed instead of supplying blocks.
  - name (string, required) — A name for the saved template.
  - subject (string, optional) — Subject line (keep {placeholders} for the parts that vary).

## contacts

### contacts_books
List all Thunderbird address books (id + name).
Parameters: none.

### contacts_create  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Create a contact. Full TB fields: multiple typed emails/phones, addresses, org/title/birthday, photo (structured fields), or raw legacy `properties`.
Parameters:
  - addresses (array<object>, optional) — [{type, street, city, state, zip, country}].
  - birthday (string, optional) — YYYY-MM-DD.
  - book_id (string, required) — Address book id (from contacts_books).
  - department (string, optional)
  - display_name (string, optional)
  - emails (array<object>, optional) — [{type, value}] — multiple typed emails.
  - first_name (string, optional)
  - last_name (string, optional)
  - middle_name (string, optional)
  - nickname (string, optional)
  - note (string, optional)
  - org (string, optional)
  - phones (array<object>, optional) — [{type, value}] — multiple typed phones.
  - photo_base64 (string, optional) — Contact photo (base64).
  - photo_mime (string, optional) — e.g. image/png.
  - properties (object, optional) — Raw legacy fields, e.g. {"DisplayName":"Ada","PrimaryEmail":"ada@x.com"}. Optional when using the structured fields.
  - title (string, optional)
  - urls (array<object>, optional) — [{value}] — web pages.

### contacts_delete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Delete a contact by id.
Parameters:
  - id (string, required)

### contacts_list
List contacts across all address books.
Parameters:
  - count (boolean, optional) — Return only {total, approx} — the total contact count — instead of the items.
  - limit (integer, optional) — Max contacts. Default 20.
  - offset (integer, optional) — Skip the first N (pagination; default 0).
  - verbose (boolean, optional) — Include the full parsed vCard + props per contact. OFF by default — lean rows (id, name, emails) are enough to pick a contact; fetch full detail with contacts_show by id.

### contacts_list_add  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Add a contact (card id) to a mailing list.
Parameters:
  - contact (string, required) — Contact card id (from contacts_search).
  - list (string, required) — Mailing-list id or name.

### contacts_list_create  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Create a mailing list / group in an address book.
Parameters:
  - book_id (string, required) — Address book id (from contacts_books).
  - description (string, optional)
  - name (string, required) — List name — used to address it in a recipient field.
  - nick_name (string, optional)

### contacts_list_delete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Delete a mailing list (by id or name); members' contact cards are kept.
Parameters:
  - list (string, required) — Mailing-list id or name. Members' contact cards are kept.

### contacts_list_members
List the members (contacts) of a mailing list, by list id or name.
Parameters:
  - list (string, required) — Mailing-list id or name.

### contacts_list_remove  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Remove a contact (card id) from a mailing list.
Parameters:
  - contact (string, required) — Contact card id (from contacts_search).
  - list (string, required) — Mailing-list id or name.

### contacts_lists
List mailing lists / groups (optionally within one address book).
Parameters:
  - book (string, optional) — Restrict to one address book id (default: all).

### contacts_search
Search contacts by name or email substring.
Parameters:
  - count (boolean, optional) — Return only {total, approx} — the total matching these filters (for pagination) — instead of the items.
  - limit (integer, optional) — Max results. Default 20.
  - offset (integer, optional) — Skip the first N matches (pagination; default 0). offset 20 + limit 20 = results 21-40.
  - query (string, optional) — Substring matched across ALL fields — name, emails, phones, organization, title, address, note (FR-SEARCH-01). Omit to list all.
  - verbose (boolean, optional) — Include the full parsed vCard + props per contact. OFF by default — lean rows (id, name, emails) are enough to pick a contact; fetch full detail with contacts_show by id.

### contacts_show
Show a single contact by id, email, or name.
Parameters:
  - identifier (string, required) — Contact id, email, or name.

### contacts_update  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Update a contact. Structured fields rewrite the card as a vCard; legacy `properties` set/clear single fields.
Parameters:
  - addresses (array<object>, optional) — [{type, street, city, state, zip, country}].
  - birthday (string, optional) — YYYY-MM-DD.
  - department (string, optional)
  - display_name (string, optional)
  - emails (array<object>, optional) — [{type, value}] — multiple typed emails.
  - first_name (string, optional)
  - id (string, required)
  - last_name (string, optional)
  - middle_name (string, optional)
  - nickname (string, optional)
  - note (string, optional)
  - org (string, optional)
  - phones (array<object>, optional) — [{type, value}] — multiple typed phones.
  - photo_base64 (string, optional) — Contact photo (base64).
  - photo_mime (string, optional) — e.g. image/png.
  - properties (object, optional) — Legacy fields to set/clear. Structured fields below rewrite the card as a vCard.
  - title (string, optional)
  - urls (array<object>, optional) — [{value}] — web pages.

## license

### license_billing_portal  [ADMIN — needs ATBRIDGE_ADMIN_TOOLS=1]
Returns a Stripe Customer Portal URL to manage or cancel the subscription. Surface it to the user as a link.
Parameters: none.

### license_billing_status  [ADMIN — needs ATBRIDGE_ADMIN_TOOLS=1]
Your subscription: plan, cohort, current period end, cancel-at, and payment state.
Parameters: none.

### license_devices_deactivate  [ADMIN — needs ATBRIDGE_ADMIN_TOOLS=1]
Deactivate (release) a device slot on your license by device id. A 24h cooldown applies before the slot frees.
Parameters:
  - device_id (string, required) — The device id (from license_devices_list) to deactivate / release.

### license_devices_list  [ADMIN — needs ATBRIDGE_ADMIN_TOOLS=1]
List the devices on your license (id, hostname, platform, status, last seen, cooldown).
Parameters: none.

## mail

### mail_attachment_get
Read one attachment's content by index or partName (from mail_attachments). encoding=text returns text/* attachments as a string (e.g. a .csv/.txt); otherwise base64 bytes. Lets an assistant read/summarise an attached file.
Parameters:
  - encoding (string, optional) — base64 (default) | text. text base64-decodes text/* attachments to a string; non-text always returns base64.
  - identifier (string, required) — Numeric message id or RFC Message-ID.
  - index (integer, optional) — 0-based attachment index (from mail_attachments). Default 0.
  - part_name (string, optional) — Attachment partName (from mail_attachments); preferred over index when set.

### mail_attachments
List a message's attachments (index, filename, content type, size, partName, inline flag). Use before mail_attachment_get.
Parameters:
  - identifier (string, required) — Numeric message id or RFC Message-ID.

### mail_compose  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Build a BRANDED, atbridge-themed HTML email with @bridge Branded Email from a block layout, then draft or send it. Use this — NOT mail_send — whenever the user wants a designed / branded / formatted email (newsletters, announcements, KPI tables, anything that should look styled). blocks is a JSON ARRAY; each item has a "type":
• {"type":"brandline","mode":"header"}  (brand identity band — wordmark + tagline from the theme; mode header|footer. Open with a header brandline; close with a footer one)
• {"type":"heading","level":1,"text":"Title"}  (level 1 = email title, 2/3 = section header)
• {"type":"text","text":"A paragraph.","weight":"normal|bold","tone":"default|muted|faint"}
• {"type":"text","runs":[{"text":"see "},{"text":"PAY-1","href":"https://..."},{"text":" "},{"text":"done","color":"success","bold":true}]}  (RICH inline text — runs with href / bold / italic / code:true / color=default|muted|success|info|warning|danger; use whenever a sentence has an inline link or a status word)
• {"type":"button","text":"Read more","href":"https://...","variant":"primary|ghost"}
• {"type":"badge","text":"Critical","variant":"danger","icon":"🔴"}  (status chip; variant neutral|info|success|warning|danger)
• {"type":"callout","variant":"warning","title":"Heads up","children":[ ... ]}  (a highlighted panel)
• {"type":"card","title":"...","badges":[{"text":"Done","variant":"success"}],"children":[ ... ]}  (a bordered item with status badges)
• {"type":"columns","children":[{"type":"section","children":[ ... ]},{"type":"section","children":[ ... ]}]}  (side-by-side; stacks on mobile; wrap a column's blocks in a section)
• {"type":"table","columns":[{"label":"Item","align":"left"},{"label":"Total","align":"right"}],"rows":[["Widget","$20"]],"totals":["","$20"]}  (data table; align per column; totals row optional)
• {"type":"keyvalue","items":[{"key":"Invoice #","value":"INV-001"}]}  (key/value list)
• {"type":"progress","parts":[{"value":56,"variant":"success","label":"done"},{"value":44,"variant":"neutral","label":"to do"}]}  (segmented status bar + legend)
• {"type":"section","background":"surface|alt|none","children":[ ... ]}  (a tinted band) · {"type":"divider"} (rule) · {"type":"spacer"} (gap)
• {"type":"chart","chartType":"bar|line|area|scatter|stacked-bar|pie","title":"Revenue","labels":["Q1","Q2"],"datasets":[{"label":"2026","data":[10,20]}]}  (rendered natively to an inline PNG, themed automatically)
• {"type":"image","name":"moon","alt":"The Moon","width":480}  (a PICTURE. Add the block here AND supply its bytes in the top-level `images` array under the SAME name — the simplest way is a public URL: images:[{"name":"moon","url":"https://.../moon.jpg"}] (or path / content_base64). atbridge downloads it and auto-downscales + recompresses it to an email-friendly size, and embeds it inline (cid:). To add a real photo, find its image URL and pass it in images[].url — do NOT paste a description.)
• {"type":"footer","segments":[{"text":"Sent with @bridge"}],"linkText":"Unsubscribe","linkHref":"https://..."}
TIP: ready-made layouts exist — call compose_templates to fetch one (invoice, newsletter, project-update, proposal, welcome …), fill the {placeholders}, and pass its blocks here. Colors, fonts and spacing come from the brand theme automatically — do NOT add inline styles.
Parameters:
  - attachments (array<string>, optional) — File paths to attach (regular, non-inline attachments alongside the branded body).
  - bcc (array<string>, optional)
  - blocks (array<object>, required) — Array of @bridge Branded Email blocks — see the tool description for the format.
  - cc (array<string>, optional)
  - from (string, optional) — REQUIRED sender (PREFERRED name; matches the CLI --from): the account's email address or a TB identity id. Call accounts_list to find it. Never defaults to a mailbox (FR-IDENT-01). Alias: identity (from wins if both are set).
  - identity (string, optional) — Deprecated alias of from — kept for back-compat. Prefer from.
  - images (array<object>, optional) — Byte sources for {type:image,name:N} blocks — one entry per image block, matched by name. Each: {name, and ONE of url/path/content_base64, +optional content_type}. A public https url is the easiest way to add a real photo. atbridge auto-optimizes (downscale + recompress) and embeds inline (cid:).
  - mode (string, optional) — draft (default — saved to the Drafts folder) | send | review (opens a compose window in Thunderbird).
  - subject (string, required) — Email subject.
  - theme (object, optional) — Optional partial theme override (colors/fonts); omit to use the atbridge brand default.
  - to (array<string>, required) — Recipient email addresses.

### mail_delete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Delete a message (Trash, or hard=true). Bulk: pass identifiers[] or a selector.
Parameters:
  - hard (boolean, optional) — Permanently delete (skip Trash).
  - identifier (string, optional)
  - identifiers (array<string>, optional) — Bulk: ids to delete.
  - max (integer, optional) — Bulk safety cap (default 100).
  - selector (object, optional) — Bulk: pick messages to delete.

### mail_draft_edit  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Edit an existing draft — change only the fields you pass; the rest of the draft (body, recipients, attachments) is kept. Identify the draft by its id from mail_list/mail_search.
Parameters:
  - bcc (array<string>, optional) — Replace the BCC recipients. Omit to keep them.
  - cc (array<string>, optional) — Replace the CC recipients. Omit to keep them.
  - html (string, optional) — Replace the body with HTML. Omit to keep the body.
  - identifier (string, required) — The draft to edit — its MailExt id (from mail_list/mail_search) or its RFC message-id.
  - subject (string, optional) — New subject. Omit to keep the draft's subject.
  - text (string, optional) — Replace the body with plain text (ignored if html is set).
  - to (array<string>, optional) — Replace the recipients. Omit to keep them.

### mail_empty_trash  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Permanently delete everything in an account's Trash.
Parameters:
  - account (string, required) — EXACT account id or email whose Trash to empty (FR-IDENT-02).
  - max (integer, optional) — Safety cap (default 100).

### mail_fetch
Trigger Thunderbird's Get Messages (new-mail check) NOW — same as the toolbar button. Use before searching for very recent mail; arrival otherwise waits each account's check interval.
Parameters:
  - account_key (string, optional) — Poll only this account key (from accounts_list). Default: every account.

### mail_folder_create  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Create a mail folder (nested 'Parent/Child' supported).
Parameters:
  - account (string, required) — EXACT account id or email — call accounts_list to choose (FR-IDENT-02; no substring matching).
  - name (string, required) — Folder name; 'Parent/Child' to nest.

### mail_folder_delete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Delete a mail folder (special-use folders are protected).
Parameters:
  - account (string, required) — EXACT account id or email (FR-IDENT-02).
  - path (string, required) — Folder path to delete (special-use folders are protected).

### mail_folder_rename  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Rename a mail folder.
Parameters:
  - account (string, required) — EXACT account id or email (FR-IDENT-02).
  - name (string, required) — New folder name.
  - path (string, required) — Current folder path.

### mail_folders
List all mail folders across all Thunderbird accounts (name, path, account, message count).
Parameters: none.

### mail_forward  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Forward a message (requires to).
Parameters:
  - attachments (array<string>, optional) — File paths to attach (regular, non-inline attachments).
  - bcc (array<string>, optional)
  - cc (array<string>, optional)
  - delivery_status_notification (boolean, optional) — Request a delivery status notification.
  - forward_type (string, optional) — forwardInline (default) | forwardAsAttachment.
  - from (string, optional) — Sender (PREFERRED name; matches the CLI --from): the account's email address or a TB identity id — call accounts_list to find it. REQUIRED for a new message (mail_send). For mail_reply/mail_forward, LEAVE EMPTY to reply from the account that received the original; only set to override. Never defaults to a mailbox for new messages (FR-IDENT-01). Alias: identity (from wins if both are set).
  - headers (array<object>, optional) — Custom headers [{name, value}] — TB requires X- names.
  - html (string, optional) — HTML body.
  - identifier (string, required) — Message to forward.
  - identity (string, optional) — Deprecated alias of from — kept for back-compat. Prefer from.
  - inline_images (array<object>, optional) — Inline images for the HTML body, referenced as <img src="cid:CID">. Embed as multipart/related (render inline in Gmail/Outlook), not dangling attachments. FR-COMPOSE-14.
  - mode (string, optional) — send | draft | template | later | review. Default send. review opens a TB compose window for the user to review + Send (nothing is sent by the call).
  - no_signature (boolean, optional)
  - priority (string, optional) — lowest | low | normal | high | highest.
  - reply_to (array<string>, optional) — Reply-To addresses.
  - return_receipt (boolean, optional) — Request a read receipt.
  - subject (string, optional)
  - text (string, optional) — Plain-text body.
  - to (array<string>, optional) — Recipients.

### mail_get
Fetch a single message by numeric id or RFC Message-ID. Returns headers, body, attachments metadata.
Parameters:
  - body (string, optional) — Body format: text | html | raw. Default text.
  - identifier (string, required) — Numeric message id (from mail_list/mail_search) or RFC Message-ID.
  - include_headers (boolean, optional)

### mail_list
List recent messages in a folder (default INBOX), newest first. Returns LEAN rows by default (id, date, from/to, subject, read/flagged); add verbose:true for the full routing metadata.
Parameters:
  - account (string, optional)
  - count (boolean, optional) — Return only {total, approx} — the message count in the folder — instead of the items.
  - folder (string, optional) — Folder to list by label (e.g. INBOX, or nested Parent/Child). Default INBOX.
  - limit (integer, optional) — Max results. Default 20.
  - offset (integer, optional) — Skip the first N (pagination; default 0).
  - verbose (boolean, optional) — Return the full per-result metadata (headerMessageId, folderLabel, accountName, conversationId). OFF by default: rows are LEAN — id, date, from/to, subject, read/flagged — enough to pick a message; recover the rest with mail_get by id.

### mail_mark  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Update message flags (read/star/tags). Bulk: pass identifiers[] or a selector.
Parameters:
  - flagged (boolean, optional) — Set star/flag.
  - identifier (string, optional)
  - identifiers (array<string>, optional) — Bulk: ids to mark.
  - max (integer, optional) — Bulk safety cap (default 100).
  - read (boolean, optional) — Set read state (true=read, false=unread).
  - selector (object, optional) — Bulk: pick messages to mark.
  - tags (array<string>, optional) — Replace tags; empty array clears.

### mail_move  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Move a message to another folder. Bulk: pass identifiers[] or a selector instead of identifier.
Parameters:
  - folder (string, required) — Target folder ('INBOX' or 'Parent/Child'); first match wins.
  - identifier (string, optional) — Single message id or RFC Message-ID.
  - identifiers (array<string>, optional) — Bulk: ids to move.
  - max (integer, optional) — Bulk safety cap (default 100).
  - selector (object, optional) — Bulk: pick messages by query/folder/account/unread/flagged.

### mail_reply  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Reply to a message.
Parameters:
  - attachments (array<string>, optional) — File paths to attach (regular, non-inline attachments).
  - bcc (array<string>, optional)
  - cc (array<string>, optional)
  - delivery_status_notification (boolean, optional) — Request a delivery status notification.
  - from (string, optional) — Sender (PREFERRED name; matches the CLI --from): the account's email address or a TB identity id — call accounts_list to find it. REQUIRED for a new message (mail_send). For mail_reply/mail_forward, LEAVE EMPTY to reply from the account that received the original; only set to override. Never defaults to a mailbox for new messages (FR-IDENT-01). Alias: identity (from wins if both are set).
  - headers (array<object>, optional) — Custom headers [{name, value}] — TB requires X- names.
  - html (string, optional) — HTML body.
  - identifier (string, required) — Message to reply to.
  - identity (string, optional) — Deprecated alias of from — kept for back-compat. Prefer from.
  - inline_images (array<object>, optional) — Inline images for the HTML body, referenced as <img src="cid:CID">. Embed as multipart/related (render inline in Gmail/Outlook), not dangling attachments. FR-COMPOSE-14.
  - mode (string, optional) — send | draft | template | later | review. Default send. review opens a TB compose window for the user to review + Send (nothing is sent by the call).
  - no_signature (boolean, optional)
  - priority (string, optional) — lowest | low | normal | high | highest.
  - reply_to (array<string>, optional) — Reply-To addresses.
  - reply_type (string, optional) — replyToSender (default) | replyToAll | replyToList.
  - return_receipt (boolean, optional) — Request a read receipt.
  - subject (string, optional)
  - text (string, optional) — Plain-text body.
  - to (array<string>, optional) — Recipients.

### mail_search
Search messages by free-text query (subject AND body) and/or structured filters. Newest first. Returns LEAN rows by default (id, date, from/to, subject, read/flagged) — enough to pick a message; add snippet:true for a one-line gist per result, or verbose:true for the full routing metadata.
Parameters:
  - account (string, optional) — Restrict to one account — substring of its name/email/id (read-side is lenient; mail WRITES require an EXACT account per FR-IDENT-02).
  - count (boolean, optional) — Return only {total, approx} — the total matching these filters (for planning pagination) — instead of the items. Mail total is best-effort (the search is budget-bounded); scope with folder/since/until for an exact figure.
  - folder (string, optional) — Restrict to one folder by label (e.g. INBOX, or nested Parent/Child).
  - from (string, optional) — Filter by sender — substring of a name or address (e.g. billing@x.com or just billing).
  - limit (integer, optional) — Max results. Default 20.
  - offset (integer, optional) — Skip the first N matches (pagination; default 0). offset 20 + limit 20 = results 21-40.
  - query (string, optional) — Free-text search; matches subject and body.
  - since (string, optional) — Inclusive lower date bound. Accepts YYYY-MM-DD (e.g. 2026-01-01, treated as UTC midnight) or a full RFC3339 timestamp (2026-01-01T00:00:00Z). An unparseable value is rejected, never ignored.
  - snippet (boolean, optional) — Attach a ~200-char plaintext gist of each message body so a one-line summary or triage finishes WITHOUT a follow-up mail_get. The gist is cleaned — quote markers, separator rules and zero-width noise stripped — so it starts on real content, not a divider.
  - subject (string, optional) — Subject substring filter.
  - to (string, optional) — Filter by recipient — substring of a name or address.
  - until (string, optional) — Inclusive upper date bound. Same formats as since (YYYY-MM-DD or RFC3339).
  - verbose (boolean, optional) — Return the full per-result metadata (headerMessageId, folderLabel, accountName, conversationId). OFF by default: results are LEAN — id, date, from/to, subject, read/flagged (+ snippet if asked) — which is all you need to pick a message; recover the rest with mail_get by id. Set this only when you genuinely need those routing fields across many results at once.

### mail_send  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Compose + send a new message (or draft/template/later via mode).
Parameters:
  - attachments (array<string>, optional) — File paths to attach (regular, non-inline attachments).
  - bcc (array<string>, optional)
  - cc (array<string>, optional)
  - delivery_status_notification (boolean, optional) — Request a delivery status notification.
  - from (string, optional) — Sender (PREFERRED name; matches the CLI --from): the account's email address or a TB identity id — call accounts_list to find it. REQUIRED for a new message (mail_send). For mail_reply/mail_forward, LEAVE EMPTY to reply from the account that received the original; only set to override. Never defaults to a mailbox for new messages (FR-IDENT-01). Alias: identity (from wins if both are set).
  - headers (array<object>, optional) — Custom headers [{name, value}] — TB requires X- names.
  - html (string, optional) — HTML body.
  - identity (string, optional) — Deprecated alias of from — kept for back-compat. Prefer from.
  - inline_images (array<object>, optional) — Inline images for the HTML body, referenced as <img src="cid:CID">. Embed as multipart/related (render inline in Gmail/Outlook), not dangling attachments. FR-COMPOSE-14.
  - mode (string, optional) — send | draft | template | later | review. Default send. review opens a TB compose window for the user to review + Send (nothing is sent by the call).
  - no_signature (boolean, optional)
  - priority (string, optional) — lowest | low | normal | high | highest.
  - reply_to (array<string>, optional) — Reply-To addresses.
  - return_receipt (boolean, optional) — Request a read receipt.
  - subject (string, optional)
  - text (string, optional) — Plain-text body.
  - to (array<string>, optional) — Recipients.

### mail_thread
Fetch a whole conversation thread given any message id in it.
Parameters:
  - identifier (string, required) — A message id in the thread.
  - limit (integer, optional) — Max messages. Default 50.

## notes

### notes_delete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Delete a saved note by id.
Parameters:
  - id (string, required) — Note id (filename stem).

### notes_get
Read one saved note (with body) by id or title — pull a prior artifact in as context.
Parameters:
  - identifier (string, required) — Note id (filename stem) or exact title.

### notes_list
List or search the user's saved @bridge Notes (local markdown). With query: full-text across title/body/tags/source; without: all, newest first (metadata).
Parameters:
  - count (boolean, optional) — Return only {total, approx} — the total matching — instead of the items.
  - limit (integer, optional) — Max results. Default 20.
  - offset (integer, optional) — Skip the first N (pagination; default 0).
  - query (string, optional) — Free-text filter across all fields — title, body, tags, source (FR-SEARCH-01). Omit to list all.

### notes_move  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Move or rename a saved note within the store (organize into folders).
Parameters:
  - dest (string, required) — New relative path; an existing folder moves the note into it keeping its name (parent folders are created; won't overwrite).
  - id (string, required) — Note id (slash path, e.g. 'work/plan').

### notes_save  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Save a markdown note to the user's local @bridge Notes store (e.g. a useful chat result); optional folder.
Parameters:
  - body (string, required) — Markdown body (required).
  - folder (string, optional) — Optional subfolder (relative, slash-separated, e.g. 'work/2026').
  - source (string, optional) — Where it came from, e.g. '@bridge chat'.
  - tags (array<string>, optional)
  - title (string, required) — Note title (required).

### notes_update  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Edit a saved note in place (title/body/tags) — keeps its id + created date.
Parameters:
  - body (string, optional) — New markdown body (omit to keep).
  - id (string, required) — Note id (filename stem).
  - tags (array<string>, optional)
  - title (string, optional) — New title (omit to keep).

## tasks

### tasks_complete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Mark a task done (set reopen=true to set it back to needs-action).
Parameters:
  - id (string, required)
  - reopen (boolean, optional) — Reopen (set back to needs-action) instead of completing.

### tasks_create  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Create a task / to-do (title required). Full TB fields: start/due (+all_day), priority, notes, location, categories, status, percent_complete, recurrence, reminders, attachments.
Parameters:
  - all_day (boolean, optional) — Treat start/due as all-day (date-only).
  - attachments (array<object>, optional) — Attachments: uri (link) or dataBase64+filename (inline).
  - calendar_id (string, required) — REQUIRED task-list calendar id — call calendar_list to find it. Never defaults to a list (FR-IDENT-03).
  - categories (array<string>, optional) — Category labels.
  - count (integer, optional) — Number of occurrences (alternative to until).
  - due (string, optional) — Due date. YYYY-MM-DD or ISO 8601.
  - location (string, optional) — Location.
  - notes (string, optional) — Notes / description.
  - percent_complete (integer, optional) — Percent complete, 0-100.
  - priority (string, optional) — high | normal | low, or 0-9.
  - recurrence (string, optional) — RRULE body, e.g. FREQ=WEEKLY;BYDAY=MO — makes a recurring series.
  - reminders (array<object>, optional) — Alarms: minutesBefore (+ relativeTo start|due) or at (ISO).
  - start (string, optional) — Start. YYYY-MM-DD (all-day) or ISO 8601.
  - status (string, optional) — needs-action | in-process | completed | cancelled.
  - title (string, required) — Task title (required).
  - until (string, optional) — Recurrence end, ISO 8601.

### tasks_delete  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Delete a task by id.
Parameters:
  - id (string, required)

### tasks_list
List tasks / to-dos (incomplete by default; set include_completed for done items).
Parameters:
  - calendar_id (string, optional) — Restrict to one calendar id.
  - count (boolean, optional) — Return only {total, approx} — the total matching — instead of the items.
  - include_completed (boolean, optional) — Include completed tasks (default: incomplete only).
  - limit (integer, optional) — Max results. Default 20.
  - offset (integer, optional) — Skip the first N (pagination; default 0).
  - query (string, optional) — Free-text filter across all fields — title, notes, location, categories, status, due (FR-SEARCH-01). Omit to list all.
  - verbose (boolean, optional) — Include notes, attachments + reminders per task. OFF by default — lean rows are enough to triage what's due/overdue.

### tasks_update  [WRITE — needs ATBRIDGE_ALLOW_WRITES=1]
Update a task (only the fields you pass change; '' / [] clears). Same full field set as tasks_create.
Parameters:
  - all_day (boolean, optional) — Treat start/due as all-day (date-only).
  - attachments (array<object>, optional) — Replace attachments ([] clears).
  - categories (array<string>, optional) — Replace categories ([] clears).
  - count (integer, optional) — Number of occurrences (alternative to until).
  - due (string, optional) — New due. YYYY-MM-DD or ISO 8601; '' clears.
  - id (string, required)
  - location (string, optional) — ('' clears).
  - notes (string, optional)
  - percent_complete (integer, optional) — Percent complete, 0-100.
  - priority (string, optional) — high|normal|low|0-9 ('' clears).
  - recurrence (string, optional) — RRULE body ('' clears the series).
  - reminders (array<object>, optional) — Replace alarms ([] clears).
  - start (string, optional) — New start. YYYY-MM-DD or ISO 8601; '' clears.
  - status (string, optional) — needs-action | in-process | completed | cancelled.
  - title (string, optional)
  - until (string, optional) — Recurrence end, ISO 8601.

## version

### version_status  [ADMIN — needs ATBRIDGE_ADMIN_TOOLS=1]
Whether a newer atbridge version is available, read network-free from the cached update check. Returns known:false when no check has run yet.
Parameters: none.