--- name: busycal-essentials description: "How to use the BusyCal connector well and safely on a Mac: confirm the calendar and account scope first, pick between event, task and availability tools, search without flooding the conversation, handle the app not running, and get explicit approval before any change. Use when the user asks anything about their BusyCal calendars, events, tasks or free time, or when setting up or troubleshooting the BusyCal connection." --- # Use BusyCal well and safely BusyCal runs on the same Mac as the assistant and holds the user's real calendars, which may be shared with other people and synced to other devices. Every read is cheap; every write is visible to others. Orient first, read narrowly, and treat every change as something the user must approve. ## 1. Confirm the scope before anything else Call `list_accounts` and `list_calendars` before a search or write. Note which accounts exist and which calendars accept events and which accept tasks. Then: - If the user names a calendar or account, match it against this list. If two calendars share a name, ask which one is meant rather than guessing. - If the request does not name a calendar, search across all calendars for reads, but never create or move an item without the user saying which calendar it belongs to. - Check whether an item is an event or a task before calling a tool; the tools are split by type and the wrong one will not find it. ## 2. Choose the right tool family - **Overview of what is on a day or range:** `query_items` for mixed results, or `query_events` and `query_tasks` when the user wants one type only. - **Free or busy time:** `query_availability` to see the shape of a range, `find_next_available` to get one open slot of a given length inside working hours. Use availability for "when am I free"; do not infer it from event lists, which miss travel time and working-hour limits. - **What the user is looking at right now:** `selected_items` reads the current BusyCal selection. Prefer it over searching when the user says "this", "these" or "the ones I picked". - **A single known item:** get its identity from a search first, then act on that identity. Do not guess IDs. - **Quick capture from plain wording:** `create_natural_language_item` is convenient but less precise. For anything with a specific time, calendar or duration, use `create_event` or `create_task` so the fields are explicit and you can read back what was written. - **Showing something to the user:** `open_item` reveals an item in the BusyCal window. It changes what is on screen, not the data, but still reveal only what the user asked to see. ## 3. Search without flooding the context - Always bound searches by date range and calendar. An open-ended query over years of history returns noise and costs context. - Start narrow (the requested day or week), and widen only if the first pass is empty. - Summarise results instead of pasting raw lists: give counts, the handful of items that matter and their times, and offer to show more. - Keep notes, URLs and tags out of summaries unless the user asks; they can contain private or sensitive text. ## 4. Handle the app not running and blocked calls The server launches BusyCal if it is closed, so a first call can be slow. If a call times out or returns a connection-style error, retry once after a short pause, then tell the user plainly that BusyCal did not respond and suggest checking that the app opens and that the MCP server is connected in the assistant's settings. If a call is refused for permissions, report the refusal and what the user must change on the Mac; do not try workarounds. If results look incomplete, check whether the calendar is hidden or unchecked in BusyCal before concluding the data is missing. ## 5. Read before you write, and say what you will change For any change, first read the current item so you can state its present values (title, time, calendar, duration, reminders, travel time, starred status). Then describe the exact change in plain words: "Move 'Design review' from Tue 14:00 to Wed 10:00 on Work", and wait for the user's explicit yes before calling the write tool. ## 6. The write tools and the approval rule These tools change data: `create_natural_language_item`, `create_event`, `create_task`, `duplicate_item`, `move_event`, `defer_task`, `complete_task`, `uncomplete_task`, `update_event`, `update_task`, `delete_event`, `delete_task`. Each requires the user's explicit yes in this conversation, shown per change, wait for the user's explicit yes. A yes to one change does not cover the next. Deletions and bulk changes need a fresh, specific confirmation that lists the items. Switching the active account or calendar used for new items also counts as a change and needs the same yes. ## Common patterns and traps - **Wrong type:** asking for "my to-dos" with an event tool returns nothing that looks like a task. Check the type first. - **Time zones:** items can carry their own IANA timezone. A 9:00 that displays differently for the user may be a timezone mismatch, not a missing item. State the zone when reporting times for cross-timezone items. - **Duplicate-looking items:** the same meeting on two calendars, or a copy made with `duplicate_item`, can look like a double booking. Check the calendar before reporting a conflict. - **Availability versus events:** a clear event list does not mean free time, because travel time, working hours and other calendars matter. Use the availability tools for that answer. - **Silent edits from natural language:** capture phrases such as "tomorrow at 3" depend on the current date and the user's locale. Confirm the resolved date and time before writing. - **Shared or synced calendars:** a change to a calendar others can see is visible to them. Mention this when the calendar looks shared. - **Undated tasks and deferred work:** an undated task is not overdue; do not report it as late. ## Output ``` Scope: Found: Free time: Pending change: Could not check: