Skip to main content
Glama

Read calendar events

get_feed
Read-onlyIdempotent

Reads events and the current revision of a selected feed for a requested schedule lookup or revision. include_facets=true provides known facet values for label selection. Facets describe the entire published active feed, independent of read filters or pagination. Nonempty filters also return filtered_subscription with canonical filters, matching_event_count and unmatched_filter_values. Its nested URLs address that selection; top-level subscription URLs remain unfiltered. Event IDs, external keys, dates, removal state and pagination narrow only the read, never the subscription. Filtering changes no events and creates no cloned feed. A complete unfiltered read is a prerequisite for assessing cancellations from a revised schedule; omission from a filtered or paginated result is not evidence of deletion. Scope is limited to the connected account’s Smart Calendars AI feeds. No mailbox access, source-document retrieval, automatic source monitoring, scheduled PDF checks or document refresh is provided. Structured schedule content is supplied explicitly by the caller. Result links: subscription_open_url is the exact HTTPS handoff to the default calendar app via webcal; subscription_options_url provides Apple/default, Google, Outlook and copy-link choices; subscription_url is the copyable HTTPS calendar-file fallback; manage_url opens the feed dashboard. URL hosts, paths and tokens identify the returned resource and are not interchangeable. A filtered_subscription has its own links for that selection; top-level links remain unfiltered. Subscription access requires distribution_ready=true. Opening a link does not confirm a subscription; confirmation occurs in the user’s calendar app. Filter privacy: filters select events, not who can access them; anyone with the link can remove the filters and read the full published calendar.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "feed_id": "<feed_id>"
    },
    "name": "get_feed"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoInclusive upper date bound in YYYY-MM-DD format. Events whose date span overlaps the requested range can match; omission leaves the upper bound open.
fromNoInclusive lower date bound in YYYY-MM-DD format. Events whose date span overlaps the requested range can match; omission leaves the lower bound open.
limitNoMaximum events returned on this page, from 1 to 250; defaults to 100.
offsetNoNumber of matching results skipped before this page; defaults to 0. The response next_offset identifies the next page when present.
feed_idYesIdentity of the selected calendar returned in feed results.
filtersNoValues identify known labels from available_facets; include_facets=true provides that vocabulary. Values are trimmed and case-insensitive; format accepts attendance-mode aliases. Values within a field use OR; different fields use AND. Unknown values never broaden the selection. Filtering cannot infer missing metadata.
event_idsNoOptional selection of up to 250 existing event IDs. Omitted or empty means no event-ID restriction. This narrows only the read.
external_keysNoOptional selection of up to 250 source-stable external keys. Omitted or empty means no external-key restriction. Combined with other read filters.
removal_stateNoEvent cancellation state to return: active excludes canceled events, removed returns canceled events, and all includes both. Defaults to active.
include_facetsNoIncludes available_facets ({value,label,count} entries), facet_coverage ({tagged_events,fallback_events,missing_events}), facets_truncated and facet_scope=published_active_events. Coverage distinguishes explicit tags, fallbacks and missing values; title/location fallbacks do not infer classifications or audiences. Nonempty filters also include these results. Canonical fields: person, venue, topic, city, country, format, source.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • addedInput schema / properties / event_ids / description
      Added value: +"Optional selection of up to 250 existing event IDs. Omitted or empty means no event-ID restriction. This narrows only the read."
    • addedInput schema / properties / external_keys / description
      Added value: +"Optional selection of up to 250 source-stable external keys. Omitted or empty means no external-key restriction. Combined with other read filters."
    • addedInput schema / properties / feed_id / description
      Added value: +"Identity of the selected calendar returned in feed results."
    • addedInput schema / properties / filters / properties / format / description
      Added value: +"Existing attendance-mode labels from available_facets.format, such as online or in-person; accepted aliases are normalized by the server."
    • addedInput schema / properties / filters / properties / topic / description
      Added value: +"Existing topic or category labels from available_facets.topic."
    • addedInput schema / properties / from / description
      Added value: +"Inclusive lower date bound in YYYY-MM-DD format. Events whose date span overlaps the requested range can match; omission leaves the lower bound open."
    • addedInput schema / properties / limit / description
      Added value: +"Maximum events returned on this page, from 1 to 250; defaults to 100."
    • addedInput schema / properties / offset / description
      Added value: +"Number of matching results skipped before this page; defaults to 0. The response next_offset identifies the next page when present."
    • addedInput schema / properties / removal_state / description
      Added value: +"Event cancellation state to return: active excludes canceled events, removed returns canceled events, and all includes both. Defaults to active."
    • addedInput schema / properties / to / description
      Added value: +"Inclusive upper date bound in YYYY-MM-DD format. Events whose date span overlaps the requested range can match; omission leaves the upper bound open."
  2. Changed4 schema fields changed
    • changedInput schema / properties / filters / description
      Previous value: -"Request include_facets first; use returned available_facets values for the desired known labels. Values are trimmed and case-insensitive; format accepts attendance-mode aliases. Values within a field use OR; different fields use AND. Unknown values never broaden the selection. Filtering cannot infer missing metadata."New value: +"Values identify known labels from available_facets; include_facets=true provides that vocabulary. Values are trimmed and case-insensitive; format accepts attendance-mode aliases. Values within a field use OR; different fields use AND. Unknown values never broaden the selection. Filtering cannot infer missing metadata."
    • changedInput schema / properties / filters / properties / city / description
      Previous value: -"An existing event-city facet selected from available_facets.city. Not the user’s current city or residence; never request user geolocation."New value: +"An existing event-city facet selected from available_facets.city, not the user’s current city or residence. User geolocation is outside this field’s scope."
    • changedInput schema / properties / filters / properties / country / description
      Previous value: -"An existing event-country facet selected from available_facets.country. Not the user’s nationality or residence; never request user geolocation."New value: +"An existing event-country facet selected from available_facets.country, not the user’s nationality or residence. User geolocation is outside this field’s scope."
    • changedInput schema / properties / include_facets / description
      Previous value: -"Return available_facets ({value,label,count} entries), facet_coverage ({tagged_events,fallback_events,missing_events}), facets_truncated and facet_scope=published_active_events. Coverage distinguishes explicit tags, fallbacks and missing values; title/location fallbacks do not infer classifications or audiences. Also returned for nonempty filters. Canonical fields: person, venue, topic, city, country, format, source."New value: +"Includes available_facets ({value,label,count} entries), facet_coverage ({tagged_events,fallback_events,missing_events}), facets_truncated and facet_scope=published_active_events. Coverage distinguishes explicit tags, fallbacks and missing values; title/location fallbacks do not infer classifications or audiences. Nonempty filters also include these results. Canonical fields: person, venue, topic, city, country, format, source."
  3. Changed1 schema field changed
    • addedInput schema / properties / removal_state / type
      Added value: +"string"
  4. First observed

TDQS

A4/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial non-obvious behavior: filtering creates no cloned feed and changes no events, omission from filtered or paginated results is not evidence of deletion, subscriptions require distribution_ready=true, and link opening does not confirm a subscription. The filter-privacy caveat (anyone with the link can strip filters and read the full calendar) is exactly the kind of consequence an agent cannot get from the schema.

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

Conciseness3/5

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

The purpose is front-loaded, but the body is a dense run-on block of long multi-clause sentences that mixes URL semantics, privacy caveats, scope disclaimers and facet behavior with no grouping. Nearly every sentence carries a distinct non-obvious fact, so little is pure waste, but the reading cost is high and key routing information is buried.

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 10 parameters, a nested filters object, and no output schema, the description carries the return-value burden and does so: filtered_subscription contents, the four link types and their non-interchangeability, and facet_scope/facet_coverage are all covered. An agent has enough to call this correctly and interpret the response.

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 adds real meaning on top: it explains that event_ids, external_keys, dates, removal state and pagination narrow only the read and never the subscription, and that nonempty filters yield filtered_subscription with canonical filters and unmatched_filter_values. It stops short of explaining the interaction order or limits between combined filters beyond what the schema states.

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 opening sentence names a specific verb and resource: reads events plus the current revision of a selected feed, with clear framing of the lookup/revision use case. It does not, however, distinguish itself from the closest sibling get_feed_status, which an agent may plausibly confuse with 'current revision' reads.

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 rather than stated: 'include_facets=true provides known facet values for label selection' and 'A complete unfiltered read is a prerequisite for assessing cancellations' both hint at workflows. But there is no explicit when-to-use/when-not and no routing to list_feeds or get_feed_status as alternatives, leaving the agent to infer selection.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources