Tools Reference

The CourtsApp MCP Server exposes four tools. AI assistants call these tools to browse facilities, look up facility information, search for court availability, and generate booking links.

When to use which tool

Goal	Tool
Browse or pick from facilities in an area	list_facilities
Look up facility hours, amenities, policies, contact info	get_facility_details
Search for available court times	search_availability
Generate a booking link after choosing a slot	get_booking_link

---

list_facilities

List facilities by location. Use this when the user wants to browse or pick from facilities in an area. Returns facility IDs, names, and availability status — including both bookable and coming-soon facilities.

Parameters

Parameter	Type	Required	Description
city	string	No	City name. Use with state for a 50-mile radius search. E.g. "Austin", "Denver"
state	string	No	State name or abbreviation. Alone: returns all facilities in the state. With city: 50-mile radius. E.g. "Texas", "TX"
zipCode	string	No	Zip code for a 50-mile radius search. E.g. "78701"
sport	string	No	Filter by sport (e.g. "pickleball", "tennis", "padel"). Case-insensitive

At least one of city, state, or zipCode is required.

Response

Returns a list of facilities, each with:

• Facility name and ID
• comingSoon flag — true means the facility is joining CourtsApp but is not yet bookable

[!TIP] Use the facilityId values from list_facilities as input to get_facility_details for full information, or to search_availability when looking for available slots.

---

get_facility_details

Look up authoritative information about one or more facilities from the CourtsApp database. Use this tool any time the user asks about a facility — hours, location, amenities, phone number, policies, what sports they offer, or any other detail. Do not search the web; the CourtsApp database has up-to-date information for every facility in its network.

Accepts partial name matches, city, state, or zip. facilityId is optional — pass it only when you already have a facility ID from another CourtsApp tool; otherwise use name and location fields. At least one search field is required.

Parameters

Parameter	Type	Required	Description
name	string	No	Facility name or partial name (case-insensitive). E.g. "Lifetime", "Central Park Tennis", "YMCA"
facilityId	string (UUID)	No	Exact facility ID from list_facilities or search_availability. Omit when searching by name or location
city	string	No	City name (case-insensitive partial match). E.g. "Austin", "New York"
state	string	No	State name or abbreviation. E.g. "Texas", "TX"
zip	string	No	Zip/postal code (exact match)

At least one parameter is required.

Response

Returns up to 5 matching facilities. Each facility includes:

• Name and comingSoon status
• Description and timezone
• Full address and phone number
• Hours of operation
• Amenities list
• Booking and cancellation policies
• Available sports
• Court details (name, environment, surface, sports)
• Link to the facility page on CourtsApp

Advance booking windows: bookingPolicies.advanceBookingDays is the maximum advance booking window across all sports. When different sports have different windows, advanceBookingDaysBySport lists each sport and its specific window (e.g. Pickleball 7 days, Tennis 14 days).

Coming-soon facilities: Facilities with comingSoon: true are joining CourtsApp but are not yet bookable. Share available details with the user and suggest they check back soon — do not attempt to search availability or generate booking links for these facilities.

---

search_availability

Search for available court times at nearby facilities. Returns facilities with available slots, pricing, and a sportId needed for booking.

Parameters

Parameter	Type	Required	Description
sport	string	Yes	Sport type. One of: tennis, pickleball, padel, table-tennis, badminton, racquetball, squash
duration	number	Yes	Session length in minutes. One of: 30, 60, 90, 120
date	string	Yes	Date in YYYY-MM-DD format
time	string	Yes	Time in HH:MM 24-hour format
location	string	Yes	Location query — coordinates, city+state, or zip code
facilityName	string	No	Optional facility name filter (fuzzy matching)

Location Formats

The location parameter accepts three formats:

Format	Example
Zip code	85022
City, State	manhattan, ny
Coordinates	40.6892,-74.0445

Response

Returns a list of facilities with available court slots. Each facility includes:

• Facility name and ID
• Available time slots with pricing
• sportId — a UUID required when calling get_booking_link
• Court surface types

[!TIP] The sportId and facilityId values from the search response are required to generate a booking link. Always use these values from the search results — do not construct them manually.

---

get_booking_link

Generate a booking link for a specific court slot. Returns a URL to the CourtsApp booking page with pre-filled details and live pricing.

Parameters

Parameter	Type	Required	Description
facilityId	string	Yes	Facility UUID from search_availability results
date	string	Yes	Date in YYYY-MM-DD format
time	string	Yes	Time in HH:MM 24-hour format
sportId	string	Yes	Sport UUID from search_availability results
duration	number	Yes	Session length in minutes
surface	string	No	Optional court surface filter

Response

Returns a booking URL that the user can open to complete their reservation. The link includes:

• Pre-selected facility, court, date, and time
• Live pricing
• Direct path to checkout

[!CAUTION] Booking links are time-sensitive. Generate them close to when the user intends to book, as court availability can change.