Tools and prompts

Reference for what an agent on https://api.workwae.com/mcp can call. Read it when you choose a credential's scopes or write instructions for an agent. To connect a client, see MCP server.

Tools by scopeCopy Anchor Link

A client sees only the tools its credential's scopes allow.

• search_messages is the way to find and list mail; get_thread reads a conversation with its bodies in one call.
• mark_messages and move_messages triage up to 50 messages, or a whole thread, at once.
• preview_message, commit_message and pick_meeting_time back the MCP Apps views; commit_message is for the review card only.
• Claude Code keeps search_messages and list_events loaded while it defers the others.

Refusals come back as tool errors whose text starts with the reason (account_not_found: ...) and says what to do next, such as which tool the missing id comes from, so the model can recover. How sends are confirmed and limited is in Sending safely.

Working with accountsCopy Anchor Link

Tools that work on one account take accountId: the account's id or its email address. Every result names its account. accountId may be left out when:

• the key or grant is limited to exactly one account;
• a message id names it (the server finds the caller's account holding the message);
• a calendar or contacts tool is called and only one account syncs them.

Otherwise the refusal names the accounts to choose from.

• list_accounts shows each account's provider, status (and why, when not active), calendar time zone, what it can do (mail, send, calendar, contacts) and the addresses it can send as, default first.
• list_changes reads the change feed across the caller's accounts.
• Times show in the account's calendar zone, or in the IANA zone passed as timeZone (invalid_time_zone otherwise).
• get_current_time uses the zone asked for, else that of accountId, else the one the credential's accounts' calendars share, else UTC.

Connecting another accountCopy Anchor Link

connect_account returns a link, valid for an hour, where the user connects another mailbox. provider is google, microsoft or imap; left out, the page offers all three. Clients that support URL elicitation open the link for the user.

• A key limited to accounts is refused with account_scope_forbidden.
• Under an OAuth grant for specific accounts, the new account is out of reach until the user signs in again and picks it.

MailCopy Anchor Link

Search and readCopy Anchor Link

• search_messages takes q: words, "exact phrase", OR, -exclude. Left out, it lists newest first.
• Filters: from, to, unread, flagged, hasAttachments, after, before and mailbox, an id or a role (inbox, archive, sent, drafts, trash, spam, all).
• Pages hold 20 messages (at most 50); a listing of one mailbox estimates its total.
• detail is brief by default (one line and a 120-character snippet per message); full adds recipients, labels and mailboxes.
• Without accountId, search_messages searches every account the caller reaches, up to 25, merged newest first without paging, and lists any that failed. A mailbox role works across accounts; a mailbox id or a cursor needs accountId.
• get_message removes quoted reply history, signatures and mobile footers; quoted: true keeps them. Bodies come in pages of 20,000 characters; pass the returned offset as bodyOffset to read on.
• get_thread returns a conversation oldest first with the latest body (bodies: "latest", the default), every body ("all") or snippets only ("none"). Bodies share 30,000 characters; a cut one continues with get_message.
• get_attachment returns at most 10 MiB.

TriageCopy Anchor Link

• mark_messages sets read and flagged.
• move_messages moves to a mailbox (to: "trash" trashes; "archive" on Gmail removes the Inbox label) or adds and removes Gmail labels.
• Both take up to 50 messageIds or a threadId and report each failure.

ComposeCopy Anchor Link

create_draft, update_draft and send_message share their fields:

• update_draft replaces the whole draft, so pass every field it should keep; the draft gets a new id.
• send_message and send_draft send at once or at sendAt. cancel_send cancels a queued send during the account's undo window or before its sendAt.

Calendar and contactsCopy Anchor Link

• list_events lists occurrences overlapping a range, from start (default now) to end (default 90 days later), 50 a page, with detail brief or full. q finds events whose subject, location, organizer or attendees contain all its words.
• list_events, get_event and find_availability show times in the account's zone or timeZone; find_availability reads workingHours in that zone.
• create_event goes to the account's primary calendar unless calendarId names another. It takes one meeting: { provider: "teams" | "meet" | "zoom" | "webex" } or { url }. Teams needs a Microsoft account and Meet a Google one (meeting_provider_mismatch otherwise).
• update_event takes only meeting: { url }, or null to remove the link.
• Calendar writes that email attendees or the organizer need send; see Calendar writes are sends.
• search_contacts finds contacts by name, address, phone number or organization and returns full records, 20 a page.

PromptsCopy Anchor Link

Clients list prompts as slash commands. account completes from the caller's own accounts. A prompt mentions a write or send tool only when the caller has its scope.