Which integrations are available for this server?

Read-only access to locally synced Apple data including Mail, Messages, Calendar, Reminders, Contacts, Photos, Notes, Voice Memos, and iCloud Drive. Ability to read locally synced Gmail messages through Mail.app. Retrieval of local iCloud Drive files and iCloud-synced mail via Mail.app.

How do I use local-apple-data?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@local-apple-data find my recent emails from Sarah" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

local-apple-data

by BillyBunn

Overview Schema Related Servers Score Discussions

Python

Local

The local-apple-data server provides local-first, privacy-gated, read-mostly access to Apple app data synced on your Mac, with a limited set of approved write/mutation operations.

Health & Diagnostics

apple_data_health – Redacted readiness and schema checks for all supported data surfaces
apple_data_doctor – Non-mutating diagnostics and remediation guidance

Mail – Search messages, retrieve metadata and plain-text content (capped). Plan and apply creation of new drafts.

Messages – Search chats by display name, retrieve bounded transcripts (capped). Plan and apply sending text messages.

Hide My Email – Search and retrieve inferred aliases from local Mail metadata (not an authoritative iCloud inventory).

Voice Memos – Search recordings, retrieve metadata and transcripts, export .m4a audio to a directory.

Apple Notes – Search notes, retrieve metadata and paginated plain-text content (capped). Plan and apply creating new notes or appending to existing ones.

iCloud Drive – Search files/folders, retrieve metadata and text file content (capped). Plan and apply creating or appending to text files.

Calendar – Search events by title within a time window, retrieve event details. Plan and apply creating new events.

Contacts – Search by name/organization, retrieve contact details. Plan and apply creating new contacts.

Photos – Search by filename, retrieve asset metadata, export assets to a directory. Plan and apply importing new photos/videos.

Reminders – Search by title, list due reminders, retrieve reminder notes. Plan and apply creating, completing, or updating due dates.

Additional read-only access (search and metadata retrieval) for: Safari Bookmarks/Reading List, Apple Shortcuts, Apple Books annotations, Podcasts, Apple Music, and Apple TV.

Key design constraints:

All reads use opaque signed handles; raw IDs and file paths are never exposed
Broad/wildcard queries are rejected to prevent bulk data extraction
Content is always capped (default 4,000 characters)
Write operations follow a plan → approval token → explicit confirm-apply flow
No network credentials, OAuth, iCloud APIs, or keychains are used

local-apple-data

Local-first Apple data access for Codex and other MCP clients.

This project provides a privacy-gated CLI and MCP server for locally synced:

Mail.app mail, including iCloud and Gmail accounts synced locally through Mail.app
Messages chats synced locally through Messages.app
Inferred Hide My Email aliases observed in local Mail address metadata
Voice Memos synced locally through Voice Memos.app
Safari bookmarks, Reading List items, and bookmark folders synced locally through Safari/iCloud
Apple Shortcuts shortcut, folder, and exact selected-folder shortcut metadata through the local shortcuts CLI
Apple Books library metadata and selected-book annotations synced through Books/iCloud
Apple Podcasts show and episode metadata synced through Podcasts/iCloud
Apple Music track and playlist metadata synced through Music/Apple Music
Apple TV item, playlist, and selected-playlist item metadata synced through TV/iCloud
Apple Freeform board, folder, selected-folder board, and selected-folder child-folder metadata synced through Freeform/iCloud
Apple Notes note, folder, and exact selected-folder item metadata
Apple Calendar
Apple Reminders
Apple Contacts
Apple Photos asset, regular-album, exact selected-album asset metadata, and regular-album management
iCloud Drive local files and folders
A bounded home-directory Filesystem rooted at the operator home directory

The current release is local-only and read-mostly. Its plan/apply surfaces cover approved exact operations in Reminders, iCloud Drive, Calendar, Contacts excluding note mutation, Notes (including rich-text body create/replace and exact empty child-folder move), Mail, Photos, Messages, the bounded home-directory Filesystem, and one exact identifier-bound Shortcuts run. Every apply requires its matching approval token and explicit confirmation; the exact operation inventory and per-operation limits are maintained in docs/MUTATION_GATES.md.

Contacts note plan/apply contracts are designed and synthetic-testable, but they are not a usable live mutation surface: this local signed helper lacks Apple's restricted Contacts-notes entitlement, so every note operation fails closed with contacts_note_unavailable before mutation. Contact free-form labels are implemented up to 255 characters; control characters and oversize labels are refused.

The plugin does not use the Gmail connector, Gmail API, IMAP credentials, OAuth, app passwords, iCloud.com, browser sessions, keychain credentials, private iCloud web APIs, or any network mail service.

Current Status

The MCP server, local skill/plugin packaging, exact-handle retrieval, the approved apply paths summarized above, and synthetic runtime verification are implemented. That includes the bounded home-directory Filesystem and exact identifier-bound Shortcuts run gate; “approved Contacts” here excludes the live-unavailable Contacts note operations described above.

Real-machine smoke stays schema-only unless a user intentionally requests a specific metadata search, selects an exact returned handle for detail/content/export, or explicitly approves an operation generated from a matching plan.

Implemented now:

Repo guidance and privacy model
local-apple-data health --json with redacted broad-surface readiness summaries, schema-only Mail/Messages/Voice Memos/Books/Podcasts/Freeform/Notes/Reminders checks, Safari bookmarks and iCloud Drive root checks, Shortcuts CLI and Music.app/TV.app automation availability, and non-prompting access requirements for framework-backed surfaces
local-apple-data doctor --json with redacted non-mutating remediation guidance
local-apple-data mail search/get metadata commands, with optional exact --mailbox-handle <mail:mailbox:v1:...> filtering for one selected mailbox
local-apple-data mail mailbox-messages --json --handle <mail:mailbox:v1:...> --after <date-or-timestamp> [--before <date-or-timestamp>] for date-bounded metadata-only messages in one selected mailbox
Metadata-only content_status hints in Mail search results so agents can prefer locally retrievable messages before exact content calls
local-apple-data mail body-search --json --query <text> --after <date-or-timestamp> [--before <date-or-timestamp>] for date-bounded local Mail body discovery with capped redacted snippets and no full-body output
local-apple-data mail attachment-search --json --query <filename-or-mime-or-content> --after <date-or-timestamp> [--before <date-or-timestamp>] [--include-content] [--include-ocr] for date-bounded Mail attachment filename/MIME metadata discovery plus opt-in text/PDF/OCR redacted snippets, exact attachment handles, and no bytes
local-apple-data mail advanced-search --json --query <text> --scope subject|from|to|cc|bcc|body|attachment_filename --after <date-or-timestamp> [--before <date-or-timestamp>] for date-bounded subject/header/body/attachment metadata discovery with masked headers and capped snippets
local-apple-data mail fts-build --json --after <date-or-timestamp> [--before <date-or-timestamp>] --confirm-index [--cursor <cursor>] [--include-attachments] [--include-ocr] for opt-in private local Mail FTS indexing; this writes a durable local content cache but returns only counts, next_cursor, and an opaque index ref, not the cache path. Use --reset only on the first build page; continuation cursors must run without reset.
local-apple-data mail fts-search --json --query <text> --after <date-or-timestamp> [--before <date-or-timestamp>] [--scope subject|from|to|cc|bcc|body|attachment_filename|attachment_content] for date-bounded read-only search of the opt-in Mail FTS index with capped redacted snippets, live-row/date/content-state revalidation, and no full body, bytes, or cache path output
local-apple-data mail content --json --handle <mail:message:v2:...> --max-chars 4000 [--offset <n>] for exact-handle local Mail plain-text content with paging metadata
local-apple-data mail unsubscribe-metadata --json --handle <mail:message:v2:...> [--include-body-links] and MCP mail_get_unsubscribe_metadata(handle, include_body_links=false) for exact-message, read-only List-Unsubscribe/List-Unsubscribe-Post/List-Help detail. Output contains only ordered allowlisted http(s)/mailto endpoints plus opaque account/mailbox refs; only HTTPS paired with the exact RFC 8058 post header is classified as one_click. The explicit body-link opt-in returns at most five conservatively matched anchor URLs as body_link, always manual_required; it returns no body, anchor labels, or unrelated links.
local-apple-data mail mailboxes --json --query <text> and local-apple-data mail mailbox --json --handle <mail:mailbox:v1:...> for bounded Mail move target selection by opaque mailbox handle and opaque account refs
local-apple-data mail senders --json --query <text> and local-apple-data mail sender --json --handle <mail:sender:v1:...> for bounded configured Mail sender metadata selection with masked email previews only; search matches returned-safe masked fields only
local-apple-data mail signatures --json --query <text> and local-apple-data mail signature --json --handle <mail:signature:v1:...> for bounded Mail signature metadata without signature bodies
local-apple-data mail template-create/templates/template/template-delete for plugin-local Mail template management, plus local-apple-data mail plan-search-triage for capped FTS-result triage planning into exact selected message handles
local-apple-data mail attachments --json --handle <mail:message:v2:...> for exact selected-message attachment metadata with opaque mail:attachment:v1: handles
local-apple-data mail export-attachment --json --message-handle <mail:message:v2:...> --handle <mail:attachment:v1:...> --output-dir <dir> for exact local Mail attachment export without inline bytes or source message paths
local-apple-data mail plan --json --operation create-draft --to <address> --subject <subject> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] for non-mutating future draft-create previews with optional exact sender selection, bounded caller-selected local file attachments, file identity plus content SHA-256 approval binding, idempotency where safe, and approval metadata
local-apple-data mail apply --json --operation create-draft --to <address> --subject <subject> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] --approval-token <token> --confirm-apply for the approved Mail create-draft path, with optional exact sender selection and bounded caller-selected local file attachments, private validated attachment-copy automation handoff, selected-sender/attachment automation read-back, and local Drafts read-back verification when the Drafts store exposes the saved draft
local-apple-data mail plan --json --operation send-message --to <address> --subject <subject> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] for non-mutating future outbound-send previews with optional exact sender selection, optional bounded caller-selected local file attachments, irreversible-send metadata, non-retry-safe status, and approval metadata
local-apple-data mail apply --json --operation send-message --to <address> --subject <subject> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] --approval-token <token> --confirm-apply for the approved Mail send-message path, with optional exact sender selection, optional bounded caller-selected local file attachments, private validated attachment-copy automation handoff, selected-sender and Mail-derived attachment-count confirmation before send, local Sent-copy read-back when available, no draft save, and no body/path/byte/full-sender echo in apply output
local-apple-data mail plan --json --operation reply-message --message-handle <mail:message:v2:...> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] for non-mutating exact-message sender-only reply previews with optional exact sender selection, optional bounded caller-selected local file attachments, current source-message state binding, and irreversible-send metadata
local-apple-data mail apply --json --operation reply-message --message-handle <mail:message:v2:...> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] --approval-token <token> --confirm-apply for the approved Mail sender-only reply path, scoped by Mail account, mailbox, and RFC Message-ID, with optional exact sender selection, optional bounded caller-selected local file attachments, stale-state refusal, no direct-recipient override, local Sent-copy read-back when available, and no body/path/byte/full-sender echo in apply output
local-apple-data mail plan --json --operation reply-all-message --message-handle <mail:message:v2:...> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] for non-mutating exact-message reply-all previews with optional exact sender selection, optional bounded caller-selected local file attachments, current source-message state binding, and irreversible-send metadata
local-apple-data mail apply --json --operation reply-all-message --message-handle <mail:message:v2:...> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] --approval-token <token> --confirm-apply for the approved Mail exact-message reply-all path, scoped by Mail account, mailbox, and RFC Message-ID, with optional exact sender selection, optional bounded caller-selected local file attachments, stale-state refusal, no direct-recipient override, local Sent-copy read-back when available, and no body/path/byte/full-sender echo in apply output
local-apple-data mail plan --json --operation forward-message --message-handle <mail:message:v2:...> --to <address> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] [--include-source-attachments] for non-mutating exact-message forward previews with optional exact sender selection, optional bounded caller-selected local file attachments, current source-message state binding, default source attachment/non-body-part refusal, opt-in source attachment-like part preservation, irreversible-send metadata, and approval metadata
local-apple-data mail apply --json --operation forward-message --message-handle <mail:message:v2:...> --to <address> --body-text <text> [--sender-handle <mail:sender:v1:...>] [--attachment-path <local-file>] [--include-source-attachments] --approval-token <token> --confirm-apply for the approved Mail exact-message forward path, scoped by Mail account, nested mailbox path, and RFC Message-ID, with optional exact sender selection, optional bounded caller-selected local file attachments, optional source attachment-like part preservation, stale-state refusal, selected-sender and pre-send Mail attachment-count verification, local Sent-copy read-back when available, and no body/source-content/path/byte/full-sender echo in apply output
local-apple-data mail plan --json --operation mark-read|mark-unread|flag-message|unflag-message|archive-message|move-message|trash-message --message-handle <mail:message:v2:...> [--message-handle <mail:message:v2:...> ...] [--target-mailbox-handle <mail:mailbox:v1:...>] for non-mutating exact-message or capped exact bulk read/flag/archive/move/trash triage previews with current-state binding, idempotency, and approval metadata
local-apple-data mail apply --json --operation mark-read|mark-unread|flag-message|unflag-message|archive-message|move-message|trash-message --message-handle <mail:message:v2:...> [--message-handle <mail:message:v2:...> ...] [--target-mailbox-handle <mail:mailbox:v1:...>] --approval-token <token> --confirm-apply for the approved Mail read/flag/archive/move/trash triage path, scoped by Mail account, mailbox, exact target mailbox, and RFC Message-ID, with same-account Archive/Trash resolution, exact target-mailbox resolution including cross-account exact targets, capped exact bulk preflight, stale-state refusal, no permanent deletion, partial reporting, and local read-back verification
local-apple-data mail plan-mailbox/apply-mailbox for exact sender-selected synthetic top-level LAD-TEST-* mailbox create/rename and source-gated empty synthetic mailbox delete
local-apple-data mail plan-cleanup/apply-cleanup for source-gated exact synthetic LAD-TEST-* permanent-delete planning/apply and synthetic-only empty Trash/Junk planning/apply with Mail-idle, exact target-state binding, and absence proof
local-apple-data messages search/get commands for local Messages chat display-name metadata and exact bounded transcripts, including modern local attributedBody plaintext fallback when message.text is empty
local-apple-data messages participants --json --handle <messages:chat:v1:...> and local-apple-data messages participant --json --chat-handle <messages:chat:v1:...> --handle <messages:participant:v1:...> for exact selected-chat participant metadata; list output returns opaque participant handles without phone/email previews, and full participant identifiers are exact participant-handle detail only
local-apple-data messages attachments --json --handle <messages:chat:v1:...> for exact selected-chat attachment metadata with opaque messages:attachment:v1: handles
local-apple-data messages export-attachment --json --chat-handle <messages:chat:v1:...> --handle <messages:attachment:v1:...> --output-dir <dir> for exact local Messages attachment export without inline bytes or source media paths
local-apple-data messages plan --json --operation send-text --handle <messages:chat:v1:...> --body-text <text> for non-mutating future send-text previews with chat-state, body-hash, idempotency, and approval metadata
local-apple-data messages apply --json --operation send-text --handle <messages:chat:v1:...> --body-text <text> --approval-token <token> --confirm-apply for the approved Messages send-text path, with Messages.app automation, stale chat-state refusal, ghost-row detection, and local read-back verification without echoing the sent body in apply output
local-apple-data messages plan --json --operation send-file --handle <messages:chat:v1:...> --file-path <path> for non-mutating future exact-chat file-send previews with file metadata, file-identity binding, idempotency, and approval metadata without returning local file paths or bytes
local-apple-data messages apply --json --operation send-file --handle <messages:chat:v1:...> --file-path <path> --approval-token <token> --confirm-apply for the approved Messages send-file path, with Messages.app automation, stale chat/file-state refusal, ghost-row detection, and local attachment read-back verification without returning file bytes or local paths
local-apple-data hide-my-email search/get commands for inferred Hide My Email aliases observed in local Mail address metadata
local-apple-data voice-memos search/get/export commands for local Voice Memos title/filename metadata, exact existing embedded transcripts, and exact-handle .m4a export to a caller-selected output directory
local-apple-data safari search/get/folders/folder/folder-items commands for local Safari bookmarks, Reading List title/URL metadata, bookmark-folder metadata, exact selected URL detail, and exact selected-folder direct child metadata by opaque handle
local-apple-data shortcuts search/get/folder-items commands for local Apple Shortcuts shortcut/folder name metadata and exact selected-folder shortcut metadata by opaque handle, without opening, signing, exporting, or returning shortcut bodies
local-apple-data shortcuts plan/apply --json --operation run --handle <shortcuts:item:v1:...> for one exact identifier-bound shortcut run through the approval-token/explicit-confirmation gate, argv-only invocation, and a hard execution timeout. Success proves only that the named shortcut was invoked; arbitrary shortcut side effects are not read back.
local-apple-data books search/get/annotations commands for local Apple Books title/author/genre metadata and exact selected-book annotation text by opaque handle, without extracting book/chapter text or returning raw asset IDs, annotation UUIDs, or local file paths
local-apple-data podcasts search/get/episodes/episode commands for local Apple Podcasts show metadata, selected-show episode metadata, and exact selected-episode bounded descriptions by opaque handle, without returning transcripts, audio bytes, feed/enclosure URLs, raw identifiers, or local download paths
local-apple-data music search/get/playlists/playlist/playlist-tracks commands for local Apple Music track, playlist, and exact selected playlist-track metadata by opaque handle, without returning audio bytes, lyrics, file paths, raw identifiers, play history, ratings, or broad playlist track dumps
local-apple-data tv search/get/playlists/playlist/playlist-items commands for local Apple TV item, playlist, and exact selected-playlist item metadata by opaque handle, without returning video bytes, file paths, artwork, descriptions, playback state, watched state, ratings, raw identifiers, or broad playlist item dumps
local-apple-data freeform boards/get/folders/folder/folder-boards/child-folders commands for local Apple Freeform recent-board, folder-title, exact selected-folder board, and exact selected-folder child-folder metadata by opaque handle, without returning board BLOBs, decoded board items, asset bytes, previews, collaboration payloads, raw identifiers, or board content
local-apple-data notes search/get metadata commands and local-apple-data notes folders/folder/folder-items/folder-tree exact folder metadata/direct-item/tree commands
local-apple-data notes content --json --handle <notes:note:v2:...> --max-chars 4000 --offset 0 for exact-handle local Notes content (plain text by default; add --content-format html for the bounded rich-text HTML body plus its extracted visible text), with next_offset pagination for long imported notes
local-apple-data notes attachments --json --handle <notes:note:v2:...> for exact selected-note attachment metadata with opaque notes:attachment:v1: handles
local-apple-data notes export-attachment --json --handle <notes:attachment:v1:...> --output-dir <dir> for exact local Notes attachment export without inline bytes or source media paths
local-apple-data notes plan --json --operation create --title <title> --body-text <text> for non-mutating future note-create previews with idempotency and approval metadata
local-apple-data notes apply --json --operation create --title <title> --body-text <text> [--folder-handle <notes:folder:v1:...>] --approval-token <token> --confirm-apply for the approved Notes create-note path in the default folder or one exact selected folder, with Notes.app automation and exact-content read-back verification
local-apple-data notes plan --json --operation create-folder --folder-handle <notes:folder:v1:...> --title <folder-title> for non-mutating future exact child-folder create previews under one selected normal parent folder
local-apple-data notes apply --json --operation create-folder --folder-handle <notes:folder:v1:...> --title <folder-title> --approval-token <token> --confirm-apply for the approved Notes exact child-folder create path, with Notes.app automation, same-parent idempotency, metadata-only read-back, and selected-parent proof
local-apple-data notes plan --json --operation delete-folder --folder-handle <notes:folder:v1:...> --expected-current-sha256 <folder-title-sha256> for non-mutating future exact empty child-folder delete previews
local-apple-data notes apply --json --operation delete-folder --folder-handle <notes:folder:v1:...> --expected-current-sha256 <folder-title-sha256> --approval-token <token> --confirm-apply for the approved Notes exact empty child-folder delete path, with title-hash drift checks, empty-folder rechecks, scoped Notes.app automation, and absence proof
local-apple-data notes plan --json --operation append-text --handle <notes:note:v2:...> --expected-current-sha256 <sha256> --body-text <text> for non-mutating future note append previews with expected-current-content binding
local-apple-data notes apply --json --operation append-text --handle <notes:note:v2:...> --expected-current-sha256 <sha256> --body-text <text> --approval-token <token> --confirm-apply for the approved Notes append-text path, with drift refusal and exact-content read-back verification
local-apple-data notes plan --json --operation replace-text --handle <notes:note:v2:...> --expected-current-sha256 <sha256> --body-text <text> for non-mutating future note plaintext replacement previews with expected-current-content binding
local-apple-data notes apply --json --operation replace-text --handle <notes:note:v2:...> --expected-current-sha256 <sha256> --body-text <text> --approval-token <token> --confirm-apply for the approved Notes replace-text path, with drift refusal, locked/shared-note refusal, and exact-content read-back verification
local-apple-data notes plan --json --operation move-to-folder --handle <notes:note:v2:...> --folder-handle <notes:folder:v1:...> --expected-current-sha256 <sha256> for non-mutating exact-note/exact-folder move previews with same-account and current-content binding
local-apple-data notes apply --json --operation move-to-folder --handle <notes:note:v2:...> --folder-handle <notes:folder:v1:...> --expected-current-sha256 <sha256> --approval-token <token> --confirm-apply for the approved Notes move-to-folder path, with drift refusal, same-account normal-folder proof, Notes.app scoped move automation, and folder read-back verification
local-apple-data notes plan --json --operation delete --handle <notes:note:v2:...> --expected-current-sha256 <sha256> for non-mutating future note delete previews with expected-current-content binding
local-apple-data notes apply --json --operation delete --handle <notes:note:v2:...> --expected-current-sha256 <sha256> --approval-token <token> --confirm-apply for the approved Notes exact-note delete path, with drift refusal, locked/shared-note refusal, and absence read-back verification
local-apple-data icloud-drive search/root/get metadata commands for local iCloud Drive items by filename or the configured root
local-apple-data icloud-drive list --json --handle <icloud:file:v1:...> [--limit 20] for exact selected-folder direct child metadata listing without content or raw paths
local-apple-data icloud-drive tree --json --handle <icloud:file:v1:...> [--depth 2] [--limit 50] for bounded recursive metadata listing under one exact selected folder without content, raw paths, symlink traversal, or package traversal
local-apple-data icloud-drive content --json --handle <icloud:file:v1:...> --max-chars 4000 for exact-handle local iCloud Drive text-file content
local-apple-data icloud-drive export --json --handle <icloud:file:v1:...> --output-dir <dir> [--filename <name>] for exact-handle local iCloud Drive regular-file export with selected source identity binding and without inline bytes, source paths, or arbitrary symlink output ancestors
local-apple-data icloud-drive plan --json --operation create-text --parent-handle <icloud:file:v1:...> --filename <name.md> --content-text <text> for non-mutating future text-file create previews with idempotency and approval metadata
local-apple-data icloud-drive apply --json --operation create-text --parent-handle <icloud:file:v1:...> --filename <name.md> --content-text <text> --approval-token <token> --confirm-apply for the approved iCloud Drive create-text path, with exclusive create and read-back verification
local-apple-data icloud-drive plan --json --operation create-folder --parent-handle <icloud:file:v1:...> --folder-name <folder-name> for non-mutating future folder-create previews with idempotency and approval metadata
local-apple-data icloud-drive apply --json --operation create-folder --parent-handle <icloud:file:v1:...> --folder-name <folder-name> --approval-token <token> --confirm-apply for the approved iCloud Drive create-folder path, with no-follow parent validation, exclusive mkdir, metadata-only read-back, and existing-directory idempotency
local-apple-data icloud-drive plan --json --operation rename-folder --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> --folder-name <new-folder-name> for non-mutating exact folder rename previews with directory metadata binding, non-empty support, and no overwrite
local-apple-data icloud-drive apply --json --operation rename-folder --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> --folder-name <new-folder-name> --approval-token <token> --confirm-apply for the approved iCloud Drive exact folder rename path, with no-follow source validation, metadata drift refusal, no-overwrite target rename, non-empty child preservation, and metadata-only read-back
local-apple-data icloud-drive plan --json --operation trash-folder --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> for non-mutating exact folder Trash previews with directory metadata binding and no content or parent input
local-apple-data icloud-drive apply --json --operation trash-folder --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> --approval-token <token> --confirm-apply for the approved iCloud Drive exact folder Trash path, including non-empty directories, with no-follow source validation, metadata drift refusal, recoverable Trash move, original absence proof, child preservation, and metadata-only read-back
local-apple-data icloud-drive plan --json --operation delete-folder --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> for non-mutating exact selected-folder permanent-delete previews with directory metadata binding, private bounded tree binding, and no content, parent, or filename input
local-apple-data icloud-drive apply --json --operation delete-folder --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> --approval-token <token> --confirm-apply for the approved iCloud Drive exact selected-folder permanent-delete path, with no-follow source validation, private bounded tree binding, hidden/symlink/package/tree-size refusal, metadata/tree drift refusal, hidden staging identity proof, bounded permanent staged-tree removal, original absence proof, and metadata-only read-back
local-apple-data icloud-drive plan --json --operation delete-text --handle <icloud:file:v1:...> --expected-current-sha256 <content-sha256> for non-mutating exact text-file permanent-delete previews with current SHA-256 and exact file identity approval binding
local-apple-data icloud-drive apply --json --operation delete-text --handle <icloud:file:v1:...> --expected-current-sha256 <content-sha256> --approval-token <token> --confirm-apply for the approved iCloud Drive exact text-file permanent-delete path, with root-aware plan recomputation, exact file identity approval binding, stale token replay refusal for recreated same-path/same-content files, current-content drift refusal, random-only hidden staging identity proof, permanent unlink, original absence proof, and no content/hash/path return
local-apple-data icloud-drive plan --json --operation move-folder --handle <icloud:file:v1:...> --parent-handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> [--folder-name <new-folder-name>] for non-mutating exact folder move previews with directory metadata binding, exact target parent binding, non-empty support, and no content input
local-apple-data icloud-drive apply --json --operation move-folder --handle <icloud:file:v1:...> --parent-handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> [--folder-name <new-folder-name>] --approval-token <token> --confirm-apply for the approved iCloud Drive exact folder move path, with no-follow source and target-parent validation, metadata drift refusal, descendant-parent refusal, no-overwrite target proof, source/target presence proof, non-empty child preservation, and metadata-only read-back
local-apple-data icloud-drive plan --json --operation copy-folder --handle <icloud:file:v1:...> --parent-handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> [--folder-name <new-folder-name>] for non-mutating exact selected-folder copy previews with directory metadata binding, exact target parent binding, private bounded source-tree binding, and no content input
local-apple-data icloud-drive apply --json --operation copy-folder --handle <icloud:file:v1:...> --parent-handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> [--folder-name <new-folder-name>] --approval-token <token> --confirm-apply for the approved iCloud Drive exact selected-folder copy path, with no-follow source and target-parent validation, bounded non-empty tree support, hidden/symlink/package refusal, metadata/tree drift refusal, no-overwrite target proof, source preservation proof, target presence proof, and metadata-only read-back
local-apple-data icloud-drive plan --json --operation append-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> --content-text <text> for non-mutating future text append previews with expected-current-content binding
local-apple-data icloud-drive apply --json --operation append-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> --content-text <text> --approval-token <token> --confirm-apply for the approved iCloud Drive append-text path, with drift refusal and read-back hash verification
local-apple-data icloud-drive plan --json --operation replace-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> --content-text <text> for non-mutating full-text replacement previews with expected-current-content binding
local-apple-data icloud-drive apply --json --operation replace-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> --content-text <text> --approval-token <token> --confirm-apply for the approved iCloud Drive replace-text path, with drift refusal, atomic same-directory replacement, and read-back hash verification
local-apple-data icloud-drive plan --json --operation trash-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> for non-mutating recoverable Trash previews with expected-current-content binding
local-apple-data icloud-drive apply --json --operation trash-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> --approval-token <token> --confirm-apply for the approved iCloud Drive trash-text path, with drift refusal, post-swap SHA verification, recoverable Trash move, no raw Trash path return, and original-handle absence proof
local-apple-data icloud-drive plan --json --operation rename-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> --filename <new-name.md> for non-mutating exact-file rename previews with expected-current-content binding and no overwrite
local-apple-data icloud-drive apply --json --operation rename-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> --filename <new-name.md> --approval-token <token> --confirm-apply for the approved iCloud Drive rename-text path, with no-overwrite target reservation, no-follow swap, post-swap SHA/identity proof, rollback on verifiable drift before target proof, no rollback after verified target proof, and source-handle absence proof
local-apple-data icloud-drive plan --json --operation copy-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> [--parent-handle <icloud:file:v1:...>] --filename <copy-name.md> for non-mutating exact-file copy previews with no source mutation and no overwrite
local-apple-data icloud-drive apply --json --operation copy-text --handle <icloud:file:v1:...> --expected-current-sha256 <sha256> [--parent-handle <icloud:file:v1:...>] --filename <copy-name.md> --approval-token <token> --confirm-apply for the approved iCloud Drive copy-text path, with exclusive create, target read-back hash proof, post-copy source SHA recheck, and source-presence proof
local-apple-data icloud-drive plan --json --operation move-text --handle <icloud:file:v1:...> --parent-handle <icloud:file:v1:...> --expected-current-sha256 <sha256> [--filename <new-name.md>] for non-mutating exact-file move previews with exact destination folder selection and no overwrite
local-apple-data icloud-drive apply --json --operation move-text --handle <icloud:file:v1:...> --parent-handle <icloud:file:v1:...> --expected-current-sha256 <sha256> [--filename <new-name.md>] --approval-token <token> --confirm-apply for the approved iCloud Drive move-text path, with no-overwrite target reservation, no-follow swap, post-swap SHA/identity proof, rollback on verifiable drift before target proof, no rollback after verified target proof, and source-handle absence proof
local-apple-data icloud-drive plan --json --operation rename-file --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> --filename <new-name.bin> for non-mutating exact regular-file rename previews with expected metadata binding, no content/hash return, and no overwrite
local-apple-data icloud-drive apply --json --operation rename-file --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> --filename <new-name.bin> --approval-token <token> --confirm-apply for the approved iCloud Drive regular-file rename path, with non-text non-package regular-file validation, no-overwrite target reservation, no-follow swap, metadata-only read-back, and source-handle absence proof
local-apple-data icloud-drive plan --json --operation copy-file --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> [--parent-handle <icloud:file:v1:...>] --filename <copy-name.bin> for non-mutating exact regular-file copy previews with expected metadata binding, no content/hash return, no source mutation, and no overwrite
local-apple-data icloud-drive apply --json --operation copy-file --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> [--parent-handle <icloud:file:v1:...>] --filename <copy-name.bin> --approval-token <token> --confirm-apply for the approved iCloud Drive regular-file copy path, with exclusive create, target identity/size proof, source metadata recheck, metadata-only read-back, and source-presence proof
local-apple-data icloud-drive plan --json --operation move-file --handle <icloud:file:v1:...> --parent-handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> [--filename <new-name.bin>] for non-mutating exact regular-file move previews with exact destination folder selection, expected metadata binding, no content/hash return, and no overwrite
local-apple-data icloud-drive apply --json --operation move-file --handle <icloud:file:v1:...> --parent-handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> [--filename <new-name.bin>] --approval-token <token> --confirm-apply for the approved iCloud Drive regular-file move path, with non-text non-package regular-file validation, no-overwrite target reservation, no-follow swap, metadata-only read-back, and source-handle absence proof
local-apple-data icloud-drive plan --json --operation import-file --parent-handle <icloud:file:v1:...> --source-file <path> [--filename <new-name.bin>] for non-mutating exact regular-file import previews with private source identity/content binding and no source path/hash return
local-apple-data icloud-drive apply --json --operation import-file --parent-handle <icloud:file:v1:...> --source-file <path> [--filename <new-name.bin>] --approval-token <token> --confirm-apply for the approved iCloud Drive regular-file import path, with non-text non-package source validation outside iCloud Drive, no-overwrite target proof, metadata-only read-back, and source preservation proof
local-apple-data icloud-drive plan --json --operation replace-file --handle <icloud:file:v1:...> --source-file <path> --expected-current-sha256 <metadata-sha256> for non-mutating exact regular-file replace previews with private source identity/content binding, extension match, and no source path/hash return
local-apple-data icloud-drive apply --json --operation replace-file --handle <icloud:file:v1:...> --source-file <path> --expected-current-sha256 <metadata-sha256> --approval-token <token> --confirm-apply for the approved iCloud Drive regular-file replace path, with target metadata drift refusal, source preservation proof, byte replacement proof, metadata-only target read-back, and no content/hash/path return
local-apple-data icloud-drive plan --json --operation trash-file --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> for non-mutating exact regular-file Trash previews with expected metadata binding and no content/hash/path return
local-apple-data icloud-drive apply --json --operation trash-file --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> --approval-token <token> --confirm-apply for the approved iCloud Drive regular-file Trash path, with non-text non-package regular-file validation, recoverable Trash move, original absence proof, metadata-only read-back, and no raw Trash path return
local-apple-data icloud-drive plan --json --operation delete-file --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> for non-mutating exact regular-file permanent-delete previews with expected metadata binding and no content/hash/path return
local-apple-data icloud-drive apply --json --operation delete-file --handle <icloud:file:v1:...> --expected-current-sha256 <metadata-sha256> --approval-token <token> --confirm-apply for the approved iCloud Drive regular-file permanent-delete path, with non-text non-package regular-file validation, hidden staging identity proof, permanent unlink, original absence proof, metadata-only read-back, and no raw staging or Trash path return
local-apple-data calendar search/get commands for local Calendar events by title through EventKit
local-apple-data calendar participants --json --handle <calendar:event:v1:...> and local-apple-data calendar participant --json --event-handle <calendar:event:v1:...> --participant-handle <calendar:participant:v1:...> for exact Calendar participant metadata and selected participant detail; list output returns opaque participant handles, role/status/type/current-user flags, and presence flags only, while exact detail may return bounded participant name/URL
local-apple-data calendar request-access --json to trigger the one-time macOS Calendar full-access prompt for the stable local EventKit helper app; normal Calendar reads do not prompt and fail closed if full access is absent
local-apple-data calendar calendars --json --query <calendar title> [--include-default] and local-apple-data calendar calendar --json --handle <calendar:calendar:v1:...> for exact Calendar target metadata without raw EventKit identifiers
local-apple-data calendar events --json --handle <calendar:calendar:v1:...> --start <YYYY-MM-DD-or-ISO> --end <YYYY-MM-DD-or-ISO> [--limit 20] for capped event metadata from one exact selected Calendar target; output returns opaque event handles and presence/count flags only, not notes, location text, attendee names/URLs, event URL values, raw EventKit identifiers, or raw alarm detail
local-apple-data calendar plan-calendar/apply-calendar for synthetic LAD-TEST-* Calendar calendar create/rename/delete by exact source or target calendar:calendar:v1: handle, with safe-hash binding, duplicate-title refusal, bounded empty-calendar safety-window proof for rename/delete, event-only delete refusal for calendars that may contain reminders, EventKit read-back, and delete absence proof.
local-apple-data calendar plan --json --operation create --title <title> [--calendar-title <calendar> | --calendar-handle <calendar:calendar:v1:...> | --use-default-calendar] --start-date <ISO> --end-date <ISO> [--time-zone <IANA>] [--availability busy|free|tentative|unavailable] [--event-url <allow-listed-url>] [--structured-location <json>] [--all-day] [--alarm-offsets-minutes -10,0 | --alarm-absolute-dates <ISO>] [--recurrence-frequency daily|weekly|monthly|yearly (--recurrence-count <2-52> | --recurrence-end-date <ISO-with-timezone> | --recurrence-unbounded) [--recurrence-interval <1-4>]] for non-mutating future timed or explicit all-day event create previews with idempotency and approval metadata; --use-default-calendar is plan-only and resolves the current default calendar to an exact calendar_handle, --time-zone is timed-event only, availability is support-mask validated during apply, event URL scheme must be http, https, mailto, or tel with hash-only read-back, structured location is one bounded title plus optional paired coordinates/radius, relative/absolute alarm modes are mutually exclusive, and recurrence is simple count-, end-date-, or explicit-unbounded
local-apple-data calendar apply --json --operation create --title <title> [--calendar-title <calendar> | --calendar-handle <calendar:calendar:v1:...>] --start-date <ISO> --end-date <ISO> [--time-zone <IANA>] [--availability busy|free|tentative|unavailable] [--event-url <allow-listed-url>] [--structured-location <json>] [--all-day] [--alarm-offsets-minutes -10,0 | --alarm-absolute-dates <ISO>] [--recurrence-frequency daily|weekly|monthly|yearly (--recurrence-count <2-52> | --recurrence-end-date <ISO-with-timezone> | --recurrence-unbounded) [--recurrence-interval <1-4>]] --approval-token <token> --confirm-apply for the approved Calendar create-event path, with EventKit apply, read-back verification, hash-only URL proof when an event URL is requested, structured-location read-back proof when requested, and recurrence count/end-date/unbounded read-back proof when requested
local-apple-data calendar plan --json --operation update --handle <calendar:event:v1:...> [--target-calendar-handle <calendar:calendar:v1:...>] --expected-title <current> --expected-calendar-title <calendar> --expected-start-date <ISO> --expected-end-date <ISO> [--expected-time-zone <IANA>] [--expected-availability busy|free|tentative|unavailable|not_supported] [--expected-structured-location <json>] [--expected-event-url-present --expected-event-url-sha256 <sha256>] [--expected-alarm-offsets-minutes -10,0 | --expected-alarm-absolute-dates <ISO>] --title <new> --start-date <ISO> --end-date <ISO> [--time-zone <IANA>] [--availability busy|free|tentative|unavailable] [--event-url <allow-listed-url> | --clear-event-url] [--structured-location <json> | --clear-structured-location] [--alarm-offsets-minutes -10,0 | --alarm-absolute-dates <ISO>] [--recurrence-frequency daily|weekly|monthly|yearly (--recurrence-count <2-52> | --recurrence-end-date <ISO-with-timezone> | --recurrence-unbounded) [--recurrence-interval <1-4>]] for non-mutating exact-event update or calendar-move previews with expected-state binding; changing availability requires --expected-availability, changing structured location can bind --expected-structured-location, clearing structured location requires --expected-structured-location plus empty proposed location, changing or clearing an existing URL requires URL presence/hash binding, and recurrence update is limited to adding one simple count-, end-date-, or explicit-unbounded recurrence to a currently non-recurring event
local-apple-data calendar apply --json --operation update --handle <calendar:event:v1:...> [--target-calendar-handle <calendar:calendar:v1:...>] --expected-title <current> --expected-calendar-title <calendar> --expected-start-date <ISO> --expected-end-date <ISO> [--expected-time-zone <IANA>] [--expected-availability busy|free|tentative|unavailable|not_supported] [--expected-structured-location <json>] [--expected-event-url-present --expected-event-url-sha256 <sha256>] [--expected-alarm-offsets-minutes -10,0 | --expected-alarm-absolute-dates <ISO>] --title <new> --start-date <ISO> --end-date <ISO> [--time-zone <IANA>] [--availability busy|free|tentative|unavailable] [--event-url <allow-listed-url> | --clear-event-url] [--structured-location <json> | --clear-structured-location] [--alarm-offsets-minutes -10,0 | --alarm-absolute-dates <ISO>] [--recurrence-frequency daily|weekly|monthly|yearly (--recurrence-count <2-52> | --recurrence-end-date <ISO-with-timezone> | --recurrence-unbounded) [--recurrence-interval <1-4>]] --approval-token <token> --confirm-apply for the approved Calendar exact-event update/move path, with stale-state refusal, support-mask validation, URL hash read-back verification or URL absence proof when requested, structured-location read-back proof or absence proof when requested, recurrence read-back verification when requested, and read-back verification
Calendar recurrence selector flags for create/update plan/apply are yearly/monthly/weekly scoped: --recurrence-weekdays with weekly recurrence, monthly recurrence, or yearly week-of-year recurrence; --recurrence-month-days or --recurrence-month-weekdays only with monthly recurrence and never together; --recurrence-year-months, --recurrence-year-days, and --recurrence-year-weeks are yearly-only top-level selectors; --recurrence-year-month-days and --recurrence-year-month-weekdays are yearly-only subselectors that require --recurrence-year-months, are never mixed with each other, and are forbidden with --recurrence-year-days or --recurrence-year-weeks.
local-apple-data contacts search/get commands for local Contacts by name or organization through Contacts.framework
local-apple-data contacts request-access --json to trigger the one-time macOS Contacts prompt for the stable signed Contacts helper app; normal Contacts reads and writes do not prompt and fail closed without authorization
local-apple-data contacts groups --json --query <group> and local-apple-data contacts group --json --handle <contacts:group:v1:...> for Contacts group metadata and group_safe_sha256 without raw member identifiers
local-apple-data contacts group-members --json --handle <contacts:group:v1:...> [--limit 20] for capped selected-group member metadata with opaque contact handles and no raw member IDs or contact detail values
local-apple-data contacts containers --json --query <container> and local-apple-data contacts container --json --handle <contacts:container:v1:...> for Contacts container metadata and container_safe_sha256 without raw container identifiers
local-apple-data contacts container-members --json --handle <contacts:container:v1:...> [--limit 20] for capped selected-container member metadata with opaque contact handles and no raw contact IDs or contact detail values
local-apple-data contacts count --json for read-only live Contacts counts without returning contact details
local-apple-data contacts export --json --output-dir <dir> [--filename-prefix contacts] for a read-only JSON plus vCard Contacts backup with count-match verification and no contact-data echo in the tool response. Contact notes are omitted when Apple's restricted Contacts-notes entitlement is unavailable; if vCard serialization then cannot be verified, the JSON archive is retained but the overall archive fails closed as unverified.
local-apple-data contacts plan --json --operation create --contact-type person --given-name <name> --family-name <name> [--container-handle <contacts:container:v1:...> --expected-container-sha256 <container_safe_sha256>] for non-mutating future contact-create previews with idempotency and approval metadata
local-apple-data contacts apply --json --operation create --contact-type person --given-name <name> --family-name <name> [--container-handle <contacts:container:v1:...> --expected-container-sha256 <container_safe_sha256>] --approval-token <token> --confirm-apply for the approved Contacts create-contact path, with Contacts.framework apply and read-back verification
local-apple-data contacts plan --json --operation update --handle <contacts:contact:v1:...> --expected-current-sha256 <update_safe_sha256> --given-name <name> [--email work=name@example.invalid] [--postal-addresses-json '[...]'] [--birthday-json '{"month":1,"day":2}'] [--image-path <file>] [--clear-image] for non-mutating exact-contact scalar/method/rich-field/image update previews with current-state binding. Omitted arrays are preserved; provided arrays replace; empty arrays clear.
local-apple-data contacts apply --json --operation update --handle <contacts:contact:v1:...> --expected-current-sha256 <update_safe_sha256> ... --approval-token <token> --confirm-apply for the approved exact-contact scalar/method/rich-field/image update path, with Contacts.framework read-back verification
local-apple-data contacts plan --json --operation append-note|set-note|clear-note|merge-note --handle <contacts:contact:v1:...> --expected-current-sha256 <note_safe_sha256> [--note-text <text>] is the approved non-mutating exact-contact note gate, but it currently fails closed with contacts_note_unavailable because the local signed helper cannot obtain Apple's restricted provisioning-profile Contacts-notes entitlement
The matching Contacts note apply command remains approval-token and explicit-confirmation gated but is currently unavailable for the same entitlement reason; it never mutates before returning contacts_note_unavailable
local-apple-data contacts plan --json --operation add-group-member|remove-group-member --handle <contacts:contact:v1:...> --expected-current-sha256 <update_safe_sha256> --group-handle <contacts:group:v1:...> --expected-group-sha256 <group_safe_sha256> for non-mutating exact group membership previews
local-apple-data contacts apply --json --operation add-group-member|remove-group-member --handle <contacts:contact:v1:...> --expected-current-sha256 <update_safe_sha256> --group-handle <contacts:group:v1:...> --expected-group-sha256 <group_safe_sha256> --approval-token <token> --confirm-apply for approved exact group membership updates with metadata-only group read-back
local-apple-data contacts plan --json --operation create-group --group-name <name> [--container-handle <contacts:container:v1:...> --expected-container-sha256 <container_safe_sha256>] and matching contacts apply --operation create-group ... --approval-token <token> --confirm-apply for exact group creation with metadata-only group read-back
local-apple-data contacts plan --json --operation rename-group --group-handle <contacts:group:v1:...> --expected-group-sha256 <group_safe_sha256> --group-name <name> and matching contacts apply --operation rename-group ... --approval-token <token> --confirm-apply for exact group rename
local-apple-data contacts plan --json --operation delete-group --group-handle <contacts:group:v1:...> --expected-group-sha256 <group_safe_sha256> and matching contacts apply --operation delete-group ... --approval-token <token> --confirm-apply for exact group delete with absence proof and contacts_deleted:false
local-apple-data contacts plan --json --operation batch --batch-items-json '[...]' and matching contacts apply --operation batch --batch-items-json '[...]' --approval-token <token> --confirm-apply for capped exact batches over approved existing-contact operations
local-apple-data contacts plan --json --operation delete --handle <contacts:contact:v1:...> --expected-current-sha256 <delete_safe_sha256> for non-mutating exact-contact delete previews with full-detail current-state binding
local-apple-data contacts apply --json --operation delete --handle <contacts:contact:v1:...> --expected-current-sha256 <delete_safe_sha256> --approval-token <token> --confirm-apply for the approved exact-contact delete path, with Contacts.framework deletion and absence read-back proof
local-apple-data photos search/get/export commands for local Photos asset metadata by original filename, exact asset/resource metadata, and exact-handle asset export to a caller-selected output directory through PhotoKit
local-apple-data photos albums/album/album-assets commands for bounded regular-album title metadata, exact regular-album metadata, and exact selected-album child asset metadata by opaque album handle
local-apple-data photos request-access --json to trigger the one-time macOS Photos access prompt for the local PhotoKit helper path; normal Photos reads and writes do not prompt and fail closed if Photos access is absent. If macOS returns photos_access_request_timeout, approve Local Apple Data Photos Helper manually under Privacy & Security > Photos.
local-apple-data photos plan --json --operation import --source-file <path> for non-mutating future image/video import previews with source-file hash binding and approval metadata
local-apple-data photos apply --json --operation import --source-file <path> --approval-token <token> --confirm-apply for the approved Photos import path, with PhotoKit apply and created-asset read-back verification
local-apple-data photos plan --json --operation update-flags --handle <photos:asset:v1:...> --favorite true --expected-favorite false --expected-hidden false and matching photos apply --operation update-flags ... --approval-token <token> --confirm-apply for exact asset favorite/hidden updates with expected-state binding and PhotoKit read-back verification
local-apple-data photos plan --json --operation delete --handle <photos:asset:v1:...> and matching photos apply --operation delete ... --approval-token <token> --confirm-apply for exact selected-asset delete with expected-state binding and PhotoKit absence proof; it does not empty Recently Deleted or permanently purge Photos assets
local-apple-data photos plan/apply --json --operation create-album --album-title '<album title>', rename-album --album-handle <photos:album:v1:...> --new-album-title '<album title>', and delete-album --album-handle <photos:album:v1:...> for exact regular-album create/rename/delete with full Photos Library authorization with duplicate-title refusal, exact state binding for rename/delete, empty-album proof for delete, PhotoKit apply, title read-back for create/rename, absence proof for delete, and no raw album identifiers
local-apple-data reminders search/due metadata commands
local-apple-data reminders eventkit-search for local Reminders title metadata through EventKit
local-apple-data reminders request-access --json to trigger the one-time macOS Reminders full-access prompt for the stable local EventKit helper app; normal Reminders reads do not prompt and fail closed if full access is absent
local-apple-data reminders lists --json --query <list title text>, local-apple-data reminders list --json --handle <reminders:list:eventkit:v1:...>, and local-apple-data reminders list-items --json --handle <reminders:list:eventkit:v1:...> for exact Reminders target-list metadata and selected-list reminder metadata by opaque list handle; local-apple-data reminders lists --json without --query (MCP reminders_list_lists) enumerates all Reminders lists as capped metadata. List metadata includes is_shared (null when EventKit sharing detection is unavailable) plus sharee_count when EventKit exposes a positive count — count only, never sharee identities — so agents can see that a list is shared with other people before writing to it. Moving a reminder out of a shared list is refused by EventKit and reported as shared_list_move_unsupported with a create-on-target plus guarded-delete fallback recommendation
local-apple-data reminders content --json --handle <reminders:reminder:eventkit:v1:...> --max-chars 4000 for exact-handle local Reminder notes
local-apple-data reminders plan --json --operation create|complete|uncomplete|update-due-date|update-title|update-notes|update-priority|update-url|clear-url|set-absolute-display-alarm|set-relative-display-alarm|clear-display-alarm|move-to-list|delete ... for non-mutating future-change previews with idempotency and approval metadata
local-apple-data reminders apply --json --operation create|complete|uncomplete|update-due-date|update-title|update-notes|update-priority|update-url|clear-url|set-absolute-display-alarm|set-relative-display-alarm|clear-display-alarm|move-to-list|delete ... --approval-token <token> --confirm-apply for the approved Reminders create/complete/uncomplete/due-date/title/notes/priority/exact URL update/clear/exact absolute/relative/mixed display-alarm set/clear/start-date set/clear/recurrence create/update/clear/exact same-source list-move/delete path, with exact-handle expected-state checks, hash-only URL read-back or absence proof for URL changes, exact absolute-date or relative-offset read-back or alarm absence proof for display-alarm changes, exact expected-current-list and same-source target-list handle checks plus target_list_verified:true identity proof for list-move, notes-hash drift refusal for notes updates and delete, EventKit apply, and read-back verification or delete absence proof
local-apple-data reminders plan-list --json --operation create-list|rename-list|delete-list|delete-list-with-migration ... and matching reminders apply-list ... --approval-token <token> --confirm-apply for exact list create/rename/empty-delete/same-source migrate-delete, with exact source/target list-handle binding, empty-list proof for rename/delete, bounded migration count proof for migrate-delete, EventKit apply, and source/title, empty-list, migration, target-count, or absence read-back verification
Highest-version Mail store discovery without exposing raw local store paths in normal output
local-apple-data-mcp stdio MCP server with read-only tools plus 14 public apply-capable MCP tools: reminders_apply_change, reminders_apply_list_change, icloud_drive_apply_change, calendar_apply_change, calendar_apply_calendar_change, contacts_apply_change, notes_apply_change, mail_apply_change, mail_apply_mailbox_change, mail_apply_cleanup, photos_apply_change, messages_apply_change, filesystem_apply_change, and shortcuts_apply_run. Tools whose static apply surface can delete, move an item to Trash, send external mail, or invoke a Shortcut are annotated destructive.
MCP runner script that avoids package builds during normal plugin startup
Codex skill under skills/local-apple-data/
Local plugin manifest under .codex-plugin/plugin.json
Bundled MCP config under .mcp.json
Redacted command event logging
Opaque signed handles for exact Mail/Messages/Voice Memos/Safari/Shortcuts/Books/Podcasts/Music/TV/Notes/Notes-folder/Calendar/Contacts/Contacts-group/Contacts-container/Photos/Reminders/iCloud Drive/Filesystem metadata fetches, including fs:file:v1: for bounded home-directory selection
Exact Mail content retrieval through the same opaque mail:message:v2: handles
Exact Messages chat transcript retrieval through opaque messages:chat:v1: handles, using local text plus bounded attributedBody plaintext fallback when available
Exact Messages participant metadata through opaque messages:chat:v1: and messages:participant:v1: handles; participant lists do not expose phone/email previews
Exact Messages attachment metadata/export through opaque messages:chat:v1: and messages:attachment:v1: handles
Exact inferred Hide My Email alias detail through opaque hide_my_email:alias:v1: handles
Exact Voice Memos transcript retrieval through opaque voice_memos:recording:v1: handles when Apple-generated local transcript data is embedded in the selected .m4a
Exact Voice Memos audio export through opaque voice_memos:recording:v1: handles to a caller-selected output directory without returning audio bytes inline
Exact Safari bookmark and Reading List URL detail retrieval through opaque safari:item:v1: handles plus exact selected-folder metadata and direct child listing through opaque safari:folder:v1: handles, without returning full URLs in search or folder-list results
Exact Shortcuts shortcut/folder metadata retrieval and selected-folder shortcut metadata listing through opaque shortcuts:item:v1: handles without returning raw identifiers or shortcut bodies
Exact Apple Books metadata and selected-book annotation retrieval through opaque books:book:v1: handles without returning raw Books identifiers, local paths, or book/chapter text
Exact Apple Podcasts show metadata, selected-show episode metadata, and selected-episode bounded descriptions through opaque podcasts:show:v1: and podcasts:episode:v1: handles without returning transcripts, audio bytes, feed/enclosure URLs, raw identifiers, or local download paths
Exact Apple Music track, playlist, and selected-playlist track metadata through opaque music:track:v1: and music:playlist:v1: handles without returning audio bytes, lyrics, file paths, raw identifiers, play history, ratings, or broad playlist track dumps
Exact Apple TV item, playlist, and selected-playlist item metadata through opaque tv:item:v1: and tv:playlist:v1: handles without returning video bytes, file paths, artwork, descriptions, playback state, watched state, ratings, raw identifiers, or broad playlist item dumps
Exact iCloud Drive root metadata selection, selected-folder direct child metadata listing, bounded recursive folder-tree metadata listing, text-file retrieval, and regular-file export through opaque icloud:file:v1: handles
Exact Calendar event detail retrieval through opaque calendar:event:v1: handles and exact selected participant detail through calendar:participant:v1: handles
Exact Contact detail retrieval through opaque contacts:contact:v1: handles
Exact Photos asset metadata/resource detail retrieval through opaque photos:asset:v1: handles
Exact Photos asset export through opaque photos:asset:v1: handles to a caller-selected output directory without returning image/video bytes inline
Exact Reminder note retrieval through opaque reminders:reminder:eventkit:v1: handles and exact Reminders list metadata through opaque reminders:list:eventkit:v1: handles
Broad-query rejection for empty, wildcard-only, and one-character searches
Runtime verification script under scripts/verify_runtime.py
Cross-client sync verifier under scripts/verify_cross_agent_sync.py, including optional Cursor mcp.json validation
macOS CI workflow under .github/workflows/ci.yml
Contributor guide under CONTRIBUTING.md and GitHub issue/PR templates with privacy and mutation-gate checklists
Repo-local redaction scanner under scripts/redaction_scan.py
Release-readiness auditor under scripts/audit_release_readiness.py, including clean-git-worktree, redaction, public leakage, gate drift, public-checkout, public GitHub visibility, live remote-advertised HEAD, and source release candidate gates
Mutation-gate auditor under scripts/audit_mutation_gates.py so write-like CLI/MCP surfaces cannot appear without explicit gates
Write-design gate auditor under scripts/audit_write_design_gates.py so every write-like surface remains machine-checkable against the canonical 14-tool public MCP apply inventory and its operation-specific design gates in docs/MUTATION_GATES.md
Machine-readable public Messages scripting-surface audit under scripts/audit_messages_public_surface.py, which keeps risky Messages CRUD blocked unless the public SDEF changes and a separate design gate is approved
Surface-contract auditor under scripts/audit_surface_contract.py so MCP tools, CLI commands, health surfaces, access requirements, and the capability matrix stay aligned
MCP client config renderer for generic stdio, Claude Code, Cursor, and OpenClaw under scripts/render_mcp_client_config.py
Public release tree builder under scripts/build_public_release_tree.py
Public git checkout preparer under scripts/prepare_public_git_checkout.py, including optional initial local commit creation
Path-redacted release receipt generator under scripts/generate_release_receipt.py; receipts include source git traceability and file output is intentionally limited to paths outside the source checkout
Synthetic unit and CLI tests
Local git repo on branch main

Deferred:

Any mutating tools other than the approved Reminders create/complete/uncomplete/due-date/title/notes/priority-update/exact URL update/clear/exact absolute/relative/mixed display-alarm set/clear/start-date set/clear/recurrence create/update/clear/exact same-source list-move/delete apply and exact list create/rename/empty-delete/same-source migrate-delete apply surface, iCloud Drive create-folder/create-folder-path/rename-folder/trash-folder/delete-folder/move-folder/copy-folder/create/append-text/replace-text/trash-text/delete-text/rename-text/copy-text/move-text/rename-file/copy-file/move-file/import-file/replace-file/trash-file/delete-file apply surface, Calendar event create/update/delete apply surface including date-only all-day inference, exact availability create/update, exact allow-listed event URL create/update and exact event URL clearing with hash-only read-back proof, simple count-, end-date-, or explicit-unbounded daily/weekly/monthly/yearly recurrence create and add-to-non-recurring-event update with weekly weekday, monthly weekday, monthly day-of-month, monthly nth-weekday, and yearly month/month-day/month-nth-weekday/day-of-year/week-of-year plus explicit weekday selection for week-of-year and selector-backed set-position filtering, selected-occurrence recurring-event title/plain-location/notes/timed reschedule/availability/event URL set/clear/structured-location set/clear/display-alarm set/clear/action-alarm set/clear/all-day set/clear/date-only reschedule/target-calendar move update, selected-occurrence recurring-event delete, future-event recurring span delete, whole-series recurring-event delete, first-visible and mid-series recurrence clearing, mid-series recurrence replacement, future-series recurring-event title/plain-location/notes/timed reschedule/availability/event URL set/clear/structured-location set/clear/display-alarm set/clear/action-alarm set/clear/all-day set/clear/date-only reschedule/target-calendar move update, and structured event location create/update/clear, apply from approved explicit default-calendar create plans only through the resolved exact calendar handle, and Calendar synthetic LAD-TEST-* calendar create/rename/delete apply surface, Contacts create-contact/exact scalar/method/rich-field/image update/exact group membership/exact group create/rename/delete/exact batch/delete apply surface, Notes default/exact-folder note create, exact child-folder create, exact-folder rename, exact empty child-folder delete, exact empty child-folder move, append-text, replace-text, rich-text body create, rich-text body replace, move-to-folder, and exact-note delete apply surface, Mail create-draft/send-message/reply-message/reply-all-message/forward-message/mark-read/mark-unread/flag-message/unflag-message/archive-message/move-message/trash-message apply surface, Mail synthetic LAD-TEST-* mailbox create/rename apply surface, source-gated synthetic mailbox delete and cleanup apply surface only when public Mail.app deletion plus exact target-state binding, mailbox-scoped absence proof, and Mail-idle guards succeed, Photos import, exact asset favorite/hidden update, exact asset delete, exact regular-album membership add/remove, and exact regular-album create/rename/delete apply with full Photos Library authorization surface, Messages send-text/send-file apply surface, home-directory Filesystem apply surface, and exact identifier-bound Shortcuts run apply surface. Contacts note gates remain designed and synthetic-testable but live-unavailable: they fail closed with contacts_note_unavailable before mutation.
Mail send outside the approved send-message gate, Mail reply outside the approved exact-message sender-only or reply-all gates, Mail forward outside the approved exact-message forward gate, Mail source attachment/non-body-part forwarding outside the explicit include_source_attachments forward gate, Mail cross-account move outside the approved exact target-mailbox gate, Mail permanent delete outside the synthetic LAD-TEST-* Trash/Junk cleanup gate, Mail mailbox mutation outside the synthetic empty LAD-TEST-* mailbox gate, Mail account mutation, Mail archive outside the approved exact-message same-account Archive gate, Mail move outside the approved exact-message target-mailbox gate, Mail read/flag/archive/move/trash triage mutation outside the approved exact-message or capped exact bulk mark-read/mark-unread/flag-message/unflag-message/archive-message/move-message gate, Mail query-result triage outside the capped preview-to-exact-plan gate, Mail attachment mutation outside the approved draft/send/reply/reply-all/forward local-file attachment gates, broad Mail attachment export, Calendar update outside the approved exact-event title/time/location/structured-location/notes/all-day/relative-or-absolute display/audio/email/geofence alarm/time-zone/availability/event-URL/simple add-recurrence/first-visible or mid-series recurrence-clear-or-replace/selected-occurrence title/plain-location/notes/timed reschedule/availability/event URL set/clear/structured-location set/clear/display-alarm set/clear/action-alarm set/clear/all-day set/clear/date-only reschedule/target-calendar move gate, Calendar delete outside the approved exact-event absence-proof gate, Calendar recurrence outside simple count-, end-date-, or explicit-unbounded daily/weekly/monthly/yearly create, add-to-non-recurring-event update with weekly weekday, monthly weekday, monthly day-of-month, monthly nth-weekday, and yearly month/month-day/month-nth-weekday/day-of-year/week-of-year plus explicit weekday selection for week-of-year and selector-backed set-position filtering, selected-occurrence title/plain-location/notes/timed reschedule/availability/event URL set/clear/structured-location set/clear/display-alarm set/clear/action-alarm set/clear/all-day set/clear/date-only reschedule/target-calendar move update, future-series title/plain-location/notes/timed reschedule/availability/event URL set/clear/structured-location set/clear/display-alarm set/clear/action-alarm set/clear/all-day set/clear/date-only reschedule/target-calendar move update, selected-occurrence delete, future-event recurring span delete, whole-series recurring-event delete, or first-visible or mid-series recurrence clearing, mid-series recurrence replacement, or custom recurrence shapes beyond approved selector-backed EventKit rules, attendee/invitation/organizer mutation, silent default-calendar guessing or default-calendar mutation, timed-event time-zone guessing, availability outside explicit busy/free/tentative/unavailable support-mask validation, non-allow-listed event URL schemes, procedure alarms, or alarm mutation outside exact relative/absolute display-or-audio-or-email-or-geofence-alarm gates, Contacts raw identifier input, broad contact dumps in chat, direct database writes, duplicate merge automation, free-form labels over 255 characters or labels containing control characters, and complete Contacts management, Notes update outside the approved exact-note append/replace/move-to-folder gates, Notes delete outside the approved exact-note delete gate, Notes move outside the approved exact-note/exact-folder move-to-folder gate, Notes folder/account targeting outside exact note create, exact child-folder create, exact-folder rename, exact empty child-folder delete, exact empty child-folder move, and move-to-folder gates, Notes root/recursive folder delete, root/non-empty/recursive/cross-account folder move, root/default-account folder creation, Notes rich-text mutation outside approved create_html/replace_html gates or attachment mutation, Notes broad attachment export, locked/shared-note mutation, Recently Deleted management, Photos permanent delete/Recently Deleted empty, smart/shared/synced album targeting, bulk album membership, content edits, or metadata mutation outside exact favorite/hidden update, exact asset delete, exact regular-album membership add/remove, and exact regular-album create/rename/delete with full Photos Library authorization, Photos network iCloud fetch, Messages direct-recipient send/new-chat/SMS-fallback selection/edit/delete/reaction/tapback/other mutation outside the approved exact-chat send-text/send-file gates, broad Messages attachment export, Messages attachment mutation outside the approved exact-chat send-file gate, Voice Memos mutation or attachments, Safari history/open-tabs/passwords/private-browsing data/bookmark mutation, Shortcuts runs outside the approved exact-handle plan/apply gate, Shortcuts open/view/sign/export/body/action-graph/import/create/update/delete/duplicate mutation, Books book/chapter/PDF/EPUB text extraction, broad annotation dumps/search, raw Books paths/identifiers, or mutation, Podcasts transcript/audio/feed/enclosure URL extraction, broad episode-description dumps/search, raw Podcasts identifiers/paths, iCloud media fetch, Podcasts.app automation, or mutation, Music audio/lyrics/file-path export, play history, ratings/favorites, broad playlist track dumps, playback/queue control, library import/delete, raw Music database parsing, Music.app mutation, TV video/file-path/artwork/description export, playback or watched state, ratings/favorites, broad playlist item dumps, playback/queue control, library import/delete, raw TV library parsing, TV.app mutation, iCloud media fetch, Reminders bulk/account management and sharing/cross-source list management, non-empty list delete outside the bounded same-source migrate-delete gate, and list management outside exact same-source list-move plus exact list create/rename/empty-delete/same-source migrate-delete, attachments, URL mutation outside the exact URL update/clear gate, raw URL return, rich-content mutation, or delete outside the approved exact-handle gate, Reminders title/notes/priority/URL mutation outside the approved exact-handle update gates, Reminders list move outside the approved exact reminder plus exact same-source target-list gate, and Reminders list create/rename/delete outside the exact source/target handle, empty-delete, and bounded same-source migrate-delete gates, iCloud Drive content replacement outside the exact replace-text or replace-file gates, iCloud Drive folder creation outside the exact create-folder or bounded create-folder-path gates, iCloud Drive folder rename outside the exact folder rename gate, iCloud Drive folder move outside the exact folder move gate, iCloud Drive folder copy outside the exact selected-folder copy gate, iCloud Drive folder delete outside the exact selected-folder delete gate, iCloud Drive trash/delete outside the exact trash-text, exact folder trash, exact regular-file trash, or exact delete-file gates, iCloud Drive rename/copy/move outside the exact text-file or regular-file gates, iCloud Drive file permanent delete outside the exact delete-text or delete-file gates, unbounded-recursive-delete/unbounded-folder-copy/binary/document content generation or editing, regular-file mutation outside exact import-file, exact replace-file, exact trash-file, exact delete-file, or metadata-only rename/copy/move gates, authoritative Hide My Email inventory, Hide My Email creation/deactivation/deletion, private iCloud web/API access, browser/keychain credential access, generated Voice Memos transcription, unbounded broad content search, broad Messages text search, broad Voice Memos transcript search, unsupported/binary iCloud Drive content extraction, and durable content caches outside the approved opt-in private Mail FTS index

The exact-handle Mail content retrieval gate is summarized in the safety model and capability matrix. The public capability matrix is documented in docs/CAPABILITY_MATRIX.md. The write/mutation approval gates are documented in docs/MUTATION_GATES.md. The future write-tool roadmap is documented in docs/WRITE_TOOL_ROADMAP.md. The first Reminders write design gate is documented in docs/V1_11_REMINDERS_WRITE_DESIGN.md. The Reminders exact same-source list-move write design gate is documented in docs/V1_65_REMINDERS_LIST_MOVE_WRITE_DESIGN.md. The Reminders exact URL update/clear write design gate is documented in docs/V1_136_REMINDERS_URL_WRITE_DESIGN.md. The Reminders exact absolute display-alarm set/clear write design gate is documented in docs/V1_137_REMINDERS_ABSOLUTE_DISPLAY_ALARM_WRITE_DESIGN.md. The Reminders exact relative display-alarm set and broadened pure display-alarm clear write design gate is documented in docs/V1_138_REMINDERS_RELATIVE_DISPLAY_ALARM_WRITE_DESIGN.md. The Reminders exact mixed absolute-plus-relative display-alarm set/clear write design gate is documented in docs/V1_176_REMINDERS_MIXED_DISPLAY_ALARM_WRITE_DESIGN.md. The first iCloud Drive write design gate is documented in docs/V1_12_ICLOUD_DRIVE_WRITE_DESIGN.md. The first Calendar write design gate is documented in docs/V1_13_CALENDAR_WRITE_DESIGN.md. The Calendar simple recurrence create write design gate is documented in docs/V1_89_CALENDAR_RECURRENCE_WRITE_DESIGN.md. The Calendar explicit default-calendar create planning gate is documented in docs/V1_91_CALENDAR_DEFAULT_CALENDAR_CREATE_WRITE_DESIGN.md. The Calendar exact availability create/update gate is documented in docs/V1_92_CALENDAR_AVAILABILITY_WRITE_DESIGN.md. The Calendar add-to-non-recurring-event recurrence update gate is documented in docs/V1_93_CALENDAR_RECURRENCE_UPDATE_WRITE_DESIGN.md. The Calendar selected recurring occurrence delete gate is documented in docs/V1_96_CALENDAR_RECURRING_OCCURRENCE_DELETE_WRITE_DESIGN.md; the future-event recurring span delete gate is documented in docs/V1_97_CALENDAR_RECURRING_FUTURE_DELETE_WRITE_DESIGN.md; the whole-series recurring-event delete gate is documented in docs/V1_98_CALENDAR_RECURRING_SERIES_DELETE_WRITE_DESIGN.md; the weekly weekday recurrence gate is documented in docs/V1_99_CALENDAR_WEEKLY_WEEKDAY_RECURRENCE_WRITE_DESIGN.md; the first-visible and mid-series recurrence clearing gate is documented in docs/V1_100_CALENDAR_RECURRENCE_CLEAR_WRITE_DESIGN.md; the monthly day-of-month recurrence gate is documented in docs/V1_101_CALENDAR_MONTHDAY_RECURRENCE_WRITE_DESIGN.md; the structured event location gate is documented in docs/V1_102_CALENDAR_STRUCTURED_LOCATION_WRITE_DESIGN.md; selected recurring occurrence scalar update through all-day set/clear/date-only reschedule is documented in docs/V1_114_CALENDAR_SELECTED_OCCURRENCE_UPDATE_WRITE_DESIGN.md, docs/V1_115_CALENDAR_SELECTED_OCCURRENCE_RESCHEDULE_WRITE_DESIGN.md, docs/V1_116_CALENDAR_SELECTED_OCCURRENCE_AVAILABILITY_WRITE_DESIGN.md, docs/V1_117_CALENDAR_SELECTED_OCCURRENCE_EVENT_URL_WRITE_DESIGN.md, docs/V1_118_CALENDAR_SELECTED_OCCURRENCE_STRUCTURED_LOCATION_WRITE_DESIGN.md, docs/V1_119_CALENDAR_SELECTED_OCCURRENCE_DISPLAY_ALARM_WRITE_DESIGN.md, docs/V1_120_CALENDAR_SELECTED_OCCURRENCE_ACTION_ALARM_WRITE_DESIGN.md, and docs/V1_121_CALENDAR_SELECTED_OCCURRENCE_ALL_DAY_WRITE_DESIGN.md. The Calendar mid-series recurrence replacement gate is documented in docs/V1_126_CALENDAR_RECURRENCE_REPLACEMENT_WRITE_DESIGN.md; the future-series recurring-event title/plain-location/notes update gate is documented in docs/V1_167_CALENDAR_FUTURE_SERIES_SCALAR_UPDATE_WRITE_DESIGN.md; the future-series recurring-event timed reschedule gate is documented in docs/V1_168_CALENDAR_FUTURE_SERIES_RESCHEDULE_WRITE_DESIGN.md; the future-series recurring-event availability update gate is documented in docs/V1_169_CALENDAR_FUTURE_SERIES_AVAILABILITY_WRITE_DESIGN.md; the future-series recurring-event event URL set/clear gate is documented in docs/V1_170_CALENDAR_FUTURE_SERIES_EVENT_URL_WRITE_DESIGN.md; the future-series recurring-event structured-location set/clear gate is documented in docs/V1_171_CALENDAR_FUTURE_SERIES_STRUCTURED_LOCATION_WRITE_DESIGN.md; the future-series recurring-event display-alarm set/clear gate is documented in docs/V1_172_CALENDAR_FUTURE_SERIES_DISPLAY_ALARM_WRITE_DESIGN.md; the future-series recurring-event action-alarm set/clear gate is documented in docs/V1_173_CALENDAR_FUTURE_SERIES_ACTION_ALARM_WRITE_DESIGN.md; the future-series recurring-event all-day set/clear/date-only reschedule gate is documented in docs/V1_174_CALENDAR_FUTURE_SERIES_ALL_DAY_WRITE_DESIGN.md. The Calendar selector-backed set-position recurrence gate is documented in docs/V1_123_CALENDAR_SET_POSITIONS_RECURRENCE_WRITE_DESIGN.md. The Calendar synthetic calendar management gate is documented in docs/V1_124_CALENDAR_CALENDAR_MANAGEMENT_WRITE_DESIGN.md. The first Contacts write design gate is documented in docs/V1_14_CONTACTS_WRITE_DESIGN.md. The Contacts exact scalar update write design gate is documented in docs/V1_48_CONTACTS_UPDATE_WRITE_DESIGN.md; the Contacts exact email/phone/URL method-array replacement gate is documented in docs/V1_69_CONTACTS_METHOD_UPDATE_WRITE_DESIGN.md. The Contacts exact delete write design gate is documented in docs/V1_49_CONTACTS_DELETE_WRITE_DESIGN.md. The first Notes write design gate is documented in docs/V1_15_NOTES_WRITE_DESIGN.md. The Notes exact-folder create write design gate is documented in docs/V1_39_NOTES_FOLDER_CREATE_WRITE_DESIGN.md. The Notes exact child-folder create write design gate is documented in docs/V1_57_NOTES_FOLDER_CREATE_WRITE_DESIGN.md. The Notes exact-folder rename write design gate is documented in docs/V1_58_NOTES_FOLDER_RENAME_WRITE_DESIGN.md. The Notes exact empty child-folder delete write design gate is documented in docs/V1_59_NOTES_FOLDER_DELETE_WRITE_DESIGN.md. The Notes exact empty child-folder move write design gate is documented in docs/V1_158_NOTES_FOLDER_MOVE_WRITE_DESIGN.md. The Notes exact-delete write design gate is documented in docs/V1_42_NOTES_DELETE_WRITE_DESIGN.md. The first Mail draft write design gate is documented in docs/V1_16_MAIL_DRAFT_WRITE_DESIGN.md; optional exact sender selection for Mail create-draft is documented in docs/V1_74_MAIL_SENDER_DRAFT_WRITE_DESIGN.md; exact sender selection for Mail send/reply/reply-all/forward is documented in docs/V1_82_MAIL_OUTBOUND_SENDER_SELECTION_WRITE_DESIGN.md; optional local file attachments for Mail create-draft are documented in docs/V1_75_MAIL_DRAFT_ATTACHMENT_WRITE_DESIGN.md. The Mail send-message write design gate is documented in docs/V1_43_MAIL_SEND_WRITE_DESIGN.md. The Mail reply-message write design gate is documented in docs/V1_44_MAIL_REPLY_WRITE_DESIGN.md. The Mail reply-all-message write design gate is documented in docs/V1_73_MAIL_REPLY_ALL_WRITE_DESIGN.md. The Mail forward-message write design gate is documented in docs/V1_50_MAIL_FORWARD_WRITE_DESIGN.md. The Mail exact-message target-mailbox move write design gate is documented in docs/V1_46_MAIL_MOVE_WRITE_DESIGN.md; the cross-account exact target extension is documented in docs/V1_66_MAIL_CROSS_ACCOUNT_MOVE_WRITE_DESIGN.md. The Mail synthetic LAD-TEST-* mailbox management and synthetic-only cleanup design gate is documented in docs/V1_84_MAIL_SYNTHETIC_MAILBOX_CLEANUP_WRITE_DESIGN.md. The first Photos import write design gate is documented in docs/V1_17_PHOTOS_IMPORT_WRITE_DESIGN.md; exact favorite/hidden update is documented in docs/V1_134_PHOTOS_UPDATE_FLAGS_WRITE_DESIGN.md; exact selected-asset delete is documented in docs/V1_149_PHOTOS_DELETE_WRITE_DESIGN.md; exact regular-album membership add/remove is documented in docs/V1_151_PHOTOS_ALBUM_MEMBERSHIP_WRITE_DESIGN.md; exact selected-album asset listing is documented in docs/V1_152_PHOTOS_ALBUM_ASSET_LISTING.md; exact regular-album create/rename/delete with full Photos Library authorization is documented in docs/V1_154_PHOTOS_REGULAR_ALBUM_MANAGEMENT_WRITE_DESIGN.md. The Mail exact-message Trash write design gate is documented in docs/V1_41_MAIL_TRASH_WRITE_DESIGN.md. The first iCloud Drive append-text write design gate is documented in docs/V1_18_ICLOUD_DRIVE_APPEND_WRITE_DESIGN.md. The iCloud Drive replace-text write design gate is documented in docs/V1_51_ICLOUD_DRIVE_REPLACE_WRITE_DESIGN.md. The iCloud Drive create-folder write design gate is documented in docs/V1_52_ICLOUD_DRIVE_FOLDER_CREATE_WRITE_DESIGN.md. The iCloud Drive trash-text write design gate is documented in docs/V1_53_ICLOUD_DRIVE_TRASH_WRITE_DESIGN.md. The iCloud Drive rename/copy/move text-file write design gate is documented in docs/V1_54_ICLOUD_DRIVE_RENAME_COPY_MOVE_WRITE_DESIGN.md. The iCloud Drive exact folder Trash write design gate is documented in docs/V1_61_ICLOUD_DRIVE_FOLDER_TRASH_WRITE_DESIGN.md; non-empty folder broadening is documented in docs/V1_146_ICLOUD_DRIVE_NON_EMPTY_FOLDER_TRASH_WRITE_DESIGN.md. The iCloud Drive exact folder move write design gate is documented in docs/V1_62_ICLOUD_DRIVE_FOLDER_MOVE_WRITE_DESIGN.md; non-empty folder rename/move broadening is documented in docs/V1_145_ICLOUD_DRIVE_NON_EMPTY_FOLDER_RENAME_MOVE_WRITE_DESIGN.md. The iCloud Drive exact folder copy write design gate is documented in docs/V1_63_ICLOUD_DRIVE_FOLDER_COPY_WRITE_DESIGN.md and broadened for bounded non-empty selected-folder trees in docs/V1_147_ICLOUD_DRIVE_NON_EMPTY_FOLDER_COPY_WRITE_DESIGN.md. The iCloud Drive exact selected-folder permanent delete write design gate is documented in docs/V1_67_ICLOUD_DRIVE_FOLDER_DELETE_WRITE_DESIGN.md. The iCloud Drive exact text-file permanent delete write design gate is documented in docs/V1_68_ICLOUD_DRIVE_DELETE_TEXT_WRITE_DESIGN.md. The iCloud Drive exact regular-file export read design gate is documented in docs/V1_85_ICLOUD_DRIVE_FILE_EXPORT.md. The first Notes append-text write design gate is documented in docs/V1_19_NOTES_APPEND_WRITE_DESIGN.md. The first Notes attachment export design gate is documented in docs/V1_20_NOTES_ATTACHMENT_EXPORT.md. The first Mail attachment export design gate is documented in docs/V1_21_MAIL_ATTACHMENT_EXPORT.md. The first Messages attachment export design gate is documented in docs/V1_22_MESSAGES_ATTACHMENT_EXPORT.md. The Messages attributed-body fallback design gate is documented in docs/V1_23_MESSAGES_ATTRIBUTED_BODY.md. The Messages participant metadata read gate is documented in docs/V1_64_MESSAGES_PARTICIPANTS_METADATA.md. The first Messages send-text write design gate is documented in docs/V1_24_MESSAGES_SEND_TEXT_WRITE_DESIGN.md. The first Messages send-file write design gate is documented in docs/V1_38_MESSAGES_SEND_FILE_WRITE_DESIGN.md. The Messages risky-mutation source-review blocker gate and public SDEF audit are documented in docs/V1_47_MESSAGES_RISKY_MUTATION_SOURCE_REVIEW.md. The Safari bookmarks and Reading List read gate is documented in docs/V1_25_SAFARI_BOOKMARKS.md. The Shortcuts metadata/selected-folder shortcut metadata read gate is documented in docs/V1_26_SHORTCUTS_METADATA.md. The Apple Books metadata and selected annotations read gate is documented in docs/V1_27_BOOKS_METADATA.md. The Apple Podcasts metadata read gate is documented in docs/V1_28_PODCASTS_METADATA.md.

The Apple Music metadata read gate is documented in docs/V1_29_MUSIC_METADATA.md. The Apple TV metadata read gate is documented in docs/V1_30_TV_METADATA.md. The publication checklist is documented in docs/PUBLISHING.md. The public install guide is documented in docs/INSTALL.md. Synthetic sample outputs are documented in docs/SAMPLE_OUTPUTS.md. macOS support notes are documented in docs/MACOS_SUPPORT.md. Security reporting is documented in SECURITY.md. Contribution rules are documented in CONTRIBUTING.md. Release notes are documented in CHANGELOG.md. Public release file boundaries are documented in docs/PUBLIC_RELEASE_MANIFEST.md.

Related MCP server: orchard-mcp

Quick Checks

uv run pytest
uv run python -m compileall src tests scripts
uv run python scripts/redaction_scan.py .
uv run python scripts/public_release_scan.py
uv run python scripts/audit_mutation_gates.py
uv run python scripts/audit_write_design_gates.py
uv run python scripts/audit_messages_public_surface.py --json
uv run python scripts/audit_surface_contract.py
uv run python scripts/audit_release_readiness.py --json
uv run python scripts/generate_release_receipt.py --json
uv run python scripts/render_mcp_client_config.py --client claude-code
uv run python scripts/render_mcp_client_config.py --client cursor
uv run python scripts/render_mcp_client_config.py --client openclaw --server-only --compact
uv run python scripts/build_public_release_tree.py --dest /tmp/local-apple-data-public --force
uv run python scripts/prepare_public_git_checkout.py --dest /tmp/local-apple-data-public-git --force --init-git --commit
uv run python scripts/verify_runtime.py
uv run local-apple-data health --json
uv run local-apple-data mail search --json --query '<subject text>'
uv run local-apple-data mail content --json --handle '<mail:message:v2:...>' --max-chars 4000
uv run local-apple-data mail attachments --json --handle '<mail:message:v2:...>'
uv run local-apple-data mail export-attachment --json --message-handle '<mail:message:v2:...>' --handle '<mail:attachment:v1:...>' --output-dir /tmp/local-apple-data-exports
uv run local-apple-data messages search --json --query '<chat display name text>'
uv run local-apple-data messages get --json --handle '<messages:chat:v1:...>' --max-messages 25 --max-chars 4000
uv run local-apple-data messages participants --json --handle '<messages:chat:v1:...>'
uv run local-apple-data messages participant --json --chat-handle '<messages:chat:v1:...>' --handle '<messages:participant:v1:...>'
uv run local-apple-data messages attachments --json --handle '<messages:chat:v1:...>'
uv run local-apple-data messages export-attachment --json --chat-handle '<messages:chat:v1:...>' --handle '<messages:attachment:v1:...>' --output-dir /tmp/local-apple-data-exports
uv run local-apple-data hide-my-email search --json --query '<specific alias substring>'
uv run local-apple-data hide-my-email get --json --handle '<hide_my_email:alias:v1:...>'
uv run local-apple-data voice-memos search --json --query '<recording title text>'
uv run local-apple-data voice-memos get --json --handle '<voice_memos:recording:v1:...>' --max-chars 4000
uv run local-apple-data voice-memos export --json --handle '<voice_memos:recording:v1:...>' --output-dir /tmp/local-apple-data-exports
uv run local-apple-data safari search --json --query '<bookmark title or URL text>'
uv run local-apple-data safari get --json --handle '<safari:item:v1:...>'
uv run local-apple-data shortcuts search --json --query '<shortcut or folder name text>'
uv run local-apple-data shortcuts get --json --handle '<shortcuts:item:v1:...>'
uv run local-apple-data shortcuts folder-items --json --handle '<shortcuts:item:v1:...>' --limit 5
uv run local-apple-data books search --json --query '<book title or author text>'
uv run local-apple-data books get --json --handle '<books:book:v1:...>'
uv run local-apple-data books annotations --json --handle '<books:book:v1:...>' --max-chars 4000
uv run local-apple-data podcasts search --json --query '<podcast show title or author text>'
uv run local-apple-data podcasts get --json --handle '<podcasts:show:v1:...>'
uv run local-apple-data podcasts episodes --json --handle '<podcasts:show:v1:...>'
uv run local-apple-data podcasts episode --json --handle '<podcasts:episode:v1:...>' --max-chars 4000
uv run local-apple-data music search --json --query '<track title or artist text>'
uv run local-apple-data music get --json --handle '<music:track:v1:...>'
uv run local-apple-data music playlists --json --query '<playlist name text>'
uv run local-apple-data music playlist --json --handle '<music:playlist:v1:...>'
uv run local-apple-data music playlist-tracks --json --handle '<music:playlist:v1:...>'
uv run local-apple-data tv search --json --query '<item title or show text>'
uv run local-apple-data tv get --json --handle '<tv:item:v1:...>'
uv run local-apple-data tv playlists --json --query '<playlist name text>'
uv run local-apple-data tv playlist --json --handle '<tv:playlist:v1:...>'
uv run local-apple-data tv playlist-items --json --handle '<tv:playlist:v1:...>'
uv run local-apple-data freeform boards --json --limit 5
uv run local-apple-data freeform get --json --handle '<freeform:board:v1:...>'
uv run local-apple-data freeform folders --json --query '<folder title text>' --limit 5
uv run local-apple-data freeform folder --json --handle '<freeform:folder:v1:...>'
uv run local-apple-data freeform folder-boards --json --handle '<freeform:folder:v1:...>'
uv run local-apple-data freeform child-folders --json --handle '<freeform:folder:v1:...>'
uv run local-apple-data notes search --json --query '<title or snippet text>'
uv run local-apple-data notes folders --json --query '<folder title text>'
uv run local-apple-data notes folder --json --handle '<notes:folder:v1:...>'
uv run local-apple-data notes folder-items --json --handle '<notes:folder:v1:...>' --limit 5
uv run local-apple-data notes folder-tree --json --handle '<notes:folder:v1:...>' --depth 2 --limit 10
uv run local-apple-data notes content --json --handle '<notes:note:v2:...>' --max-chars 4000 --offset 0
uv run local-apple-data notes content --json --handle '<notes:note:v2:...>' --content-format html
uv run local-apple-data notes attachments --json --handle '<notes:note:v2:...>'
uv run local-apple-data notes export-attachment --json --handle '<notes:attachment:v1:...>' --output-dir /tmp/local-apple-data-exports
uv run local-apple-data notes plan --json --operation create --title '<note title>' --body-text '<plain text>'
uv run local-apple-data notes apply --json --operation create --title '<note title>' --body-text '<plain text>' --approval-token '<notes-apply:v1:...>' --confirm-apply
uv run local-apple-data notes plan --json --operation create --title '<note title>' --folder-handle '<notes:folder:v1:...>' --body-text '<plain text>'
uv run local-apple-data notes apply --json --operation create --title '<note title>' --folder-handle '<notes:folder:v1:...>' --body-text '<plain text>' --approval-token '<notes-apply:v1:...>' --confirm-apply
uv run local-apple-data notes plan --json --operation create-html --title '<note title>' --body-html '<h1>title</h1><p>rich body</p>'
uv run local-apple-data notes apply --json --operation create-html --title '<note title>' --body-html '<h1>title</h1><p>rich body</p>' --approval-token '<notes-apply:v1:...>' --confirm-apply
uv run local-apple-data notes plan --json --operation replace-html --handle '<notes:note:v2:...>' --expected-current-sha256 '<extracted-text-sha256-from-content>' --body-html '<h1>title</h1><p>replaced rich body</p>'
uv run local-apple-data notes apply --json --operation replace-html --handle '<notes:note:v2:...>' --expected-current-sha256 '<extracted-text-sha256-from-content>' --body-html '<h1>title</h1><p>replaced rich body</p>' --approval-token '<notes-apply:v1:...>' --confirm-apply
uv run local-apple-data notes plan --json --operation append-text --handle '<notes:note:v2:...>' --expected-current-sha256 '<sha256-from-content>' --body-text '<text>'
uv run local-apple-data notes apply --json --operation append-text --handle '<notes:note:v2:...>' --expected-current-sha256 '<sha256-from-content>' --body-text '<text>' --approval-token '<notes-apply:v1:...>' --confirm-apply
uv run local-apple-data notes plan --json --operation delete --handle '<notes:note:v2:...>' --expected-current-sha256 '<sha256-from-content>'
uv run local-apple-data notes apply --json --operation delete --handle '<notes:note:v2:...>' --expected-current-sha256 '<sha256-from-content>' --approval-token '<notes-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive search --json --query '<filename text>'
uv run local-apple-data icloud-drive root --json
uv run local-apple-data icloud-drive content --json --handle '<icloud:file:v1:...>' --max-chars 4000
uv run local-apple-data icloud-drive export --json --handle '<icloud:file:v1:...>' --output-dir /tmp/local-apple-data-exports
uv run local-apple-data icloud-drive plan --json --operation create-folder --parent-handle '<icloud:file:v1:...>' --folder-name '<folder-name>'
uv run local-apple-data icloud-drive apply --json --operation create-folder --parent-handle '<icloud:file:v1:...>' --folder-name '<folder-name>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive plan --json --operation create-folder-path --parent-handle '<icloud:file:v1:...>' --folder-component '<folder-name>' --folder-component '<child-folder-name>'
uv run local-apple-data icloud-drive apply --json --operation create-folder-path --parent-handle '<icloud:file:v1:...>' --folder-component '<folder-name>' --folder-component '<child-folder-name>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive plan --json --operation rename-folder --handle '<icloud:file:v1:...>' --expected-current-sha256 '<metadata-sha256-from-folder-metadata>' --folder-name '<new-folder-name>'
uv run local-apple-data icloud-drive apply --json --operation rename-folder --handle '<icloud:file:v1:...>' --expected-current-sha256 '<metadata-sha256-from-folder-metadata>' --folder-name '<new-folder-name>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive plan --json --operation create-text --parent-handle '<icloud:file:v1:...>' --filename '<new-file.md>' --content-text '<text>'
uv run local-apple-data icloud-drive apply --json --operation create-text --parent-handle '<icloud:file:v1:...>' --filename '<new-file.md>' --content-text '<text>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive plan --json --operation append-text --handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --content-text '<text>'
uv run local-apple-data icloud-drive apply --json --operation append-text --handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --content-text '<text>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive plan --json --operation replace-text --handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --content-text '<text>'
uv run local-apple-data icloud-drive apply --json --operation replace-text --handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --content-text '<text>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive plan --json --operation rename-text --handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --filename '<new-name.md>'
uv run local-apple-data icloud-drive apply --json --operation rename-text --handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --filename '<new-name.md>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive plan --json --operation copy-text --handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --filename '<copy-name.md>'
uv run local-apple-data icloud-drive apply --json --operation copy-text --handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --filename '<copy-name.md>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data icloud-drive plan --json --operation move-text --handle '<icloud:file:v1:...>' --parent-handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>'
uv run local-apple-data icloud-drive apply --json --operation move-text --handle '<icloud:file:v1:...>' --parent-handle '<icloud:file:v1:...>' --expected-current-sha256 '<sha256-from-content>' --approval-token '<icloud-drive-apply:v1:...>' --confirm-apply
uv run local-apple-data calendar search --json --query '<event title text>'
uv run local-apple-data calendar get --json --handle '<calendar:event:v1:...>' --max-chars 4000
uv run local-apple-data calendar request-access --json
uv run local-apple-data calendar calendars --json --query '<calendar title text>' --include-default
uv run local-apple-data calendar calendar --json --handle '<calendar:calendar:v1:...>'
uv run local-apple-data calendar plan --json --operation create --title '<event title>' --calendar-title '<target calendar>' --start-date '<ISO timestamp>' --end-date '<ISO timestamp>'
uv run local-apple-data calendar plan --json --operation create --title '<event title>' --calendar-handle '<calendar:calendar:v1:...>' --start-date '<ISO timestamp>' --end-date '<ISO timestamp>'
uv run local-apple-data calendar plan --json --operation create --title '<event title>' --use-default-calendar --start-date '<ISO timestamp>' --end-date '<ISO timestamp>'
uv run local-apple-data calendar plan --json --operation create --title '<event title>' --calendar-handle '<calendar:calendar:v1:...>' --start-date '<ISO timestamp>' --end-date '<ISO timestamp>' --recurrence-frequency weekly --recurrence-count 6 --recurrence-interval 1
uv run local-apple-data calendar apply --json --operation create --title '<event title>' --calendar-title '<target calendar>' --start-date '<ISO timestamp>' --end-date '<ISO timestamp>' --approval-token '<calendar-apply:v1:...>' --confirm-apply
uv run local-apple-data calendar apply --json --operation update --handle '<calendar:event:v1:...>' --target-calendar-handle '<calendar:calendar:v1:...>' --expected-title '<current title>' --expected-calendar-title '<current calendar>' --expected-start-date '<ISO timestamp>' --expected-end-date '<ISO timestamp>' --expected-time-zone '<IANA time zone>' --title '<new title>' --start-date '<ISO timestamp>' --end-date '<ISO timestamp>' --time-zone '<IANA time zone>' --approval-token '<calendar-apply:v1:...>' --confirm-apply
uv run local-apple-data calendar plan --json --operation delete --handle '<calendar:event:v1:...>' --expected-title '<current title>' --expected-calendar-title '<current calendar>' --expected-start-date '<ISO timestamp>' --expected-end-date '<ISO timestamp>' --expected-location '<current location>' --expected-notes '<current notes>'
uv run local-apple-data calendar apply --json --operation delete --handle '<calendar:event:v1:...>' --expected-title '<current title>' --expected-calendar-title '<current calendar>' --expected-start-date '<ISO timestamp>' --expected-end-date '<ISO timestamp>' --expected-location '<current location>' --expected-notes '<current notes>' --approval-token '<calendar-apply:v1:...>' --confirm-apply
uv run local-apple-data calendar plan-calendar --json --operation create-calendar --source-calendar-handle '<calendar:calendar:v1:...>' --calendar-title 'LAD-TEST-<name>'
uv run local-apple-data calendar apply-calendar --json --operation create-calendar --source-calendar-handle '<calendar:calendar:v1:...>' --calendar-title 'LAD-TEST-<name>' --approval-token '<calendar-apply:v1:...>' --confirm-apply
uv run local-apple-data contacts search --json --query '<name or organization text>'
uv run local-apple-data contacts get --json --handle '<contacts:contact:v1:...>'
uv run local-apple-data contacts plan --json --operation create --contact-type person --given-name '<given>' --family-name '<family>' --email 'work=<email>'
uv run local-apple-data contacts apply --json --operation create --contact-type person --given-name '<given>' --family-name '<family>' --email 'work=<email>' --approval-token '<contacts-apply:v1:...>' --confirm-apply
uv run local-apple-data photos search --json --query '<original filename text>'
uv run local-apple-data photos request-access --json
uv run local-apple-data photos albums --json --query '<album title text>'
uv run local-apple-data photos album-assets --json --handle '<photos:album:v1:...>'
uv run local-apple-data photos get --json --handle '<photos:asset:v1:...>'
uv run local-apple-data photos export --json --handle '<photos:asset:v1:...>' --output-dir /tmp/local-apple-data-exports
uv run local-apple-data photos plan --json --operation import --source-file /path/to/local-image.jpg
uv run local-apple-data photos apply --json --operation import --source-file /path/to/local-image.jpg --approval-token '<photos-apply:v1:...>' --confirm-apply
uv run local-apple-data photos plan --json --operation update-flags --handle '<photos:asset:v1:...>' --favorite true --expected-favorite false --expected-hidden false
uv run local-apple-data photos apply --json --operation update-flags --handle '<photos:asset:v1:...>' --favorite true --expected-favorite false --expected-hidden false --approval-token '<photos-apply:v1:...>' --confirm-apply
uv run local-apple-data reminders due --json --days 14
uv run local-apple-data reminders eventkit-search --json --query '<reminder title text>'
uv run local-apple-data reminders request-access --json
uv run local-apple-data reminders lists --json
uv run local-apple-data reminders content --json --handle '<reminders:reminder:eventkit:v1:...>' --max-chars 4000
uv run local-apple-data reminders plan --json --operation create --title '<new reminder title>' --list-name '<target list name>' --due-date '<YYYY-MM-DD>'
uv run local-apple-data reminders apply --json --operation create --title '<new reminder title>' --list-name '<target list name>' --due-date '<YYYY-MM-DD>' --approval-token '<reminders-apply:v1:...>' --confirm-apply
uv run local-apple-data reminders plan-list --json --operation create-list --source-list-handle '<reminders:list:eventkit:v1:...>' --list-title 'Project New'
uv run local-apple-data reminders apply-list --json --operation create-list --source-list-handle '<reminders:list:eventkit:v1:...>' --list-title 'Project New' --approval-token '<reminders-apply:v1:...>' --confirm-apply

scripts/audit_release_readiness.py treats a dirty git worktree as a release blocker. Commit or remove source changes before using a release receipt as a clean handoff.

When writing a durable receipt file, use /tmp or another artifact directory outside the source checkout. scripts/generate_release_receipt.py --output rejects project-local paths so receipt generation cannot dirty a release candidate.

Run the plugin and skill validator scripts too when those local validator helpers are installed in the current Codex skills cache.

The installed-plugin consistency check for a configured local operator setup is:

cd /absolute/path/to/local-apple-data && uv run python scripts/verify_cross_agent_sync.py

If a Cursor project or global MCP config should be treated as mandatory, verify it explicitly:

uv run python scripts/verify_cross_agent_sync.py --require-cursor
uv run python scripts/verify_cross_agent_sync.py --cursor-config .cursor/mcp.json --require-cursor

The health command reports redacted local readiness only. Search commands may print local metadata such as subjects, Messages chat display names, masked inferred Hide My Email alias previews, Voice Memo titles, Safari bookmark titles/domains, Shortcuts names, Books titles/authors/genres, Podcasts show titles/authors/categories/providers, Music track/artist/album/playlist names, TV item/show/artist/genre/playlist names, Freeform folder metadata and board counts, note titles/snippets, Notes folder titles, calendar event titles, contact names/organizations, Photos filenames, iCloud Drive filenames, and reminder titles, so run them only for an intentional user-requested workflow. The Mail, Messages, inferred Hide My Email, Voice Memos, Safari, Shortcuts, Books, Podcasts, Music, TV, Freeform, Notes, Calendar, Contacts, Photos, Reminders, and iCloud Drive content/detail/folder-list/tree/export commands may print bounded local text, exact selected alias or URL detail, Books selected-book annotations, Podcasts selected-episode descriptions, Music selected-track/playlist/selected-playlist track metadata, TV selected-item/playlist/selected-playlist item metadata, Freeform selected-board/folder/selected-folder board/child-folder metadata, Notes selected-folder direct note/child-folder metadata and bounded child-folder tree metadata, asset/resource metadata, or caller-selected export paths and should be run only with an exact handle selected from metadata output.

Search handles are opaque and are generated from a local secret under the plugin state directory. They are not reusable credentials and are not logged. Mail search results include a best-effort metadata-only content_status hint of available, unavailable, or unknown; the hint checks local content-file availability without reading message bodies. Mail body, attachment, and advanced discovery require date bounds, cap returned results/snippets, redact email addresses in snippets, return masked header metadata, and still require exact handles for full content or attachment export. Hide My Email results are inferred from local Mail address metadata and set authoritative_inventory:false; they are not an iCloud account inventory or management API. Safari item search returns titles and URL metadata such as domain/scheme/query presence, not full URLs; Safari folder search/listing returns folder and direct child metadata only by exact safari:folder:v1: handle. Shortcuts search returns shortcut/folder names; folder-items returns contained shortcut names plus opaque handles only, not raw identifiers or shortcut bodies. Books search returns title/author/genre metadata and annotation counts only, not annotation text, book text, raw identifiers, or local paths. Podcasts search returns show metadata only; episode descriptions require exact episode handles and transcripts, audio bytes, feed/enclosure URLs, raw identifiers, and local download paths are not returned. Music search returns track/artist/album/genre and playlist metadata only; exact selected playlist-track listing is capped, and audio bytes, lyrics, file paths, raw identifiers, play history, ratings, and broad playlist track dumps are not returned. TV search returns item/show/artist/genre and playlist metadata only; exact selected playlist-item listing is capped, and video bytes, file paths, artwork, descriptions, playback state, watched state, ratings, and broad playlist item dumps are not returned. Freeform board/folder retrieval and selected-folder listings reject raw board rows, raw folder rows, raw identifiers, board BLOBs, decoded content, and asset export. Photos album-assets returns capped child asset metadata only for one exact photos:album:v1: handle, without resources, bytes, thumbnails, paths, or raw PhotoKit identifiers. Notes folder search returns folder-title metadata and notes:folder:v1: handles only, not raw folder IDs or account identifiers. Notes folder-items returns capped direct child folder metadata plus direct note metadata only for one exact folder handle, not note bodies, snippets, raw folder IDs, or account identifiers. Notes folder-tree returns capped descendant folder metadata only for one exact folder handle, not notes, note bodies, snippets, attachment bytes, paths, raw folder IDs, or account identifiers. Mail, Messages, inferred Hide My Email, Voice Memos, Safari, Shortcuts, Books, Podcasts, Music, TV, Freeform, Notes, Calendar, Contacts, Photos, Reminders, and iCloud Drive retrieval reject raw row IDs, older handle formats, mailbox refs, direct paths, raw framework identifiers, raw Hide My Email identifiers, raw Safari folder identifiers, raw Shortcuts identifiers, raw Books identifiers, raw Podcasts identifiers, raw Music identifiers, raw TV identifiers, raw Freeform identifiers, raw Notes folder identifiers, and arbitrary inputs.

Safety Model

See docs/PRIVACY_MODEL.md.

See also docs/THREAT_MODEL.md and docs/TESTING.md.

For the capability matrix, see docs/CAPABILITY_MATRIX.md. For future write gates, see docs/MUTATION_GATES.md. For the future write roadmap, see docs/WRITE_TOOL_ROADMAP.md. For the first Reminders write design gate, see docs/V1_11_REMINDERS_WRITE_DESIGN.md. For public release readiness, see docs/PUBLISHING.md. For installation, see docs/INSTALL.md. For synthetic examples, see docs/SAMPLE_OUTPUTS.md. For macOS support, see docs/MACOS_SUPPORT.md. For security reporting, see SECURITY.md. For public release file boundaries, see docs/PUBLIC_RELEASE_MANIFEST.md.

For exact Mail content behavior, see docs/PRIVACY_MODEL.md and docs/CAPABILITY_MATRIX.md.

For public MCP client setup, see docs/INSTALL.md and docs/CODEX_PLUGIN.md.

Codex Plugin

See docs/CODEX_PLUGIN.md.

License

MIT. See LICENSE.

Available Tools

30 tools

apple_data_doctorA

Read-onlyIdempotent

Return redacted non-mutating diagnostics and remediation guidance.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds useful context ('redacted non-mutating diagnostics') that aligns with and expands on the annotations, though it does not detail all behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the core action. Every word contributes meaning, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of parameters, strong annotations, and presence of an output schema, the description is mostly complete. It could briefly hint at the output structure, but the output schema covers that. The description is adequate for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so schema coverage is 100%. With no parameters, the baseline is 4, and the description does not need to add parameter information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'redacted non-mutating diagnostics and remediation guidance', specifying a verb and resource. However, it does not differentiate from the sibling tool 'apple_data_health', which may offer similar diagnostics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'apple_data_health' or other data retrieval tools. The description lacks context about appropriate use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

apple_data_healthA

Read-onlyIdempotent

Return redacted local readiness, schema checks, and access requirements.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by specifying the output includes 'readiness, schema checks, and access requirements,' which informs the agent about the nature of the data returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, clear sentence that is front-loaded with the action 'Return' and specifies the outputs concisely. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and an output schema (though not shown), the description adequately describes the return content. It could be more specific about the format or scope, but for a simple health check tool, it is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and the input schema is empty with 100% coverage. The description does not need to explain parameters. With zero parameters, a baseline of 4 is appropriate as per guidelines.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'redacted local readiness, schema checks, and access requirements,' specifying the verb 'return' and the resources. It distinguishes from the sibling tool 'apple_data_doctor' by focusing on readiness checks rather than general diagnostics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives. The sibling 'apple_data_doctor' may serve a similar purpose, but the description does not differentiate usage contexts or provide when-not-to-use instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

calendar_get_eventA

Read-onlyIdempotent

Get exact local Calendar event details by opaque handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_chars`	No
`days_back`	No
`days_forward`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds 'capped' which is not in annotations, providing extra context about limits. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with essential information, no redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters and existing output schema, the description is too brief. It does not explain what 'capped' means or the roles of days_back/days_forward, leaving gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate but only mentions 'opaque handle' for the handle parameter. The other parameters (max_chars, days_back, days_forward) are completely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'Calendar event', the method 'by opaque handle', and key characteristics 'capped and read-only'. It effectively distinguishes from sibling tools like `calendar_search` which searches for events.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when an opaque handle is available, but does not explicitly state when to use this tool versus alternatives or provide exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

calendar_searchC

Read-onlyIdempotent

Search local Calendar event metadata by title, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No
`days_back`	No
`days_forward`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds 'capped' (implied limit) and 'read-only' (redundant but consistent). It does not disclose that search is limited to metadata only, nor does it explain output behavior. Overall, minimal added value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 9 words, which is concise but insufficiently structured. It fails to cover multiple important aspects (e.g., parameter details), so it is under-specified rather than efficiently comprehensive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, the description does not mention return values or structure. Four parameters exist, but only one is hinted at. The tool's complexity (search with date ranges) is not addressed, leaving significant gaps for an AI agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameters. It only mentions 'by title' for the query parameter, but ignores limit, days_back, and days_forward. 'Capped' loosely relates to limit but is not explicit. No guidance on date ranges or the meaning of these parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search', the resource 'local Calendar event metadata', and the method 'by title'. It also adds 'capped and read-only' for scope. This distinguishes it from sibling search tools like notes_search or contacts_search, as it specifically targets calendar events.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when or when not to use this tool versus alternatives like calendar_get_event. The description only implies usage for title-based searches but does not mention scenarios where other tools are more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

contacts_getA

Read-onlyIdempotent

Get exact local Contact details by opaque handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_chars`	No
`max_scan_contacts`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds 'capped' beyond annotations (readOnlyHint, idempotentHint), implying output limits. Describes behavior as read-only and local. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Key information front-loaded: verb, resource, filter, constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists and annotations are comprehensive, so description can focus on purpose and constraints. Covers essential context: exact retrieval, local scope, capping. Minor gap: no mention of how to obtain the handle.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. Only mentions 'capped' which relates to parameters but does not explain handle, max_chars, or max_scan_contacts individually. Inadequate for a 3-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'Get', resource 'local Contact details', and method 'by opaque handle'. It effectively distinguishes from sibling 'contacts_search' by emphasizing exact retrieval with a handle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage when you have a handle, but lacks explicit when-not-to-use or direct comparison with siblings like 'contacts_search'. No mention of prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

contacts_searchB

Read-onlyIdempotent

Search local Contacts metadata by name or organization, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No
`max_scan_contacts`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. The description adds 'capped', hinting at result limits, and 'read-only' which aligns with annotations. Beyond this, no new behavioral context (e.g., auth needs, rate limits) is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and front-loaded, containing no extraneous information. Every word contributes to the meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool is simple and has an output schema, the description omits details about what 'metadata' includes, how limit and max_scan_contacts work, and differentiation from other search tools. It is minimally complete but lacks sufficient context for an agent to fully understand behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description only partially explains the query parameter as searching by name or organization, leaving limit and max_scan_contacts unexplained. The parameter names are self-explanatory but the description adds minimal value beyond the schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches local Contacts metadata by name or organization, with 'capped and read-only' distinguishing it from sibling search tools for other domains and retrieval tools like contacts_get.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lacks guidance on when to use this tool versus alternatives such as contacts_get for known IDs or other search tools for non-contacts data. No explicit when-not or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hide_my_email_get_aliasA

Read-onlyIdempotent

Get exact inferred Hide My Email alias detail by opaque handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint true, so no contradiction. The description adds 'capped' (potentially indicating rate limiting or maximum results) and 'exact inferred', providing context beyond annotations. However, it does not detail error handling or behavior for invalid handles.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no redundant words. Key elements (verb, resource, constraints) are front-loaded, making it efficient for an agent to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one parameter and annotations, the description minimally covers purpose and behavior. But it lacks parameter details and return value information (though output schema exists). For a simple tool, it is adequate but has gaps in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, meaning the description must compensate for parameter meaning. It only mentions 'by opaque handle', but does not explain what a handle is, its format, or how to obtain it. This is insufficient for an agent to correctly provide the parameter value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Get' and the resource 'exact inferred Hide My Email alias detail', specifying the input 'by opaque handle' and behavior 'capped and read-only'. This distinguishes it from the sibling tool 'hide_my_email_search' which likely returns multiple aliases without the handle constraint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when you have an opaque handle and need the exact alias detail, contrasting with searching. It mentions 'capped' suggesting a limit, but does not explicitly state when not to use or name alternatives. The sibling list includes 'hide_my_email_search' which aids differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hide_my_email_searchB

Read-onlyIdempotent

Search inferred Hide My Email aliases from local Mail metadata, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond annotations: 'inferred' hints at potential inaccuracies, and 'capped' implies a result limit. Combined with readOnlyHint=true and destructiveHint=false annotations, the agent has a good safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads key information (action, resource, source, constraints). However, it omits parameter details, which could be seen as under-specification rather than conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose and safety but fails to address parameter usage, search behavior (e.g., partial matching), or the meaning of 'inferred'. Given an output schema exists, return format is not needed, but the parameter and usage gaps make it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description provides no explanation for the 'query' or 'limit' parameters. The term 'capped' weakly hints at the limit parameter, but without explicit parameter semantics, the agent lacks critical usage details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (search), the resource (inferred Hide My Email aliases), and the data source (local Mail metadata). It distinguishes from sibling tools like hide_my_email_get_alias (specific alias retrieval) and mail_search (general mail search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide when to use this tool versus alternatives like hide_my_email_get_alias or other search tools. It mentions 'capped and read-only' but offers no explicit guidance on selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

icloud_drive_get_contentA

Read-onlyIdempotent

Get exact local iCloud Drive text content by opaque handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_chars`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already set readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds 'capped' (relating to max_chars parameter) and reiterates 'read-only', but does not detail behavior beyond that, such as error handling or what happens with invalid handles.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that is densely informative, front-loaded with the verb 'Get', and includes all key aspects (resource, parameter, modifiers). No redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, annotations, and existence of an output schema, the description covers the essential purpose and parameter hints. It lacks explanation of return format or edge cases, but these are mitigated by the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no descriptions on parameters). Description mentions 'by opaque handle' for handle and 'capped' for max_chars, providing basic mapping. However, it does not explain the nature of the handle or constraints on max_chars, leaving gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it retrieves iCloud Drive text content using an opaque handle, with a cap and read-only access. It distinguishes itself from sibling tools like icloud_drive_get_metadata (metadata retrieval) and icloud_drive_search (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for fetching content by handle and notes 'capped' and 'read-only', but lacks explicit guidance on when not to use this tool or mention of alternative tools. Context from sibling names provides differentiation, but description does not directly advise.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

icloud_drive_get_metadataA

Read-onlyIdempotent

Get exact local iCloud Drive metadata by opaque handle. File content is not returned.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the already safe annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds that it returns 'exact local' metadata and clarifies that no content is returned. This provides useful behavioral context about the tool's scope and precision.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—two short sentences—with no unnecessary words. It efficiently conveys the core purpose and a key behavioral trait.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and an existing output schema, the description covers the essential points: purpose, method, and what is not returned. It is sufficient for an agent to understand the tool's role, though it could briefly mention when to use it over siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero description coverage for the 'handle' parameter. The description compensates by labeling it as an 'opaque handle,' indicating it is an identifier (likely from a previous search) rather than a name or path. This adds crucial meaning for the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get'), the resource ('local iCloud Drive metadata'), and the method ('by opaque handle'). It also explicitly says that file content is not returned, which distinguishes it from icloud_drive_get_content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that this tool is for metadata only, but it does not explicitly name alternatives like icloud_drive_get_content or icloud_drive_search. The phrase 'File content is not returned' hints at when to use a different tool, but it lacks explicit when-to-use or when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

icloud_drive_searchA

Read-onlyIdempotent

Search local iCloud Drive metadata by filename, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds 'capped' (implying result limit) and 'read-only', which partially overlaps with annotations but adds useful context. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that immediately conveys the tool's purpose without extraneous words. Every phrase is essential.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, 1 required) and the presence of an output schema, the description is mostly complete. It covers the core operation but could mention that it searches metadata only, not file contents.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% (no property descriptions). The description only mentions 'by filename', but does not explain the query parameter format or the limit parameter's behavior. It fails to compensate for the missing schema details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'search', the resource 'local iCloud Drive metadata', and the scope 'by filename'. It effectively distinguishes this tool from sibling search tools like calendar_search or mail_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like icloud_drive_get_metadata. The description mentions 'capped and read-only' but does not provide context for selection or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mail_get_contentC

Read-onlyIdempotent

Get exact local Mail plain-text content by opaque v2 handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_chars`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. Description adds 'capped and read-only' which is redundant. No additional behavioral context (e.g., error handling, caching).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise, but sacrifices clarity on parameters and usage. Could be more structured without increasing length much.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple (2 params, output schema exists), but description fails to explain parameter semantics or usage context, making it incomplete for effective selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet description provides no explanation of 'handle' or 'max_chars' parameters. 'opaque v2 handle' is vague and insufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb ('Get'), resource ('local Mail plain-text content'), and constraints ('by opaque v2 handle, capped and read-only'). Distinct from siblings like mail_get_metadata and mail_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool over alternatives or when not to use it. Context signals show sibling tools like mail_get_metadata for metadata, but description doesn't clarify.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mail_get_metadataA

Read-onlyIdempotent

Get exact local Mail metadata by handle. Message bodies are not returned.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the key behavioral detail that message bodies are not returned, which is beyond annotations and important for correct usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single 12-word sentence that front-loads the core action and includes an important constraint. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low parameter count, rich annotations, and presence of an output schema, the description is mostly adequate but lacks explanation of the 'handle' parameter meaning.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single required parameter 'handle' has no description in the schema (0% coverage), and the description merely says 'by handle' without explaining what a handle is or where to obtain it. More param detail is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves local Mail metadata by handle, and explicitly notes that message bodies are not returned. This differentiates it from sibling tools like mail_get_content and mail_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for metadata retrieval without bodies, but does not explicitly state when to use this tool over alternatives or provide context on prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mail_searchB

Read-onlyIdempotent

Search local Mail metadata by subject, including metadata-only content availability.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the search is subject-based and includes metadata-only content availability, which provides useful context. However, it does not disclose other behaviors like case sensitivity, search scope, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the key purpose. It contains no wasted words and effectively conveys the tool's function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only 2 parameters and an output schema (as per context), the description minimally covers the purpose. It mentions 'metadata-only content availability' which hints at return values, but could provide more detail on sorting, pagination, or limitations. It is adequate for a simple search tool but not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate. It hints that 'query' is a subject search but does not specify format, wildcards, or the meaning of 'metadata-only content availability' for the limit parameter. The limit parameter is left entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the action ('Search'), the resource ('local Mail metadata'), and the method ('by subject'), while also noting the inclusion of metadata-only content availability. This effectively distinguishes it from sibling tools like mail_get_metadata and mail_get_content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as mail_search for full-text vs. subject-only, or when to prefer calendar_search or notes_search. There is no mention of prerequisites, limits, or comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

messages_get_chatA

Read-onlyIdempotent

Get exact local Messages chat transcript by opaque handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_messages`	No
`max_chars`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds 'capped' and 'local', providing behavioral context beyond what annotations capture. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 11 words, front-loading the purpose and key features. No unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, main parameter, and constraints (capped, read-only). With an output schema present, return values are assumed documented. However, it lacks explanation of the 'opaque handle' and how to obtain it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description partially compensates by mentioning 'by opaque handle' and 'capped' (relating to max_messages and max_chars). However, it does not explain what 'opaque handle' means or provide details on the format of the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'local Messages chat transcript', and the key distinguishing features 'by opaque handle, capped and read-only'. It differentiates from siblings like 'messages_search' which searches rather than retrieves by handle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have the opaque handle, but does not explicitly state when to use this tool versus alternatives like 'messages_search'. No guidance on when not to use or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

messages_searchA

Read-onlyIdempotent

Search local Messages chat metadata by display name, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds 'capped' and 'by display name', which are behavioral traits not fully captured in annotations, giving additional context about result limits and search criteria.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence of 7 words. Every word is meaningful, no fluff, and it efficiently conveys the core purpose and constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description does not need to explain return values. It covers input semantics adequately for a simple tool, though it could specify that only metadata (not content) is searched.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description partially compensates by explaining that 'query' is used for display name search. However, it does not describe the 'limit' parameter beyond the vague 'capped', leaving its role and default partially inferred.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the verb 'Search', the resource 'local Messages chat metadata', and the filter criterion 'by display name', clearly distinguishing it from sibling tools that search other resources or perform other operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like messages_get_chat or other search tools. It only states what it does without clarifying when not to use it or suggesting alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notes_get_contentA

Read-onlyIdempotent

Get exact local Notes plain-text content by opaque v2 handle, capped, paged, and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_chars`	No
`offset`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint true, destructiveHint false, and idempotentHint true, ensuring safe usage. The description adds behavioral context with 'capped, paged, and read-only', informing the agent about pagination and value limits beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the main action. It is concise, though the dense phrasing (e.g., 'capped, paged') might reduce clarity slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema, the description does not need to explain return values. However, it lacks parameter clarity and usage context relative to siblings, making it incomplete for full standalone understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description should explain parameters, but it only hints at 'capped' and 'paged' relating to max_chars and offset. It does not define the 'opaque v2 handle' or explain the default/behavior of max_chars and offset, leaving ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves 'exact local Notes plain-text content', specifying the resource (Notes) and the operation (get content). It mentions the use of an 'opaque v2 handle', which distinguishes it from sibling tools like notes_get_metadata (metadata) and notes_search (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when plain-text content is needed, but provides no explicit guidance on when not to use this tool or alternative tools. Given many sibling tools, clearer differentiation would help.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notes_get_metadataA

Read-onlyIdempotent

Get exact Apple Notes metadata by handle. Note bodies are not returned.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds that note bodies are not returned, which is a useful behavioral detail. However, it does not disclose any other behavioral traits such as authentication needs or rate limits. The added value is modest.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two short, direct sentences with no unnecessary words or redundancies. It is well-structured and front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (single parameter, output schema exists) and comprehensive annotations, the description covers the essential purpose and a key behavioral constraint. However, the lack of parameter semantics for 'handle' leaves ambiguity, preventing full contextual completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides no description for the 'handle' parameter (0% coverage), and the description does not clarify its format (e.g., UUID vs. title). The phrase 'by handle' offers minimal guidance. Given low schema coverage, the description should compensate but fails to do so.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'Apple Notes metadata', and the method 'by handle'. It also explicitly notes that note bodies are not returned, distinguishing it from notes_get_content and notes_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when retrieving metadata by handle, but it does not provide explicit guidance on when to use this tool versus alternatives like notes_get_content or notes_search, nor does it mention prerequisites or limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notes_searchA

Read-onlyIdempotent

Search local Apple Notes metadata by title/snippet, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds 'capped' (result limit) which is not in annotations, providing useful extra behavioral context with no contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, extremely concise while conveying core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a likely output schema and strong annotations covering safety, the description is fairly complete for a straightforward search tool. Lacks details on sorting or pagination but acceptable given low parameter complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It mentions 'by title/snippet' giving context for the query parameter but not its format. 'Capped' hints at a limit but does not explain the limit parameter explicitly. Insufficient to fully understand parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'search', resource 'local Apple Notes metadata', and method 'by title/snippet', but does not explicitly differentiate from sibling tools like notes_get_content or notes_get_metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage context for searching notes by title/snippet is given, but no explicit when-to-use or when-not-to-use guidance, nor alternatives named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

photos_export_assetB

Read-onlyIdempotent

Export exact local Photos asset bytes by opaque handle to a caller-selected directory.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`output_dir`	Yes
`filename`	No
`max_scan_assets`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it exports to a caller-selected directory, but does not detail side effects like file overwriting or permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, efficient sentence that immediately conveys the core purpose. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 4 parameters (2 required) and no schema descriptions, the description is too minimal. It does not explain how to obtain the handle, the expected format of output_dir, or the effect of filename and max_scan_assets.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain any parameters beyond their names. 'opaque handle' is mentioned but not clarified. Required parameters like handle and output_dir are not described.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (export), resource (local Photos asset bytes), and method (by opaque handle to a caller-selected directory). It distinguishes from siblings like `photos_get_asset` by specifying exact bytes export.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like `photos_get_asset`. No prerequisites mentioned, such as needing to obtain a handle first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

photos_get_assetA

Read-onlyIdempotent

Get exact local Photos asset metadata by opaque handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_scan_assets`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context beyond annotations by specifying 'local' (scope) and 'capped' (a constraint on scanning). This provides useful additional transparency without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-crafted sentence that includes all essential elements: action, resource, identification method, and constraints. No unnecessary words or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema and annotations, the description covers the core purpose and constraints. However, it fails to explain the parameters (0% coverage), leaving a significant gap for a low-complexity tool with only 2 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should compensate. However, it only mentions 'by opaque handle' and 'capped', without explaining the 'handle' parameter or the 'max_scan_assets' parameter. The agent lacks sufficient guidance on what these parameters mean or how to use them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'local Photos asset metadata', and the method 'by opaque handle'. It also notes 'capped and read-only', which distinguishes it from sibling tools like photos_search (search) and photos_export_asset (export).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when an opaque handle is available, but it does not explicitly state when to use this tool versus alternatives like photos_search or photos_export_asset. No when-not or alternative guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

photos_searchB

Read-onlyIdempotent

Search local Photos metadata by original filename, capped and read-only.

ParametersJSON Schema

Name	Required	Default
`query`	Yes
`limit`	No
`media_type`	No	all
`max_scan_assets`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds 'capped' (implying limited results) and 'local', but provides no further behavioral details such as how cap works, what happens on limit exceed, or any other side effects. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys key aspects: action, resource, filter, and constraints. No unnecessary words, though it could be slightly more detailed without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters (1 required), an output schema, and is a search operation, the description is too brief. It does not cover parameter meaning, result format, or how the 'capped' behavior works. The output schema exists but the description offers no guidance on its content.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must explain parameters. It only hints that 'query' is an original filename, but does not describe 'limit', 'media_type', or 'max_scan_assets'. This is insufficient for an agent to understand parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search'), resource ('local Photos metadata'), filter ('by original filename'), and constraints ('capped and read-only'). It distinguishes itself from sibling tools like photos_export_asset and photos_get_asset by focusing on metadata search by filename.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching local Photos by filename but does not explicitly state when to use this tool over alternatives or when not to use it. It lacks exclusion criteria or context about alternatives like other search tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reminders_dueB

Read-onlyIdempotent

List local Apple Reminders metadata due in a bounded window.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns 'metadata due in a bounded window', but doesn't disclose behavior beyond what annotations and name suggest. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no fluff. It is concise but could benefit from minimal additional context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema and annotations, the description provides a basic understanding. However, it omits details like the direction of the time window (past due vs upcoming) and whether only incomplete reminders are returned. Adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, and the description does not explain the 'days' and 'limit' parameters. 'bounded window' hints at 'days' purpose, but lacks detail. The description fails to compensate for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'list local Apple Reminders metadata due in a bounded window', specifying the verb and resource. It distinguishes from siblings like 'reminders_search' (text-based) and 'reminders_get_content' (full content). However, it could be more explicit about the time window direction (past/future).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus its siblings, such as 'reminders_search' or 'reminders_eventkit_search'. The description lacks context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reminders_eventkit_searchA

Read-onlyIdempotent

Search local Reminders through EventKit by title, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No
`include_completed`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds 'capped' and 'read-only', but 'capped' is vague and does not clarify behavior when the limit is reached (e.g., truncation vs. error). The description adds marginal behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the core functionality without extraneous words. It is front-loaded and efficient, though it could benefit from slight expansion for completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not shown) and annotations, the description covers the essentials for a simple search tool. However, it lacks details on error handling, performance, or how the cap interacts with the limit parameter, which would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only mentions 'by title', hinting at the query parameter, but fails to explain 'limit' and 'include_completed'. While parameter names are somewhat self-explanatory, the description does not adequately clarify their semantics or usage constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches local Reminders via EventKit by title, with a cap and read-only access. It distinguishes from sibling tools like reminders_search (possibly broader) and reminders_due (filtered by due date).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching local reminders by title but does not explicitly state when to use this tool over alternatives like reminders_search or reminders_due. No exclusions or alternative guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reminders_get_contentA

Read-onlyIdempotent

Get exact local Reminder notes by opaque EventKit handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_chars`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds context that it retrieves 'exact local' notes and is 'capped', which aligns with annotations and clarifies the scope beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no waste. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with an output schema, the description covers the core purpose, constraints, and scope. It lacks detail on handle format and output structure but is sufficient given the output schema's presence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate but does not mention parameters. It loosely references 'capped' relating to max_chars, but provides no explicit meaning or guidance for handle or max_chars beyond what the schema shows.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (get), the resource (local Reminder notes), the method (by opaque EventKit handle), and constraints (capped, read-only). It is specific and distinguishes from siblings like reminders_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (when you have a specific handle) but provides no explicit guidance on when to use this tool versus alternatives like reminders_search or reminders_eventkit_search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reminders_plan_changeA

Read-onlyIdempotent

Plan a future Reminder change without reading or mutating Reminders state.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes
`title`	No
`list_name`	No
`due_date`	No
`notes`	No
`handle`	No
`expected_title`	No
`expected_completed`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds context that the tool plans future changes without read/mutate, which goes beyond the annotations (readOnlyHint, destructiveHint, idempotentHint) by clarifying the planning nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no redundancy, efficiently conveying the core function and constraint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description states the overall purpose, it fails to explain parameters or provide enough context for correct invocation, given the tool has 8 parameters and 0% schema description coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and no parameter explanations in the description, the agent lacks guidance on how to use the 8 parameters, especially 'operation' being required but undefined.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool plans a future Reminder change without reading or mutating state, distinguishing it from sibling tools like reminders_search or reminders_get_content that perform reads or mutations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for planning changes without immediate effect but does not explicitly state when to use or avoid, nor does it name alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reminders_searchA

Read-onlyIdempotent

Search local Apple Reminders metadata by title only, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds 'capped' and 'by title only', which are behavioral traits not captured in structured fields. This adds value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with key information (search, resource, constraints), no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given existing output schema and rich annotations, the description covers the essential aspects: what is searched, how, and constraints. It is complete for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It clarifies that query is a title search, but provides no extra info for limit beyond its default. Adequate but not excellent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it searches reminders metadata by title only, differentiating it from sibling tools like reminders_eventkit_search or reminders_get_content. The verb 'search' and resource 'local Apple Reminders metadata' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when searching reminders by title. It notes it's read-only and capped, providing clear context but not explicitly stating when not to use or listing alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

voice_memos_export_audioA

Read-onlyIdempotent

Export exact local Voice Memo audio by opaque handle to a caller-selected directory.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`output_dir`	Yes
`filename`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds 'exact' and 'opaque handle' context but does not detail file format, overwrite behavior, or error handling. It is consistent with annotations and adds some value, but not rich behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence of 12 words that immediately conveys action and resource. No redundancy or fluff – every word earns its place. Excellent front-loading.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complex context (many sibling tools, 3 params, annotations present, output schema exists), the description is minimal. It covers the core purpose but lacks details on invocation context, error conditions, and file handling. Adequate but leaves gaps for an agent without additional documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains 'handle' as opaque and 'output_dir' as caller-selected, but does not clarify the 'filename' parameter (default empty) or expected formats. The description adds some meaning but is incomplete for all parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description precisely states the action (export), the resource (local Voice Memo audio), and the mechanism (by opaque handle to caller-selected directory). It clearly distinguishes from sibling tools like voice_memos_get_recording and voice_memos_search by specifying the output to a local directory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (to get actual audio file) but does not explicitly contrast with alternatives or state prerequisites (e.g., obtaining the handle via search). No exclusions or when-not-to-use guidance is provided, leaving the agent to infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

voice_memos_get_recordingA

Read-onlyIdempotent

Get exact local Voice Memo metadata/transcript by opaque handle, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`handle`	Yes
`max_chars`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds 'capped and read-only', which clarifies the behavioral trait of truncation (via max_chars) and reinforces safety. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence that front-loads the key action and resource. Every word adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complex ecosystem of sibling tools, this description provides sufficient context for a get-by-ID operation. An output schema exists, so return values are covered. It could mention what metadata includes, but is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It clarifies that 'handle' is opaque and 'capped' implies max_chars limits the response. However, it does not explicitly describe the parameters or their formats beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets 'exact local Voice Memo metadata/transcript' using an 'opaque handle', specifying it is 'capped and read-only'. This distinguishes it from sibling tools like voice_memos_search and voice_memos_export_audio.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have an opaque handle for a voice memo and want metadata/transcript. It does not explicitly state when not to use or mention alternatives, but the context of 'exact' and 'handle' suggests prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

voice_memos_searchA

Read-onlyIdempotent

Search local Voice Memos metadata by title or filename, capped and read-only.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already convey read-only and idempotent behavior. The description adds 'capped' (results limited) and 'by title or filename' (search scope), which are extra behavioral details beyond annotations. No contradiction found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 9 words, maximally concise and front-loaded. No extraneous information; every word contributes to clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and annotations, the description adequately covers the tool's purpose and key constraints (search fields, capped, read-only). It could mention that it returns metadata only, but the output schema handles return format. Overall sufficient for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema parameter descriptions are absent (0% coverage). The description explains that the 'query' parameter searches by title or filename, and 'capped' hints at the 'limit' parameter controlling result count. This adds meaningful context beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches 'local Voice Memos metadata by title or filename', specifying the resource, action, and search fields. This distinguishes it from siblings like calendar_search and contacts_search, which target different data types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for voice memos search but provides no explicit guidance on when to use it versus alternatives (e.g., other search tools). It lacks exclusions or context for when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation5/5

Tools are grouped by domain with distinct operations (search, get, export). Each tool targets a specific resource and action, e.g., notes_get_content vs notes_get_metadata, or reminders_due vs reminders_search. Overlaps are minimal and clarified by descriptions.

Naming Consistency4/5

Most tools follow a consistent <domain>_<verb>_<object> snake_case pattern. However, some deviations exist: 'reminders_due' lacks a verb, and 'reminders_eventkit_search' includes an extra specifier. Overall pattern is clear but not perfectly uniform.

Tool Count3/5

30 tools cover many Apple data domains (calendar, contacts, mail, etc.). While each domain has a reasonable number (2-3 tools), the total count is high. It is justified for the broad scope but feels heavy.

Completeness4/5

For each domain, the set provides search, get metadata, and get content (or export). Diagnostics are included. Missing mutation/delete operations are intentional (read-only). Minor gaps include no bulk operations or filter criteria beyond title, but core workflows are covered.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

thoughts
ai.thoughtbox.api
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Cloud Storage Finance
2
nylas A
io.usefulapi
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Email Calendar Management CRM
152
messages-bridge
io.github.IsaiahDupree
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Communication App Automation
1
ContextLattice
io.github.sheawinkler
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Knowledge & Memory Agent Orchestration Autonomous Agents
2152

Related MCP Servers

nucleus-apple-mcp
Calendar Management Note Taking Health & Wellness
zish-rob-crur
A
license
B
quality
B
maintenance
A macOS MCP server that provides AI agents with secure access to Calendar, Reminders, Notes, and Health data via native Apple APIs.
Updated 2 months ago (2026-06-21 04:30 UTC)
30
20
MIT
orchard-mcp
Calendar Management Email File Systems
l22-io
A
license
Not graded
quality
B
maintenance
MCP server for Apple Calendar, Mail, Reminders, and Files on macOS using native frameworks.
Updated 3 months ago (2026-06-19 08:51 UTC)
42
18
MIT
Errol-Mail
Email Communication
jasondk
A
license
Not graded
quality
C
maintenance
An MCP server that gives AI assistants comprehensive access to Apple Mail accounts, enabling email discovery, reading, flag management, and server-side message retrieval.
Updated 21 days ago (2026-08-14 00:29 UTC)
MIT
Honeycrispofficial
Email Calendar Management File Systems
cortland-suite
A
license
Not graded
quality
B
maintenance
MCP servers for your Mac's real data — Mail, Calendar, files — with safety rails you can audit. Local-first, no accounts, no cloud, with dry-run defaults and human approval gates.
Updated 8 days ago (2026-08-27 03:39 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/BillyBunn/local-apple-data'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

local-apple-data

Current Status

Quick Checks

Safety Model

Codex Plugin

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Honeycrispofficial

Latest Blog Posts

MCP directory API