Skip to main content
Glama
Sign In
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ghl_calendar_list_free_slots

Read-onlyIdempotent

Retrieve available calendar time slots for a specified date range, optionally filtered by user and timezone, to find bookable openings.

Instructions

startDate/endDate are epoch milliseconds (a number, e.g. 1548898600000), NOT an ISO date string, despite the parameter name. Date range cannot exceed 31 days. Get Free Slots Get free slots for a calendar between a date range. Optionally a consumer can also request free slots in a particular timezone and also for a particular user. Endpoint: GET /calendars/{calendarId}/free-slots (Version header: v3; source: v3/calendars-v3.json) OAuth scopes: calendars.readonly

Input Schema

NameRequiredDescriptionDefault
userIdNoThe user for whom the free slots are returned
endDateYesEnd Date (**⚠️ Important:** Date range cannot be more than 31 days)
userIdsNoThe users for whom the free slots are returned
durationNoDuration in minutes to use for slot calculation. Must match one of the active durationOptions on the calendar. If omitted, the default duration is used.
timezoneNoThe timezone in which the free slots are returned
startDateYesStart Date (**⚠️ Important:** Date range cannot be more than 31 days)
calendarIdYesCalendar Id

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.1.0
    • addedInput schema / properties / duration
      Added value: +{
+  "description": "Duration in minutes to use for slot calculation. Must match one of the active durationOptions on the calendar. If omitted, the default duration is used.",
+  "example": 30,
+  "type": "number"
+}
    • addedInput schema / properties / userIds / example
      Added value: +[
+  "082goXVW3lIExEQPOnd3"
+]
  2. First observedv2.0.0

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/destructive=false, so the bar is lower, and the description adds real value: the 31-day range limit, the required calendars.readonly scope, and the endpoint/version. It stops short of describing the returned slot shape or how empty results behave.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The most error-prone detail (epoch ms, not ISO) is front-loaded in the first sentence, followed by purpose and constraints. The 'Get Free Slots' line partly restates the title/annotation, and the endpoint/scope footer is boilerplate, but overall it is tight and well-ordered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters, no nested objects, and no output schema, the description covers the calling contract well, including the format trap and the range cap. The main gap is the absence of any hint about what a free-slot response looks like, which no other field supplies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so baseline is 3, but the description adds meaning the schema does not: startDate/endDate are epoch milliseconds, not ISO strings 'despite the parameter name,' which prevents a concrete calling error. It also explains that timezone and user are optional filters. The 31-day note duplicates the schema warning rather than extending it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get free slots for a calendar between a date range,' and clarifies that timezone and user scoping are optional. This is enough for an agent to distinguish it from scheduling/booking siblings, though it does not explicitly contrast with tools like ghl_calendar_list_blocked_slots or ghl_calendar_event_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the purpose and the 31-day range constraint, but the description never states when to prefer this tool over blocked-slot listing or event listing, nor any prerequisites beyond the OAuth scope. Adequate but leaves selection among calendar siblings to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools