--- name: calendly-availability-and-busy-time-check description: Answer "when can I meet" questions for a Calendly user by reading their availability schedules, offered times and busy blocks over a fixed window, then explaining exactly why each gap is or is not offered. Read-only capacity analysis against the calendar; no bookings or schedule changes. Use when the user asks when they are free, why a slot is not showing, how much meeting capacity they have next week, or whether a proposed time would work. --- # Check availability and busy time The question behind every request is narrower than "am I free": a slot is offered to an invitee only when the availability schedule allows it *and* nothing on the calendar blocks it. A free calendar with a narrow schedule shows no slots; an open schedule with a busy calendar shows fewer. This job separates those two causes and reports which one applies. It reads only; it changes nothing. ## 1. Fix the window, the person and the time zone Before any call, pin down: - **Whose calendar.** Confirm the user with `users-get_current_user`. If the user names someone else, use `users-get_user` only if that person's identifier is known; do not guess one. - **Window.** A concrete start and end date. "Next week" becomes actual dates. Keep it to the period asked about; a month-wide busy query is noisy. - **Time zone.** Take it from the availability schedule and the user's profile. Every time you report must carry its zone. Most "phantom" conflicts in this job are a zone mismatch between the user's view and the schedule's. - **Duration.** A 30-minute meeting and a 90-minute workshop face different gaps. Ask if it is not given. ## 2. Read the rules first: schedules Use `availability-list_user_availability_schedules`, then `availability-get_user_availability_schedule` for the schedule that applies. Note the weekly hours, any date overrides, and the zone. Write the rule down in plain words ("Mon–Thu 09:00–17:00 Europe/London, Fri 09:00–12:00"). Every later conclusion is measured against this. If the user has several schedules, check which one the relevant event types use (`event_types-list_event_type_availability_schedules`) before judging capacity. Reading the wrong schedule is the most common error here. ## 3. Read what is actually offered Use `event_types-list_event_type_available_times` for the event type and window, if the question is about a specific bookable type. This is the ground truth for "what would an invitee see". Treat it as authoritative for offered slots; do not recompute offered slots yourself from the schedule. If there is no event type to test against, say so and reason from the schedule and busy time instead, marking the result as an estimate. ## 4. Read what blocks the calendar Use `availability-list_user_busy_times` for the same window. Busy blocks come from connected calendars and existing bookings. Build a sorted list of blocks in the schedule's zone. Then, for each candidate gap, check: does it fit the duration after buffer and notice rules? A 30-minute opening between two blocks that touch the buffer is not a 30-minute opening. ## 5. Explain each gap For every window the user asks about, classify it: | Status | Meaning | |---|---| | **Offered** | In the schedule, free of busy time, shown by available times. | | **Outside hours** | Free on the calendar but the schedule does not allow it. Name the rule that excludes it. | | **Blocked** | Inside schedule hours but a busy block covers it. Name the block (title if readable, otherwise "busy"). | | **Too short** | Free but shorter than the event duration once buffers apply. | | **Not offered, cause unclear** | Evidence conflicts. Say what you checked and what remains unexplained. | Give the reason in one line each. "Tue 14:00 is missing: a busy block 13:30–15:00 covers it" is the standard. Do not list every free minute. ## 6. Answer the question asked - "When am I free?" → list the offered windows, grouped by day, with duration and zone. - "Why isn't 3pm showing?" → find the exact status from step 5 and explain it. - "Would Thursday 10:00 work?" → check that slot against both schedule and busy time, and say yes or no with the reason. - "How much capacity next week?" → total the offered minutes per day and overall, and state how many slots of the requested duration fit. ## Common patterns and traps - **Zone mismatch.** The invitee sees times in their zone; the user reads in theirs. Always state the zone with each time, and check it once if a slot looks wrong by exactly a few hours. - **Date overrides.** A one-off closed day or extra hours overrides the weekly pattern. A schedule that "should" allow a time may not on that date. Check overrides before concluding. - **Buffers and notice.** Buffers before and after meetings and minimum notice both remove slots that look free. A calendar that is empty tomorrow morning may still show nothing because of notice rules. - **Busy time is not a list of meetings.** Busy blocks may hide titles, cover tentative holds, or include other calendars. Do not assume the blank ones are personal or unimportant, and do not name titles you cannot see. - **Capacity versus offered slots.** Free hours on paper are not offered slots. Report both if the user asks "how much time do I have", and label which is which. - **Overlapping schedules.** Two schedules can cover the same hours with different rules. Attributing a gap to the wrong one wastes the user's time. - **Stale window.** Results describe the window you queried. If the user later asks about a longer or shifted range, query again rather than extending from memory. ## Output ``` Window: to , zone , duration min Whose calendar: Rule: Offered ( slots) - – ( min) ... Not offered -