Find a free meeting slot in BusyCal with AI

The goal is one specific time the user can accept, not an overview of their week. Start from the constraints the user gave (length, date window, time of day, who or what it is for), find two or three candidates, check each one, and offer them. Booking is a separate step the user approves.

1. Pin down the request before searching

Confirm these with the user if they are missing. Do not guess silently:

• Length in minutes, and whether it needs travel time on either side.
• Window: the earliest and latest acceptable date and time, and the time zone. If the user is in another zone, use a named IANA timezone and say which one.
• Working hours: check list_accounts and list_calendars first to confirm which account and calendar the user means. Free time on the wrong calendar gives false availability. Ask before switching any active account; that change needs the user's explicit yes.
• Which calendars count as busy. A personal calendar that is not shared with work may need to be included or excluded on purpose.

Reading through selected_items is only useful if the user already selected the event they are rescheduling around. Otherwise skip it.

2. Get the free time, then narrow it

Use query_availability over the window, scoped to the calendars that matter, restricted to working hours. This returns busy and free blocks cheaply. Only use query_events on a specific day if you need to know what blocks a candidate (for example to tell a tentative hold from a hard commitment).

If query_availability leaves the answer too wide, use find_next_available with the required length to get the first open slot after a given time. Run it again from the end of each candidate to get a second or third option, rather than requesting a long list.

Keep the search tight: one or two date ranges, not the whole quarter. Large result sets crowd out the rest of the conversation.

3. Check each candidate before offering it

A slot that looks free can still be bad. For each candidate:

• Buffers. Is there room before and after for the travel time the user needs? A slot directly after another meeting elsewhere is not usable.
• Day shape. Ten minutes of gap between two long meetings is technically free and practically useless. Prefer candidates that leave the user a sensible break, or flag when the day is already full.
• Type of block. A tentative or all-day "out of office" entry is a different kind of busy than a firm meeting. Name what you found.
• Time zone sanity. Read the slot back in the user's zone, and in the other party's zone if it is a cross-zone meeting. Confirm the zones are named IANA identifiers and not guessed offsets.
• Recurrence. A slot that is free today may be the weekly 1:1 next week. Check the same time on the following days if the user will want it to recur.

Offer two or three options with a short reason for each, ordered by how well they fit. Do not offer more than that.

Common patterns and traps

• Empty result over a long window. Usually means the window is too wide to show free blocks or the working hours are too narrow for the requested length. Shorten the length or widen the hours, and say which one you changed.
• Everything looks free, nothing fits. Often a single calendar is hiding a busy block because it is not in the query. Confirm the calendar list before concluding the user is unavailable.
• Free in the wrong zone. A slot offered in the user's zone may be 3 a.m. for the other person. Always state the zone with the time.
• Travel time forgotten. Two meetings in different places back to back are a conflict even if the clock says they are not.
• Stale answer. If the user has just accepted or moved something, the earlier availability result may be out of date. Re-check before offering the slot.
• Booking instead of offering. The user asked when they are free. Do not create an event unless they say so.

Output

Request: <length> min, <window>, <time zone>, <calendars considered>
Options:
1. <weekday date, start–end time zone> — <why it fits; any buffer or day-shape note>
2. <...>
3. <...>
Excluded: <notable blocks that ruled out the obvious slots, or "none">
Not checked: <calendars left out, or recurrence not verified>
Next step: Reply with the option you want and I will book it, after your explicit yes.

Rules

• Do not create, move or send any event while looking for a slot. Booking a candidate needs the user's explicit yes in this conversation, given for that specific time.
• Do not switch the active account or calendar set without the user's explicit yes.
• Never state that someone else is free or busy. You only see the user's own BusyCal data.
• Never present a slot as confirmed. It is an option until the user says yes and the event is created.
• Do not treat a tentative block as a hard conflict without saying so; let the user decide whether it can be moved.

Done when

• The request is restated with length, window, zone and calendars, and any missing parts were asked for.
• Two or three candidates are offered, each checked for buffers, zone and recurrence.
• Nothing has been booked, and the output states "Not checked" honestly.