Find Next Available Slot

Find the next 3-5 available time slots in your calendar that match specified criteria. Perfect for scheduling new meetings.

Overview

The Find Next Available Slot tool searches your calendar to find free time slots that meet your requirements. It:

• Finds multiple available slots (up to 10)
• Supports working hours constraints (e.g., 9 AM - 5 PM only)
• Can exclude weekends
• Respects event transparency (transparent events don't block)
• Adds optional buffer time between events
• Returns slots with full date and time details

Prerequisites

• A connected Google Account with OAuth authentication
• Google Calendar API enabled in your Google Cloud project
• Setup Guide

Usage

Basic Usage

Find next 5 slots for a 1-hour meeting:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 60
  }
}

Searches from now through the next 7 days.

Working Hours Only

Find slots during business hours:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 60,
    "working_hours_only": true,
    "working_hours_start": "09:00",
    "working_hours_end": "17:00"
  }
}

Only returns slots between 9 AM and 5 PM.

Exclude Weekends

Find weekday slots only:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 30,
    "exclude_weekends": true
  }
}

Custom Search Range

Search a specific date range:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 90,
    "start_search_from": "2024-01-20T09:00:00",
    "end_search_by": "2024-01-27T17:00:00"
  }
}

Short Meeting

Find slots for a quick 15-minute meeting:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 15
  }
}

Buffer Time

Add 15-minute buffer after each event:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 60,
    "min_gap_minutes": 15
  }
}

Useful for travel time or breaks between meetings.

Fewer Results

Get just the next 3 available slots:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 60,
    "max_results": 3
  }
}

Full Configuration

Combine all options:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 60,
    "start_search_from": "2024-01-15T09:00:00",
    "end_search_by": "2024-01-22T17:00:00",
    "working_hours_only": true,
    "working_hours_start": "09:00",
    "working_hours_end": "17:00",
    "exclude_weekends": true,
    "min_gap_minutes": 15,
    "max_results": 5,
    "calendar_id": "primary"
  }
}

Input Parameters

Parameter	Type	Required	Default	Description
duration_minutes	integer	Yes	-	Required slot duration (15-480 minutes / 15 min - 8 hours)
start_search_from	string	No	now	Start searching from this time (ISO 8601)
end_search_by	string	No	+7 days	Stop searching after this time (ISO 8601)
calendar_id	string	No	"primary"	Calendar identifier
max_results	integer	No	5	Maximum slots to return (1-10)
working_hours_only	boolean	No	false	Only find slots during working hours
working_hours_start	string	No	"09:00"	Start of working hours (HH:MM format)
working_hours_end	string	No	"17:00"	End of working hours (HH:MM format)
exclude_weekends	boolean	No	false	Skip Saturday and Sunday
min_gap_minutes	integer	No	0	Minimum gap after each event (0-120 minutes)

Working Hours Format

Use 24-hour HH:MM format:

• "09:00" - 9 AM
• "17:00" - 5 PM
• "08:30" - 8:30 AM
• "18:00" - 6 PM

Response Format

Success with Slots Found

{
  "success": true,
  "available_slots": [
    {
      "slot_number": 1,
      "start_time": "2024-01-15T10:00:00-08:00",
      "end_time": "2024-01-15T11:00:00-08:00",
      "duration_minutes": 60,
      "date": "2024-01-15",
      "day_of_week": "Monday"
    },
    {
      "slot_number": 2,
      "start_time": "2024-01-15T14:30:00-08:00",
      "end_time": "2024-01-15T15:30:00-08:00",
      "duration_minutes": 60,
      "date": "2024-01-15",
      "day_of_week": "Monday"
    },
    {
      "slot_number": 3,
      "start_time": "2024-01-16T09:00:00-08:00",
      "end_time": "2024-01-16T10:00:00-08:00",
      "duration_minutes": 60,
      "date": "2024-01-16",
      "day_of_week": "Tuesday"
    },
    {
      "slot_number": 4,
      "start_time": "2024-01-16T13:00:00-08:00",
      "end_time": "2024-01-16T14:00:00-08:00",
      "duration_minutes": 60,
      "date": "2024-01-16",
      "day_of_week": "Tuesday"
    },
    {
      "slot_number": 5,
      "start_time": "2024-01-17T11:00:00-08:00",
      "end_time": "2024-01-17T12:00:00-08:00",
      "duration_minutes": 60,
      "date": "2024-01-17",
      "day_of_week": "Wednesday"
    }
  ],
  "total_slots_found": 5,
  "search_parameters": {
    "duration_minutes": 60,
    "start_search_from": "2024-01-15T09:00:00-08:00",
    "end_search_by": "2024-01-22T17:00:00-08:00",
    "working_hours_only": true,
    "working_hours": "09:00-17:00",
    "exclude_weekends": true,
    "calendar_id": "primary"
  },
  "calendar_timezone": "America/Los_Angeles"
}

No Slots Found

{
  "success": true,
  "available_slots": [],
  "total_slots_found": 0,
  "search_parameters": {
    "duration_minutes": 240,
    "start_search_from": "2024-01-15T09:00:00-08:00",
    "end_search_by": "2024-01-16T17:00:00-08:00",
    "working_hours_only": true,
    "working_hours": "09:00-17:00",
    "exclude_weekends": false,
    "calendar_id": "primary"
  },
  "calendar_timezone": "America/Los_Angeles"
}

Response Fields

Field	Type	Description
available_slots	array	List of available time slots (see below)
total_slots_found	integer	Number of slots found
search_parameters	object	Echo of search criteria used
calendar_timezone	string	Calendar's timezone

Slot Object

Each slot in available_slots contains:

• slot_number: Position in results (1, 2, 3, etc.)
• start_time: Slot start (ISO 8601 with timezone)
• end_time: Slot end (ISO 8601 with timezone)
• duration_minutes: Slot duration (matches input)
• date: Slot date (YYYY-MM-DD)
• day_of_week: Day name (Monday, Tuesday, etc.)

Use Cases

1. Schedule New Meeting

Find times for a 1-hour meeting this week:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 60,
    "working_hours_only": true,
    "max_results": 5
  }
}

Pick the first available slot and create event.

2. Propose Meeting Times

Find 3 options to propose to others:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 30,
    "max_results": 3,
    "working_hours_only": true
  }
}

Send the 3 slots to attendees to choose from.

3. Schedule Deep Work

Find 2-hour blocks for focused work:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 120,
    "working_hours_only": true,
    "working_hours_start": "09:00",
    "working_hours_end": "12:00",
    "exclude_weekends": true
  }
}

Morning-only search for when you're most productive.

4. Flexible Duration

Not sure how long you need? Try different durations:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 30,
    "max_results": 10
  }
}

If 30 minutes doesn't work, try 60 minutes.

5. Next Week Planning

Schedule for next week:

{
  "tool": "google_calendar_Find_Next_Available_Slot",
  "arguments": {
    "duration_minutes": 60,
    "start_search_from": "2024-01-22T09:00:00",
    "end_search_by": "2024-01-26T17:00:00",
    "working_hours_only": true
  }
}

Error Handling

Missing Duration

Error:

{
  "error": "duration_minutes is required"
}

Solution: Provide duration_minutes parameter.

Invalid Duration

Error:

{
  "error": "Duration must be between 15 minutes and 8 hours (480 minutes)"
}

Solution: Use duration between 15 and 480 minutes.

Invalid Search Range

Error:

{
  "error": "end_search_by must be after start_search_from"
}

Solution: Ensure end time is after start time.

Search Range Too Short

Error:

{
  "error": "Search range (120 minutes) is too short to fit the requested duration (180 minutes)"
}

Solution: Extend end_search_by or reduce duration_minutes.

Invalid Working Hours

Error:

{
  "error": "working_hours_start must be in HH:MM format (e.g., '09:00'). Got: '9am'"
}

Solution: Use 24-hour HH:MM format like "09:00", not "9am".

Error:

{
  "error": "working_hours_end must be after working_hours_start. Got: 09:00 to 17:00"
}

Solution: Ensure end time is later than start time.

No Slots Found

Not an error - just means you're fully booked. Try:

• Extending the search range (end_search_by)
• Reducing the duration
• Disabling working_hours_only
• Including weekends

Tips

1. Start Simple - Begin with just duration_minutes, then add constraints if needed.

2. Working Hours Default - Default is 9 AM - 5 PM. Adjust for your actual work schedule.

3. Buffer Time - Use min_gap_minutes for travel time or breaks. Recommended: 15 minutes.

4. Weekend Meetings - Set exclude_weekends: false if you schedule meetings on weekends.

5. Long Meetings - For meetings over 2 hours, you may find fewer available slots.

6. Search Range - Default 7 days is usually enough. Extend for longer-term planning.

7. Multiple Durations - If no slots found for 60 minutes, try 30 or 45 minutes.

8. Pick First Slot - The first slot is the soonest available. Perfect for "schedule ASAP" scenarios.

9. Alternative Days - Look at day_of_week to see distribution. If all slots are Monday, maybe wait for other days.

10. Combine with Create - After finding slots, use Create Event to actually schedule.

Algorithm Details

How It Works

1. Fetch Events: Gets all events in your search range
2. Build Busy Periods: Creates list of times you're unavailable (respects transparency)
3. Add Buffer: Adds min_gap_minutes after each event
4. Scan for Gaps: Checks every 15 minutes for free slots
5. Apply Constraints: Filters by working hours and weekends
6. Validate Duration: Ensures slot fits without crossing into busy time
7. Return Results: Returns first max_results slots found

Transparent Events

Events marked as "transparent" (free/available) don't block time. This tool respects that setting.

All-Day Events

All-day events block the entire day (midnight to 11:59 PM).

Limitations

1. Single Calendar - Searches one calendar at a time. For multiple calendars, call multiple times and merge results.

2. Authenticated User Only - Cannot check other people's availability or use Google's Freebusy API.

3. 15-Minute Increments - Searches in 15-minute steps. Won't find odd-minute slots like 10:07 AM.

4. Working Hours Can't Cross Midnight - Working hours must be within a single day (e.g., can't do "17:00" to "02:00").

5. No Natural Language - Must specify times in ISO 8601, not "tomorrow" or "next Monday".

6. OAuth Only - Requires Google Account with OAuth (App Passwords don't support Calendar API).

7. Max 10 Results - Can return at most 10 slots. If you need more, adjust search range and call again.

8. No Attendee Checking - Doesn't check if invited attendees are available. Only checks your calendar.

Related Tools

• Check Availability - Check a specific time slot
• Create Event - Schedule after finding slots
• Get Events - See existing events
• Get Today's Events - View today's schedule
• List Calendars - Get calendar IDs

Billing

Cost: 1 credit per execution

Fixed cost regardless of how many slots are found or search range size.