# Pear MCP tools reference > Canonical agent-readable projection of Pear's 59 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_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. 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. 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_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_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. 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. 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 Delete an email. 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)