apple-notes-mcp 2.0.1 → 2.1.1

package/README.md

@@ -6,6 +6,10 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
 [![CI](https://github.com/sweetrb/apple-notes-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sweetrb/apple-notes-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<p align="center">
+  <img src="codex/assets/screenshot.png" alt="Apple Notes MCP — create, search, and organize Apple Notes from Codex, Claude, and other AI assistants" width="680">
+</p>
+
 ## What is This?
 
 This server acts as a bridge between AI assistants and Apple Notes. Once configured, you can ask Claude (or any MCP-compatible AI) to:
@@ -41,6 +45,21 @@ Install as a Claude Code plugin for automatic configuration and enhanced AI beha
 
 This method also installs a **skill** that teaches Claude when and how to use Apple Notes effectively.
 
+### Using the Codex Marketplace
+
+The same plugin is available for Codex. Add the marketplace and install the plugin:
+
+```bash
+codex plugin marketplace add sweetrb/apple-notes-mcp
+codex plugin add apple-notes@apple-notes-mcp
+```
+
+The Codex plugin runs the published `apple-notes-mcp` server through `npx` and ships the same Apple Notes skill, so behavior matches the Claude Code plugin.
+
+### Other Hosts (Hermes, Antigravity)
+
+Plugin packaging for the Hermes and Antigravity hosts is also included (`.hermes-plugin/` and `.antigravity-plugin/`). Each registers the same `apple-notes` MCP server (launched via `npx -y apple-notes-mcp`) and bundles the Apple Notes skill, so behavior matches the Claude Code and Codex plugins. Install them through each host's plugin/marketplace mechanism pointed at this repository.
+
 ### Manual Installation
 
 **1. Install the server:**
@@ -102,6 +121,15 @@ Resources expose read-only context the client can attach without a tool call:
 `notes://note/{id}` template (returns the note as Markdown). Prompts package
 common workflows: `find-note`, `weekly-review`, `new-meeting-note`.
 
+### Known limitations
+
+A few Notes UI features are not exposed to AppleScript and therefore cannot be
+supported. See **[docs/APPLESCRIPT-LIMITATIONS.md](docs/APPLESCRIPT-LIMITATIONS.md)**
+for the investigation and verification behind each:
+
+- **Pinned notes** — Notes has no scriptable `pinned` property, so pin state can be neither read nor set.
+- **Note-to-note links** — there is no `applenotes://` deep link or link property; the only stable handle is the `x-coredata://` note id.
+
 ---
 
 ## Tool Reference
@@ -224,7 +252,10 @@ Retrieves the full content of a specific note.
 }
 ```
 
-**Returns:** The HTML content of the note, or error if not found.
+**Returns:** The HTML content of the note, or error if not found. The
+`structuredContent` also includes `hashtags` — any inline `#hashtag` tags parsed
+from the body. Apple Notes tags are inline hashtags, not a scriptable property;
+see [docs/APPLESCRIPT-LIMITATIONS.md](../docs/APPLESCRIPT-LIMITATIONS.md#tags--hashtags-29). Smart Folders are not scriptable.
 
 ---
 
@@ -322,6 +353,8 @@ Updates an existing note's content and/or title.
 
 **Returns:** Confirmation message, or error if note not found.
 
+**Note:** `newContent` **replaces the entire note body** — it is not appended. To preserve existing content, read it first (e.g. with `get-note-content`) and include it in `newContent`.
+
 ---
 
 #### `delete-note`
@@ -352,6 +385,8 @@ Deletes a note (moves to Recently Deleted in Notes.app).
 
 **Returns:** Confirmation message, or error if note not found.
 
+**⚠️ Safety:** Irreversible from the agent's side — requires explicit user confirmation before calling. Prefer `search-notes` / `list-notes` first to confirm the exact id(s) being deleted.
+
 ---
 
 #### `move-note`
@@ -481,6 +516,8 @@ Deletes a folder.
 
 **Returns:** Confirmation message, or error if folder not found or not empty.
 
+**⚠️ Safety:** Irreversible — requires explicit user confirmation before calling. Prefer `list-folders` first to confirm the exact folder path being deleted.
+
 ---
 
 ### Account Operations
@@ -512,6 +549,8 @@ Deletes multiple notes at once by ID.
 
 **Returns:** Summary of successes and failures.
 
+**⚠️ Safety:** Irreversible — requires explicit user confirmation before calling. Prefer `search-notes` / `list-notes` first to confirm the exact ids being deleted.
+
 ---
 
 #### `batch-move-notes`
@@ -653,6 +692,8 @@ Gets comprehensive statistics about your notes.
 
 **Returns:** Total counts, per-account breakdown, folder statistics, and recently modified counts.
 
+The `structuredContent` also includes a `coverage` object — `{ complete, scanned, covered, warnings[] }`. If `complete` is `false`, one or more accounts (or the recent-activity scan) could not be read and the counts reflect only the scopes that succeeded; the text output adds a "⚠️ Partial results" line. This lets you tell a genuinely empty library apart from a partial failure.
+
 ---
 
 #### `get-sync-status`
@@ -946,13 +987,21 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 ## Development
 
 ```bash
-npm install      # Install dependencies
-npm run build    # Compile TypeScript
-npm test         # Run test suite (313 tests)
-npm run lint     # Check code style
-npm run format   # Format code
+npm install            # Install dependencies
+npm run build          # Compile TypeScript
+npm test               # Run unit test suite (mocked AppleScript)
+npm run test:integration  # Run integration tests against real Notes.app
+npm run test:all       # Unit + integration
+npm run lint           # Check code style
+npm run format         # Format code
 ```
 
+The integration suite (`test/integration.test.ts`) drives the real
+`AppleNotesManager → AppleScript → Notes.app` stack — creating, reading,
+searching, and deleting throwaway notes. Its live tests self-skip when no
+writable Notes account is available (e.g. CI), so it is safe to run anywhere;
+the pure path-safety and hashtag tests always run.
+
 ---
 
 ## Author
@@ -974,6 +1023,12 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gui
 
 ## Related Projects
 
-- [apple-mail-mcp](https://github.com/sweetrb/apple-mail-mcp) — MCP server for Apple Mail
-- [apple-numbers-mcp](https://github.com/sweetrb/apple-numbers-mcp) — MCP server for Apple Numbers spreadsheets
-- [apple-photos-mcp](https://github.com/sweetrb/apple-photos-mcp) — MCP server for Apple Photos
+Part of a family of macOS MCP servers:
+
+- [apple-mail-mcp](https://github.com/sweetrb/apple-mail-mcp) — MCP server for Apple Mail (read, search, send, and organize email)
+- [apple-numbers-mcp](https://github.com/sweetrb/apple-numbers-mcp) — MCP server for Apple Numbers (read and write .numbers spreadsheets)
+- [apple-photos-mcp](https://github.com/sweetrb/apple-photos-mcp) — MCP server for Apple Photos (query metadata and export originals)
+
+## Recurring macOS permission prompts
+
+If macOS keeps re-prompting for Full Disk Access or Automation for `node` (often after a `brew upgrade`), see [docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md](docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md) — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.

package/build/index.js

@@ -27,6 +27,7 @@ import { AppleNotesManager } from "./services/appleNotesManager.js";
 import { getSyncStatus, withSyncAwarenessSync } from "./utils/syncDetection.js";
 import { getChecklistItems, hasFullDiskAccess } from "./utils/checklistParser.js";
 import { detectChecklistAttempt } from "./utils/contentWarnings.js";
+import { parseHashtags } from "./utils/hashtags.js";
 import { runDoctor, formatDoctorReport } from "./tools/doctor.js";
 import { loadFileConfig } from "./services/fileConfig.js";
 import { registerResourcesAndPrompts } from "./tools/resourcesAndPrompts.js";
@@ -107,7 +108,7 @@ const folderNameSchema = {
 // Note Tools
 // =============================================================================
 // --- create-note ---
-server.tool("create-note", {
+server.tool("create-note", "Use when: the user wants to create a brand-new Apple Note.\nReturns: the new note's title and id — reuse the id for follow-up reads/edits.\nDo not use when: editing an existing note (use update-note).\nNote: the title is prepended as an <h1>; true Apple Notes checklists cannot be created via AppleScript (see the content field).", {
     title: z.string().min(1, "Title is required"),
     content: z
         .string()
@@ -133,7 +134,7 @@ server.tool("create-note", {
     return successResponse(`Note created: "${note.title}" [id: ${note.id}]${checklistWarning}`);
 }, "Error creating note"));
 // --- search-notes ---
-server.tool("search-notes", {
+server.tool("search-notes", "Use when: finding notes by a keyword in the title (or body with searchContent=true) and you need their ids.\nReturns: matching notes with title, folder, and id.\nDo not use when: you already have a note id (use get-note-content) or want every note (use list-notes).\nPrefer this first to obtain ids for subsequent read/update/delete/move calls.", {
     query: z.string().min(1, "Search query is required"),
     searchContent: z.boolean().optional().describe("Search note content instead of titles"),
     account: z.string().optional().describe("Account to search in"),
@@ -178,7 +179,7 @@ server.tool("search-notes", {
     return successResponse(`Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):\n${noteList}${syncNote}`, { notes, count: notes.length });
 }, "Error searching notes"));
 // --- get-note-content ---
-server.tool("get-note-content", {
+server.tool("get-note-content", "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the note's content plus parsed hashtags.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     account: z
@@ -200,7 +201,8 @@ server.tool("get-note-content", {
         if (!content) {
             return errorResponse(`Failed to read content of note "${note.title}"`);
         }
-        return successResponse(content, { title: note.title, content });
+        const hashtags = parseHashtags(content);
+        return successResponse(content, { title: note.title, content, hashtags });
     }
     // Fall back to title-based lookup
     if (!title) {
@@ -218,10 +220,11 @@ server.tool("get-note-content", {
     if (!content) {
         return errorResponse(`Failed to read content of note "${title}"`);
     }
-    return successResponse(content, { title, content });
+    const hashtags = parseHashtags(content);
+    return successResponse(content, { title, content, hashtags });
 }, "Error retrieving note content"));
 // --- get-note-by-id ---
-server.tool("get-note-by-id", {
+server.tool("get-note-by-id", "Use when: you have a note id and need its metadata only.\nReturns: id, title, created, modified, shared, passwordProtected.\nDo not use when: you need the body text (get-note-content) or only have a title (get-note-details).", {
     id: z.string().min(1, "Note ID is required"),
 }, withErrorHandling(({ id }) => {
     const note = notesManager.getNoteById(id);
@@ -240,7 +243,7 @@ server.tool("get-note-by-id", {
     return successResponse(JSON.stringify(metadata, null, 2), metadata);
 }, "Error retrieving note"));
 // --- get-note-details ---
-server.tool("get-note-details", noteTitleSchema, withErrorHandling(({ title, account }) => {
+server.tool("get-note-details", "Use when: you have a note title (not an id) and need its metadata.\nReturns: id, title, created, modified, shared, passwordProtected, account.\nDo not use when: you have an id (get-note-by-id) or need the body text (get-note-content).\nUse the returned id for reliable follow-up operations.", noteTitleSchema, withErrorHandling(({ title, account }) => {
     const note = notesManager.getNoteDetails(title, account);
     if (!note) {
         return errorResponse(`Note "${title}" not found`);
@@ -258,7 +261,7 @@ server.tool("get-note-details", noteTitleSchema, withErrorHandling(({ title, acc
     return successResponse(JSON.stringify(metadata, null, 2), metadata);
 }, "Error retrieving note details"));
 // --- update-note ---
-server.tool("update-note", {
+server.tool("update-note", "Use when: changing the title and/or replacing the body of an existing note, by id (preferred) or title.\nReturns: confirmation; warns when the note is shared.\nDo not use when: creating a new note (create-note).\nSafety: newContent REPLACES the entire body — it does not append. Read the note first if you need to preserve existing text. Edits to shared notes are immediately visible to all collaborators.", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Current note title (use id instead when available)"),
     newTitle: z.string().optional().describe("New title for the note"),
@@ -323,7 +326,7 @@ server.tool("update-note", {
     return successResponse(`Note updated: "${finalTitle}"${sharedWarning}${checklistWarning}`);
 }, "Error updating note"));
 // --- delete-note ---
-server.tool("delete-note", {
+server.tool("delete-note", "Use when: permanently deleting a single note, by id (preferred) or title.\nReturns: confirmation; warns when the note was shared.\nDo not use when: deleting many notes (batch-delete-notes) or just relocating one (move-note).\nSafety: requires explicit user confirmation before deleting. Prefer search-notes/list-notes first to show the affected note id and title. Deleting a shared note removes collaborator access.", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     account: z
@@ -368,7 +371,7 @@ server.tool("delete-note", {
     return successResponse(`Note deleted: "${title}"${sharedWarning}`);
 }, "Error deleting note"));
 // --- move-note ---
-server.tool("move-note", {
+server.tool("move-note", "Use when: moving one note to a different folder, by id (preferred) or title.\nReturns: confirmation of the note and destination folder.\nDo not use when: moving many notes (batch-move-notes).\nNote: implemented as copy-then-delete; the destination folder must already exist (create-folder).", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     folder: z.string().min(1, "Destination folder is required"),
@@ -403,7 +406,7 @@ server.tool("move-note", {
     return successResponse(`Note moved: "${title}" -> "${folder}"`);
 }, "Error moving note"));
 // --- list-notes ---
-server.tool("list-notes", {
+server.tool("list-notes", "Use when: enumerating notes in an account or folder; supports modifiedSince and limit for large collections.\nReturns: note titles only (no content or ids).\nDo not use when: you need content (get-note-content) or ids for follow-up edits (use search-notes).\nNote: warns if iCloud sync is active and results may be partial.", {
     account: z.string().optional().describe("Account to list notes from"),
     folder: z.string().optional().describe("Filter to specific folder"),
     modifiedSince: z
@@ -441,7 +444,7 @@ server.tool("list-notes", {
 // Folder Tools
 // =============================================================================
 // --- list-folders ---
-server.tool("list-folders", {
+server.tool("list-folders", "Use when: listing all folders, with full nested paths, for an account.\nReturns: folder names/paths.\nDo not use when: listing notes (list-notes).\nNote: warns if iCloud sync is active.", {
     account: z.string().optional().describe("Account to list folders from"),
 }, withErrorHandling(({ account }) => {
     // Use sync-aware wrapper for this read operation
@@ -466,7 +469,7 @@ server.tool("list-folders", {
     });
 }, "Error listing folders"));
 // --- create-folder ---
-server.tool("create-folder", {
+server.tool("create-folder", "Use when: creating a folder, including nested paths like 'Work/Clients' (intermediate folders are created, existing ones skipped).\nReturns: confirmation.\nDo not use when: creating a note (create-note).", {
     name: z
         .string()
         .min(1, "Folder name is required")
@@ -480,7 +483,7 @@ server.tool("create-folder", {
     return successResponse(`Folder created: "${folder.name}"`);
 }, "Error creating folder"));
 // --- delete-folder ---
-server.tool("delete-folder", folderNameSchema, withErrorHandling(({ name, account }) => {
+server.tool("delete-folder", "Use when: deleting an existing folder by name or nested path.\nReturns: confirmation.\nDo not use when: deleting a note (delete-note).\nSafety: requires explicit user confirmation. Deletion fails if the folder still contains notes — list or move those notes first.", folderNameSchema, withErrorHandling(({ name, account }) => {
     const success = notesManager.deleteFolder(name, account);
     if (!success) {
         return errorResponse(`Failed to delete folder "${name}". Folder may not exist or may contain notes.`);
@@ -491,7 +494,7 @@ server.tool("delete-folder", folderNameSchema, withErrorHandling(({ name, accoun
 // Account Tools
 // =============================================================================
 // --- list-accounts ---
-server.tool("list-accounts", {}, withErrorHandling(() => {
+server.tool("list-accounts", "Use when: discovering which Notes accounts exist (iCloud, Gmail, Exchange, etc.) before targeting one.\nReturns: account names.\nDo not use when: you already know the account, or are working by note id (ids are account-independent).", {}, withErrorHandling(() => {
     const accounts = notesManager.listAccounts();
     if (accounts.length === 0) {
         return successResponse("No Notes accounts found", { accounts: [], count: 0 });
@@ -506,7 +509,7 @@ server.tool("list-accounts", {}, withErrorHandling(() => {
 // Collaboration Tools
 // =============================================================================
 // --- list-shared-notes ---
-server.tool("list-shared-notes", {}, withErrorHandling(() => {
+server.tool("list-shared-notes", "Use when: finding notes shared with collaborators.\nReturns: shared notes with title, account, and id.\nDo not use when: searching all notes (search-notes).\nNote: edits or deletes to these notes affect all collaborators.", {}, withErrorHandling(() => {
     const sharedNotes = notesManager.listSharedNotes();
     if (sharedNotes.length === 0) {
         return successResponse("No shared notes found. You have no notes shared with collaborators.", { notes: [], count: 0 });
@@ -524,7 +527,7 @@ server.tool("list-shared-notes", {}, withErrorHandling(() => {
 // Diagnostics Tools
 // =============================================================================
 // --- get-sync-status ---
-server.tool("get-sync-status", {}, withErrorHandling(() => {
+server.tool("get-sync-status", "Use when: checking whether iCloud sync is in progress before trusting read results.\nReturns: sync active/idle, pending upload count, and seconds since last change.\nDo not use when: you need note data — this is a read-only diagnostics tool.", {}, withErrorHandling(() => {
     const status = getSyncStatus();
     if (status.error) {
         return successResponse(`⚠️ Sync status unknown: ${status.error}`, { ...status });
@@ -550,7 +553,7 @@ server.tool("get-sync-status", {}, withErrorHandling(() => {
     return successResponse(lines.join("\n"), { ...status });
 }, "Error checking sync status"));
 // --- health-check ---
-server.tool("health-check", {}, withErrorHandling(() => {
+server.tool("health-check", "Use when: a quick check that Notes.app is reachable and (optionally) Full Disk Access is granted for checklist features.\nReturns: pass/fail per check.\nDo not use when: you need detailed, actionable setup diagnostics (use doctor).\nRead-only.", {}, withErrorHandling(() => {
     const result = notesManager.healthCheck();
     const statusIcon = result.healthy ? "✓" : "✗";
     const statusText = result.healthy ? "All checks passed" : "Issues detected";
@@ -568,14 +571,14 @@ server.tool("health-check", {}, withErrorHandling(() => {
     return successResponse(`${statusIcon} ${statusText}\n\n${checkLines}\n${fdaLine}`);
 }, "Error running health check"));
 // --- doctor ---
-server.tool("doctor", {}, withErrorHandling(() => {
+server.tool("doctor", "Use when: diagnosing setup problems (Notes.app automation permission, account state, Full Disk Access) with actionable guidance.\nReturns: a detailed report plus structured fields.\nDo not use when: you just need a quick pass/fail (health-check).\nRead-only.", {}, withErrorHandling(() => {
     // Richer than health-check: Notes.app permission, account state, and Full
     // Disk Access with actionable messages + structuredContent (#22).
     const report = runDoctor(notesManager);
     return successResponse(formatDoctorReport(report), { ...report });
 }, "Error running doctor"));
 // --- get-notes-stats ---
-server.tool("get-notes-stats", {}, withErrorHandling(() => {
+server.tool("get-notes-stats", "Use when: summarizing the library — total notes, per-account/folder counts, and recent activity.\nReturns: aggregate statistics; flags partial coverage when some scopes were unreadable.\nDo not use when: you need individual notes (list-notes/search-notes).\nRead-only.", {}, withErrorHandling(() => {
     const stats = notesManager.getNotesStats();
     // Format the output
     const lines = [];
@@ -599,10 +602,19 @@ server.tool("get-notes-stats", {}, withErrorHandling(() => {
     lines.push(`  Last 24 hours: ${stats.recentlyModified.last24h}`);
     lines.push(`  Last 7 days: ${stats.recentlyModified.last7d}`);
     lines.push(`  Last 30 days: ${stats.recentlyModified.last30d}`);
+    // Partial-coverage diagnostics (#19): if some scopes couldn't be read, say so
+    // explicitly so the numbers above aren't mistaken for a complete picture.
+    if (!stats.coverage.complete) {
+        lines.push(``);
+        lines.push(`⚠️  Partial results: read ${stats.coverage.covered}/${stats.coverage.scanned} scopes. Counts above exclude:`);
+        for (const w of stats.coverage.warnings) {
+            lines.push(`  - ${w.scope}: ${w.reason}`);
+        }
+    }
     return successResponse(lines.join("\n"), { ...stats });
 }, "Error getting notes statistics"));
 // --- list-attachments ---
-server.tool("list-attachments", {
+server.tool("list-attachments", "Use when: listing the attachments of one note, by id (preferred) or title.\nReturns: each attachment's name, content type, and id (use with save-attachment/fetch-attachment).\nDo not use when: you want the attachment bytes (fetch-attachment) or a file on disk (save-attachment).", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     account: z
@@ -642,7 +654,7 @@ server.tool("list-attachments", {
     return successResponse(`Found ${attachments.length} attachment(s) in "${title}":\n${attachmentList}`, { attachments, count: attachments.length });
 }, "Error listing attachments"));
 // --- batch-delete-notes ---
-server.tool("batch-delete-notes", {
+server.tool("batch-delete-notes", "Use when: permanently deleting multiple notes by id in one call.\nReturns: per-id success/failure counts.\nDo not use when: deleting a single note (delete-note).\nSafety: requires explicit user confirmation; this is destructive and not undoable. Prefer search-notes/list-notes first to confirm the exact ids being deleted.", {
     ids: z.array(z.string()).describe("Array of note IDs to delete"),
 }, withErrorHandling(({ ids }) => {
     if (ids.length === 0) {
@@ -661,7 +673,7 @@ server.tool("batch-delete-notes", {
     return succeeded > 0 ? successResponse(lines.join("\n")) : errorResponse(lines.join("\n"));
 }, "Error performing batch delete"));
 // --- batch-move-notes ---
-server.tool("batch-move-notes", {
+server.tool("batch-move-notes", "Use when: moving multiple notes by id into one destination folder.\nReturns: per-id success/failure counts.\nDo not use when: moving a single note (move-note).\nNote: the destination folder must already exist (create-folder).", {
     ids: z.array(z.string()).describe("Array of note IDs to move"),
     folder: z.string().describe("Destination folder name"),
     account: z
@@ -685,7 +697,7 @@ server.tool("batch-move-notes", {
     return succeeded > 0 ? successResponse(lines.join("\n")) : errorResponse(lines.join("\n"));
 }, "Error performing batch move"));
 // --- save-attachment ---
-server.tool("save-attachment", {
+server.tool("save-attachment", "Use when: writing one note attachment to a file on disk.\nReturns: the saved path.\nDo not use when: you want the bytes in-memory as base64 (fetch-attachment).\nSafety: writes a file; savePath must be absolute and under the home directory, a temp dir, or /Volumes. Get the ids from list-attachments first.", {
     noteId: z.string().min(1, "noteId is required").describe("CoreData note id (from search/list)"),
     attachmentId: z
         .string()
@@ -707,7 +719,7 @@ server.tool("save-attachment", {
     });
 }, "Error saving attachment"));
 // --- fetch-attachment ---
-server.tool("fetch-attachment", {
+server.tool("fetch-attachment", "Use when: retrieving one note attachment's bytes inline as base64 (no file written).\nReturns: name, content type, byte count, and base64 data.\nDo not use when: you want it saved to disk (save-attachment).\nNote: get the ids from list-attachments first.", {
     noteId: z.string().min(1, "noteId is required").describe("CoreData note id (from search/list)"),
     attachmentId: z
         .string()
@@ -721,7 +733,7 @@ server.tool("fetch-attachment", {
     return successResponse(`Fetched "${r.name ?? "attachment"}" (${r.contentType ?? "unknown type"}, ${r.bytes ?? 0} bytes) as base64.`, { name: r.name, contentType: r.contentType, bytes: r.bytes, base64: r.base64 });
 }, "Error fetching attachment"));
 // --- export-notes-json ---
-server.tool("export-notes-json", {}, withErrorHandling(() => {
+server.tool("export-notes-json", "Use when: exporting the entire notes library as structured JSON for backup or bulk processing.\nReturns: a summary plus the full JSON of all notes, folders, and accounts.\nDo not use when: you need a single note (get-note-content) — this reads everything and can be large.\nRead-only.", {}, withErrorHandling(() => {
     const exportData = notesManager.exportNotesAsJson();
     const { summary } = exportData;
     return {
@@ -739,7 +751,7 @@ server.tool("export-notes-json", {}, withErrorHandling(() => {
     };
 }, "Error exporting notes"));
 // --- get-note-markdown ---
-server.tool("get-note-markdown", {
+server.tool("get-note-markdown", "Use when: reading a note as Markdown, with checklist items annotated [x]/[ ] when Full Disk Access is granted.\nReturns: the note's Markdown.\nDo not use when: you need the raw HTML/plaintext body (get-note-content) or only metadata (get-note-details).\nNote: falls back to plain lists (no checkmarks) without Full Disk Access.", {
     id: z.string().optional().describe("Note ID (preferred - more reliable than title)"),
     title: z.string().optional().describe("Note title (use id instead when available)"),
     account: z
@@ -766,7 +778,7 @@ server.tool("get-note-markdown", {
     return successResponse(markdown, { markdown });
 }, "Error getting note as markdown"));
 // --- get-checklist-state ---
-server.tool("get-checklist-state", {
+server.tool("get-checklist-state", "Use when: reading the checked/unchecked state of a note's checklist items, by id.\nReturns: each item's text and done state plus checked/total counts.\nDo not use when: you only have a title (get the id via search-notes first) or want the full body text (get-note-content).\nNote: requires Full Disk Access; reads the NoteStore database directly.", {
     id: z.string().min(1, "Note ID is required. Use search-notes to find the note ID first."),
 }, withErrorHandling(({ id }) => {
     // Verify the note exists and is accessible