Tools#

Every tool bite exposes comes from one registry (crates/bite-core/src/registry.rs): the MCP tools/list schemas and the CLI verbs are generated from the same table, so a tool and its verb can never drift — a CI conformance test fails the build if they do. That makes 46 tools, each with a human CLI twin:

bite reminders create "Water the plants" --due "tomorrow 9am"
bite calendar availability --from "today 9am" --to "today 6pm"
bite mail search --mailbox INBOX --unread --limit 10

Reading the tables below:

confirm — destructive tools return a would_delete/would_move preview until the call passes confirm: true (the CLI asks for --yes). Never blind-fired.
replay — read-only and idempotent tools are transparently retried if the helper dies mid-call; mutating tools (create, send, update, …) are not replayed — the first attempt may already have committed, so a silent retry could double-send mail or duplicate an event. They return an explicit error with a re-check hint instead.
Dates are ISO 8601 with offset; the CLI accepts relaxed forms ("tomorrow 9am").

Calendar (7 tools)#

Engine: EventKit, through the native helper.

Tool		What it does
`calendar_list_calendars`		List the user's calendars (id, title, source, writable). Use ids for calendar-scoped queries.
`calendar_events_search`		Search events in a time window (default: past 7 days to +14 days), optionally filtered by calendars or text.
`calendar_event_get`		Fetch one event by id.
`calendar_event_create`	replay	Create an event. Recurrence, relative and absolute alarms supported. Attendee invites are not supported yet (roadmap).
`calendar_event_update`	replay	Update event fields (reschedule by passing start/end, move calendar by calendar_id). Single-occurrence edit for recurring events.
`calendar_event_delete`	confirm	Delete an event. First call without confirm returns a preview; pass `confirm: true` to actually delete.
`calendar_availability`		Free/busy between two times: busy intervals (merged) and free gaps. Use before scheduling.

Reminders (5 tools)#

Engine: EventKit.

Tool		What it does
`reminders_list_lists`		List reminder lists.
`reminders_search`		Search reminders; filter by list, text, completion state, or due within N days (sorted by due date).
`reminders_create`	replay	Create a reminder with optional due date and absolute-time alarm.
`reminders_update`	replay	Update a reminder: rename, reschedule, complete/uncomplete, move list, set alarm.
`reminders_delete`	confirm	Delete a reminder. First call without confirm returns a preview.

Mail (14 tools)#

Engine: ScriptingBridge through the helper, served from the entity index where it can be. Searches are newest-first.

Tool		What it does
`mail_accounts`		List configured mail accounts. Returns fast deferred feedback while indexing runs unless `force_live`.
`mail_mailboxes_list`		List mailboxes (with unread counts).
`mail_messages_search`		Search messages in a mailbox. Served from the entity index (instant) once indexing completes; while the index is empty it falls back to a live walk. Filters: from, to, subject, body, unread, flagged, since/until, limit (default 20), `skip_count` to skip the exact-total scan. Honest `truncated` flag.
`mail_message_get`		Full message: headers, body, attachment manifest. Pass the `mailbox` from the search result for a fast lookup.
`mail_send`	replay	Send an email. Body accepts Markdown by default (`html: true` for raw HTML). Attachments are file paths.
`mail_reply`	replay	Reply to a message with a quoted original (`reply_all` includes cc's).
`mail_forward`	replay	Forward a message with a quoted original.
`mail_move`	confirm	Move a message to another mailbox. First call without confirm returns what would happen.
`mail_mark`		Mark read/unread, flag/unflag, junk/not-junk.
`mail_delete`	confirm	Delete a message. First call without confirm returns a preview.
`mail_attachment_save`		Save a message attachment to disk (by index from `mail_message_get`).
`mail_bulk_mark`	confirm	Bulk-set read/flagged/junk on a whole mailbox or a filtered selection (unread only, older than N days). Preview first; executed by the crawl worker in one Apple Event — no per-message loops.
`mail_bulk_move`	confirm	Bulk-move messages from one mailbox to another (whole mailbox or filtered selection), via Mail's internal iteration.
`mail_bulk_delete`	confirm	Bulk-delete messages from a mailbox — Mail moves them to Trash (recoverable). Unfiltered whole-mailbox runs are refused.

Notes (6 tools)#

Engine: ScriptingBridge.

Tool		What it does
`notes_folders`		List Notes folders per account.
`notes_search`		Search notes by text (title or body), optionally in one folder.
`notes_get`		Full note: HTML body plus a markdown rendering.
`notes_create`	replay	Create a note. `body` accepts Markdown (converted to Notes HTML).
`notes_update`	replay	Update a note: set/append body (markdown), rename, or move folder.
`notes_delete`	confirm	Delete a note. First call without confirm returns a preview.

Contacts (6 tools)#

Engine: Contacts.framework.

Tool		What it does
`contacts_search`		Search contacts by name/email/phone substring.
`contacts_get`		Fetch one contact by id.
`contacts_create`	replay	Create a contact. emails/phones/urls are arrays of `{label, value}`.
`contacts_update`	replay	Update contact fields. emails/phones/urls replace the whole list when passed.
`contacts_delete`	confirm	Delete a contact. First call without confirm returns a preview.
`contacts_groups`		List contact groups with member counts.

Messages (3 tools)#

Engine: ScriptingBridge for sending and active chats; ~/Library/Messages/chat.db for history (Full Disk Access).

Tool		What it does
`messages_send`	replay	Send an iMessage/SMS. The recipient must be reachable in Messages (have a conversation history) — routing is automatic.
`messages_chats_recent`		List recent chats with participants and last message.
`messages_history`		Read a chat's recent history (newest last). Active chats come from Messages; older history needs Full Disk Access.

Index and search (6 tools)#

The entity index plane — LanceDB, local-only.

Tool		What it does
`index_rebuild`		Rebuild/refresh the entity index for Mail. When the last crawl completed recently (within 7 days), runs a fast delta; `full: true` replays the 365-day schedule; `window_days` pins the lead window; `no_body` stores mail metadata only.
`index_status`		Entity index state: rows per app, freshness, FTS index, pending crawl batches.
`index_crawl_cancel`		Cancel a running index crawl.
`search`		Unified full-text search across everything indexed by bite (Mail, Calendar, Reminders, Contacts, Notes). Served locally from the index — milliseconds, no Apple Events on the query path.
`index_forget`	confirm	Drop rows from the LOCAL search index — Apple data is never touched. Scoped by app and/or container; preview first; the purge is durable across re-crawls.
`index_wipe`	confirm	Destroy the entity index (rows, watermark, purge records). Callable via the CLI (`bite index wipe`) and MCP tools/call; deliberately not advertised in `tools/list`.

One registry, two faces#

The CLI mirrors every tool with the same parameter names (--mailbox, --unread, --due …), so anything true of a tool is true of its verb and vice versa. Two CLI-only conveniences: date flags accept relaxed forms through one parser, and destructive verbs print their preview until you pass --yes.