Skip to main content
Glama

YouSpot

by com.youspot
OverviewDiscussionsAdmin

Get calendar events

get_calendar_events
Read-only

List events from the user's connected calendars, Google and Outlook together, ordered by start time: summary, start/end, location, organizer, attendees and their RSVP status, a meeting link when there is one, and which provider and account each event came from (Outlook events carry a web_link that opens them in Outlook). With no time range it returns upcoming events from now. time_min and time_max are RFC3339 timestamps ('2026-08-19T00:00:00Z'), so 'what's on my calendar tomorrow' is time_min/time_max spanning that day; past ranges work too. query free-text matches event titles, descriptions, and attendees. For 'how many meetings' questions over long ranges (a quarter, a year), set count_only=true; it sweeps the whole range and returns the total plus a per-month breakdown instead of the events themselves, so a 12-month count is one call. By default this reads each account's main calendar. When a Google account can list its calendars, the result carries available_calendars (name, id, access role), shared calendars included: pass a calendar's name or id as calendar_id ('Family') to read it, or all_calendars=true to read every calendar at once. For an Outlook calendar, get its id from list_outlook_calendars. If the result says no calendar is connected (or the account lacks calendar access), show the user the message and link them to https://youspot.com/user/integrations/gmail.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryNoFree-text search over events (titles, descriptions, attendees). Omit to list everything in the range.
accountNoEmail address of one connected Google account or Outlook mailbox. Omit to read all connected calendars.
time_maxNoLatest event start, RFC3339.
time_minNoEarliest event end, RFC3339 ('2026-08-19T00:00:00Z'). Defaults to now when time_max is also omitted.
count_onlyNoReturn only counts (total and per calendar month) instead of the events. Sweeps far more of the range (up to 12,500 events) than an event listing can. Use for totals and "how many" questions.
calendar_idNoWhich calendar to read: a name or id from available_calendars, or an id from list_google_calendars or list_outlook_calendars. Omit for each account's main calendar.
max_resultsNoMax events to return (default 10, max 250).
all_calendarsNoRead every Google calendar the user can see events on, shared ones included, instead of just the main one. Each event then names its calendar.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / all_calendars
      Added value: +{
+  "description": "Read every Google calendar the user can see events on, shared ones included, instead of just the main one. Each event then names its calendar.",
+  "type": "boolean"
+}
    • changedInput schema / properties / calendar_id / description
      Previous value: -"Which calendar to read: an id from list_google_calendars or list_outlook_calendars. Omit for each account's main calendar."New value: +"Which calendar to read: a name or id from available_calendars, or an id from list_google_calendars or list_outlook_calendars. Omit for each account's main calendar."
  2. Changed2 schema fields changed
    • changedInput schema / properties / account / description
      Previous value: -"Email address of one connected Google account. Omit to read all connected accounts."New value: +"Email address of one connected Google account or Outlook mailbox. Omit to read all connected calendars."
    • changedInput schema / properties / calendar_id / description
      Previous value: -"Which calendar to read: an id from list_google_calendars. Omit for the primary calendar."New value: +"Which calendar to read: an id from list_google_calendars or list_outlook_calendars. Omit for each account's main calendar."
  3. Changed2 schema fields changed
    • changedInput schema / properties / calendar_id / description
      Previous value: -"Which calendar to read — an id from list_google_calendars. Omit for the primary calendar."New value: +"Which calendar to read: an id from list_google_calendars. Omit for the primary calendar."
    • changedInput schema / properties / count_only / description
      Previous value: -"Return only counts — total and per calendar month — instead of the events. Sweeps far more of the range (up to 12,500 events) than an event listing can. Use for totals and \"how many\" questions."New value: +"Return only counts (total and per calendar month) instead of the events. Sweeps far more of the range (up to 12,500 events) than an event listing can. Use for totals and \"how many\" questions."
  4. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does so well: default scope is each account's main calendar, count_only sweeps up to 12,500 events versus a normal listing, max_results defaults to 10 and caps at 250, Outlook events carry a web_link, and the no-calendar-connected error state is described with remediation.

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?

Front-loaded with the return shape and scope, then walks through the parameters in a logical order. It is long (~190 words) and the count_only and calendar-selection paragraphs could be tightened, but nearly every sentence carries actionable information rather than filler.

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

Completeness5/5

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

With 8 optional parameters and no output schema, the description compensates by describing the returned fields, defaults, caps, and the special count_only return shape. An agent has everything needed to call this correctly, including the failure path.

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 the baseline is 3, but the description genuinely adds semantics beyond the schema: RFC3339 example format, the concrete 'what's on my calendar tomorrow' mapping to time_min/time_max, that past ranges work, that query matches titles/descriptions/attendees, and a 'Family' example for calendar_id.

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

Purpose5/5

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

Opens with a specific verb+resource (list events from the user's connected calendars) and immediately scopes it (Google and Outlook together, ordered by start time). It enumerates the returned fields, which makes it trivially distinguishable from siblings like create_calendar_event, list_google_calendars, and list_outlook_calendars.

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

Usage Guidelines5/5

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

Explicit routing guidance throughout: use count_only=true for 'how many meetings' over long ranges, pass calendar_id or all_calendars to read non-default calendars, get Outlook calendar ids from list_outlook_calendars, and with no time range it returns upcoming events. It even names the fallback when no calendar is connected (link to the integrations page).

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

All YouSpot toolsInspect
Try in Browser
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources