# Pear MCP tools reference > Canonical agent-readable projection of Pear's 68 hosted MCP tool definitions. MCP endpoint: https://pearmcp.com/api/mcp The connected provider, account permissions, Pear plan, granted OAuth scopes, and AI client policy determine which tools are available. Read and plan before writes; never infer that a setup guide makes every tool available in every client. ## Platform ### `pear_get_write_schema` — Get Write Input Schema Read the complete canonical input schema for an allowed write tool, including approval-only tools. Does not execute or approve anything. Provider support and connected-account readiness must still be checked with pear_provider_status; drafting validates the exact request. - Capability: platform - Access: read - Safety: Read-only. - Required scopes: `mcp:tools:read` ### `pear_get_write_status` — Get Approved Write Status Read your persisted approval status and receipt by ledgerId after an interrupted call. Requires permission for the original write tool and provider. Never executes, retries, claims, or changes the approval. An executing or unknown result must not be resubmitted automatically. - Capability: platform - Access: read - Safety: Read-only. - Required scopes: `mcp:tools:read` ### `pear_provider_status` — Provider Status Inspect connected provider capability, readiness, draftability, and executability without reading provider data. - Capability: platform - Access: read - Safety: Read-only. - Required scopes: `mcp:tools:read` ### `pear_apple_setup_diagnostics` — Apple Setup Diagnostics Run read-only Apple setup diagnostics across iCloud Calendar, Reminders, Contacts, IMAP, and SMTP without exposing secrets. - Capability: platform - Access: read - Safety: Read-only. - Required scopes: `mcp:calendar:read`, `mcp:reminders:read`, `mcp:contacts:read`, `mcp:mail:metadata` ### `pear_draft_write` — Draft Provider Write Create a non-executing ProviderDraftArtifact for an intended write tool. The payload must already satisfy the named write tool contract. To forward with original attachments, use toolName pear_forward_email. For Apple use provider apple and payload {id, folder, uidValidity, to: [recipient], comment?}; for Outlook.com or Microsoft 365 use provider microsoft, accountId, and payload {provider: microsoft, id: GraphMessageId, to: [recipient], comment?} without folder or uidValidity. Pear fetches and prepares the original content and returns attachment names and sizes for approval; never supply preparation yourself. For recurring Apple event updates, use scope this_occurrence_only with a listed recurrenceId, or scope entire_series without recurrenceId. Recurring deletes also support this_and_future with a listed recurrenceId. Dry-run payloads must be called directly and cannot enter approval. Requires permission for the underlying write tool named in toolName. - Capability: platform - Access: read - Safety: Read-only. - Required scopes: `mcp:tools:read` ### `pear_draft_email` — Draft Email (Does Not Send) Create a typed, non-sending email draft artifact from direct recipient, subject, body, and provider fields. This never sends mail and does not save anything to Outlook Drafts. To save a native Outlook draft use pear_create_mailbox_draft. Pass the returned draftArtifact to pear_approve_write_draft with toolName pear_send_email, then execute only after approval. - Capability: platform - Access: read - Safety: Read-only. - Required scopes: `mcp:tools:read` ### `pear_approve_write_draft` — Approve Write Draft Turn a ProviderDraftArtifact into an approved exact execution request and approval-ledger entry without executing the provider write. Inline entries may be carried across a storage outage, but every provider write still requires durable persistence and an atomic claim. - Capability: platform - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:tools:read` ### `pear_execute_approved_write` — Execute Approved Write Atomically claim a durable approved write, execute it at most once, then persist the provider receipt. Server-trusted approval requires ledgerId; outside that mode a canonical approvalLedgerEntry may first be durably materialized. Storage or claim failure occurs before any provider effect. - Capability: platform - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:tools:read` ### `pear_record_approved_write_receipt` — Record Approved Write Receipt Record a provider execution receipt against an approved write request and update its approval-ledger entry without executing a provider write. - Capability: platform - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:tools:read` ## Calendar ### `pear_list_calendars` — List Calendars List available calendars with offset/limit pagination. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: read - Safety: Read-only. - Required scopes: `mcp:calendar:read` ### `pear_list_events` — List Events List calendar events within a canonical timeRange object: { start, end } using ISO 8601 date-times. Use calendarNames to include 1-16 exact calendar names, ids, or URLs. If a selector returns NOT_FOUND, do not repeat it: call pear_list_calendars, choose an exact current selector returned by that call, and retry without broadening the requested calendar scope. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: read - Safety: Read-only. - Required scopes: `mcp:calendar:read` ### `pear_search_events` — Search Events Search calendar events using valid ISO 8601 start and end date/time values; start must be before end, and the search range must be 366 days or less. Use calendarNames to include 1-16 exact calendar names, ids, or URLs. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: read - Safety: Read-only. - Required scopes: `mcp:calendar:read` ### `pear_get_event` — Get Event Get one calendar event by filename. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: read - Safety: Read-only. - Required scopes: `mcp:calendar:read` ### `pear_create_event` — Create Event Create a calendar event. Provider/accountId are optional; for Apple, specify an exact calendar URL when more than one writable visible calendar is available. - Capability: calendar - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:calendar:write` ### `pear_update_event` — Update Event Update a calendar event. Recurring Apple events require explicit scope: use this_occurrence_only with the recurrenceId returned by list/search, or entire_series without recurrenceId. Set dryRun true for an Apple-only, no-write impact preview. Updating this and future occurrences is not supported. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:calendar:write` ### `pear_delete_event` — Delete Event Delete a calendar event. Recurring Apple events require explicit scope: use this_occurrence_only or this_and_future with the recurrenceId returned by list/search, or entire_series without recurrenceId. Set dryRun true for an Apple-only, no-write impact preview. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:calendar:write` ### `pear_cancel_event` — Cancel Event Mark a calendar event as cancelled without claiming attendee notifications were sent. Apple-only until provider-neutral cancellation semantics exist. - Capability: calendar - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:calendar:write` ### `pear_find_free_slots` — Find Free Slots Find available time slots across all visible calendars, one calendarName, or 1-16 exact calendarNames. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: read - Safety: Read-only. - Required scopes: `mcp:calendar:read` ### `pear_check_availability` — Check Availability Check whether a time slot is available across all visible calendars, one calendarName, or 1-16 exact calendarNames. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: read - Safety: Read-only. - Required scopes: `mcp:calendar:read` ### `pear_find_best_time` — Find Best Meeting Time Find the best meeting time across all visible calendars, one calendarName, or 1-16 exact calendarNames. Provider/accountId are optional; Pear uses your default calendar account when omitted. - Capability: calendar - Access: read - Safety: Read-only. - Required scopes: `mcp:calendar:read`, `mcp:reminders:read` ### `pear_create_events_batch` — Create Events in Batch Create multiple events. Provider/accountId are optional at the top level only; each Apple event needs an exact calendar URL when its writable visible target is ambiguous. - Capability: calendar - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:calendar:write` ## Tasks and reminders ### `pear_list_reminder_lists` — List Reminder Lists List reminder/task lists. Provider/accountId are optional; Pear uses your default reminders account when omitted. - Capability: reminders - Access: read - Safety: Read-only. - Required scopes: `mcp:reminders:read` ### `pear_list_reminders` — List Reminders List reminders/tasks. Provider/accountId are optional; Pear uses your default reminders account when omitted. - Capability: reminders - Access: read - Safety: Read-only. - Required scopes: `mcp:reminders:read` ### `pear_get_reminder` — Get Reminder Get one reminder/task by filename. Provider/accountId are optional; Pear uses your default reminders account when omitted. - Capability: reminders - Access: read - Safety: Read-only. - Required scopes: `mcp:reminders:read` ### `pear_create_reminder` — Create Reminder Create a reminder. Provider/accountId are optional; for Apple, specify an exact list URL when more than one writable visible list is available. - Capability: reminders - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:reminders:write` ### `pear_create_email_followup_reminder` — Create Email Follow-Up Reminder Create a reminder from safe email metadata. Apple/iCloud only for now; requires mail metadata and reminders write access, and uses the same approval flow as reminder writes. - Capability: reminders - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:mail:metadata`, `mcp:reminders:write` ### `pear_update_reminder` — Update Reminder Update a reminder. Provider/accountId are optional; Pear uses your default reminders account when omitted. - Capability: reminders - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:reminders:write` ### `pear_complete_reminder` — Complete Reminder Mark a reminder as completed. Provider/accountId are optional; Pear uses your default reminders account when omitted. - Capability: reminders - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:reminders:write` ### `pear_delete_reminder` — Delete Reminder Delete a reminder. Provider/accountId are optional; Pear uses your default reminders account when omitted. - Capability: reminders - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:reminders:write` ### `pear_create_reminders_batch` — Create Reminders in Batch Create multiple reminders. Provider/accountId are optional at the top level only; each Apple reminder needs an exact list URL when its writable visible target is ambiguous. - Capability: reminders - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:reminders:write` ## Contacts ### `pear_list_contacts` — List Contacts List contacts. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: read - Safety: Read-only. - Required scopes: `mcp:contacts:read` ### `pear_search_contacts` — Search Contacts Search contacts. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: read - Safety: Read-only. - Required scopes: `mcp:contacts:read` ### `pear_resolve_person` — Resolve Person Resolve a person from contacts with explicit resolved, ambiguous, or not_found status. Use before drafting email, invites, or contact writes. - Capability: contacts - Access: read - Safety: Read-only. - Required scopes: `mcp:contacts:read` ### `pear_get_contact` — Get Contact Get one contact by filename. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: read - Safety: Read-only. - Required scopes: `mcp:contacts:read` ### `pear_create_contact` — Create Contact Create a contact. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:contacts:write` ### `pear_update_contact` — Update Contact Update a contact using filename from pear_search_contacts, pear_list_contacts, pear_resolve_person, or pear_get_contact. Include addressBookUrl when present, rerun resolution if NOT_FOUND, and do not guess filenames. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:contacts:write` ### `pear_delete_contact` — Delete Contact Delete a contact. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:contacts:write` ### `pear_list_contact_groups` — List Contact Groups List contact groups. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: read - Safety: Read-only. - Required scopes: `mcp:contacts:read` ### `pear_create_contact_group` — Create Contact Group Create a contact group. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:contacts:write` ### `pear_delete_contact_group` — Delete Contact Group Delete a contact group by filename, groupId, or groupName. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:contacts:write` ### `pear_add_contact_to_group` — Add Contact to Group Add a contact to a group. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:contacts:write` ### `pear_update_contact_photo` — Update Contact Photo Update a contact photo. Provider/accountId are optional; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:contacts:write` ### `pear_create_contacts_batch` — Create Contacts in Batch Create multiple contacts. Provider/accountId are optional at the top level only; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:contacts:write` ### `pear_delete_contacts_batch` — Delete Contacts in Batch Delete multiple contacts. Provider/accountId are optional at the top level only; Pear uses your default contacts account when omitted. - Capability: contacts - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:contacts:write` ## Mail ### `pear_list_mail_folders` — List Mail Folders List mail folders. Provider/accountId are optional; Pear uses your default mail account when omitted. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:metadata` ### `pear_list_emails` — List Emails List email metadata. Provider/accountId are optional; Pear uses your default mail account when omitted. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:metadata` ### `pear_mail_digest` — Build Mail Digest Build a deterministic read-only digest of email metadata with priority and category signals. Provider/accountId are optional; Pear uses your default mail account when omitted. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:metadata` ### `pear_get_contact_mail_history` — Get Contact Mail History Get recent read-only mail metadata for a resolved contact or exact email address. Apple/iCloud only for now; requires contacts read and mail metadata access. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:contacts:read`, `mcp:mail:metadata` ### `pear_read_email` — Read Email Read a bounded email body in text or HTML. Follow bodyNextOffset with bodyOffset while bodyHasMore is true. Provider/accountId are optional; Pear uses your default mail account when omitted. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:read` ### `pear_export_email_rfc822` — Export Email as EML Create a short-lived private download URL for one provider-supplied RFC 822 email as an .eml file, up to 5 MiB. For Apple/iCloud and generic IMAP, pass the uidValidity returned by pear_list_emails. Pro only. Supported for Apple/iCloud, Microsoft, and generic IMAP (including Gmail IMAP); Google OAuth/Gmail API connections are not enabled for this tool. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:read` ### `pear_inspect_unsubscribe_options` — Inspect Unsubscribe Options Inspect safe unsubscribe headers for one email without opening links, sending email, or making network requests. Apple/iCloud only for now. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:read` ### `pear_list_mail_rules` — List Mail Rules List your non-destructive mail workflow rules that tune digest priority and category behavior without changing provider mailboxes. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:metadata` ### `pear_create_mail_rule` — Create Mail Rule Create a non-destructive mail workflow rule for digest priority/category behavior. Requires write approval and never moves, sends, deletes, marks, or unsubscribes email. - Capability: mail - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:mail:write` ### `pear_update_mail_rule` — Update Mail Rule Update a non-destructive mail workflow rule. Requires write approval and never mutates provider mailbox state. - Capability: mail - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:mail:write` ### `pear_delete_mail_rule` — Delete Mail Rule Delete a mail workflow rule. Requires write approval and does not touch provider mailboxes. - Capability: mail - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:mail:write` ### `pear_suggest_mail_rule_from_email` — Suggest Mail Rule from Email Suggest a non-destructive mail workflow rule from one email metadata record. Read-only; returns a pear_create_mail_rule payload but does not create the rule. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:metadata` ### `pear_extract_email_attachment` — Extract Email Attachment Text Extract bounded, resumable text from one supported email attachment, including plain-text files and text-based PDFs. Pro only. Select attachmentIndex or attachmentId from pear_read_email across Apple/iCloud, IMAP, Google, and Microsoft mail. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:read` ### `pear_forward_email` — Forward Email with Attachments Forward one Apple iCloud or Microsoft Outlook.com / Microsoft 365 email with its original body and attachments. Requires read and send access and always requires approval: use pear_draft_write with toolName pear_forward_email and the selected provider/accountId, approve the returned draft, then pear_execute_approved_write. Apple requires id, exact folder and uidValidity. Microsoft requires provider microsoft and a Graph message id, without folder or uidValidity. Pass explicit to recipients. Source limit 5 MiB; unsupported MIME fails without sending. Microsoft acceptance is processing, not recipient delivery. Does not support uploads, Google, generic IMAP or send-only accounts. - Capability: mail - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:mail:read`, `mcp:mail:send` ### `pear_create_mailbox_draft` — Create Outlook Mailbox Draft Create a real message in Outlook Drafts. This writes to the selected Microsoft mailbox and never sends email. Distinct from pear_draft_email, which creates only a Pear approval artifact. Explicit provider microsoft and accountId required. List drafts using pear_list_emails with folder Drafts. No attachment uploads. - Capability: mail - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:mail:write` ### `pear_get_mailbox_draft` — Get Outlook Mailbox Draft Read one real Outlook mailbox draft, including its revision and a bounded body preview. The message must still be a draft. bodyTruncated means the body is incomplete; do not use it to replace the full draft body. This read does not mark the message read. - Capability: mail - Access: read - Safety: Read-only. - Required scopes: `mcp:mail:read` ### `pear_update_mailbox_draft` — Update Outlook Mailbox Draft Edit specified fields of a real Outlook mailbox draft. Requires the revision from pear_get_mailbox_draft; changed drafts require a fresh read and review. Omitted fields are preserved. Supplying body replaces the entire draft body. Never sends email. - Capability: mail - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:mail:read`, `mcp:mail:write` ### `pear_delete_mailbox_draft` — Delete Outlook Mailbox Draft Delete a real Outlook mailbox draft using its last inspected revision. Refuses messages that are no longer drafts or changed since inspection. This never sends email. Refresh mailbox state before retrying an uncertain outcome. - Capability: mail - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:mail:read`, `mcp:mail:write` ### `pear_create_reply_draft` — Create Outlook Reply Draft Create a real native Outlook reply or reply-all draft to one original Graph message. Microsoft preserves the thread and determines recipients. Saves in the mailbox without sending. Inspect the returned draft before editing or sending manually in Outlook. - Capability: mail - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:mail:read`, `mcp:mail:write` ### `pear_send_email` — Send Email Send an email. Provider/accountId are optional; Pear uses your default mail account when omitted. - Capability: mail - Access: write - Safety: Write: this changes user-visible provider data. - Required scopes: `mcp:mail:send` ### `pear_request_unsubscribe` — Request Email Unsubscribe Request an unsubscribe action from a previously inspected option. Requires write approval; one-click sends exactly one HTTPS POST and never follows redirects, mailto prepares a separate send-email draft, and manual URLs are never fetched. - Capability: mail - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:mail:read`, `mcp:mail:write` ### `pear_move_email` — Move Email Move an email and return its new identity when the provider supplies one. Apple/IMAP require uidValidity from pear_list_emails. After a move use the returned id, folder and uidValidity; if identityAvailable is false, list the destination folder first. Provider/accountId are optional; Pear uses your default mail account when omitted. - Capability: mail - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:mail:write` ### `pear_mark_email_read` — Mark Email Read or Unread Mark an email as read or unread. Apple/IMAP require uidValidity from pear_list_emails. Provider/accountId are optional; Pear uses your default mail account when omitted. - Capability: mail - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:mail:write` ### `pear_delete_email` — Move Email to Trash Move an email to Trash. Apple/IMAP require uidValidity from pear_list_emails. Provider/accountId are optional; Pear uses your default mail account when omitted. - Capability: mail - Access: write - Safety: Destructive write: review the target and obtain the user-required confirmation before calling. - Required scopes: `mcp:mail:write` ## Related references - [Authentication](https://pearmcp.com/auth.md) - [Client compatibility](https://pearmcp.com/llm/mcp-compatibility.md) - [Data handling](https://pearmcp.com/llm/data-handling.md)