Show events in a calendar
When your agent has a schedule to show, post it as a calendar instead of a list in text. People switch between Day, Week, Month and Agenda, browse inside the range you fetched, open an event’s details and use Full screen. The tool is show_calendar, part of the Streams MCP server.
What the tool does
Section titled “What the tool does”show_calendar posts one card as a message from your agent, with a one-line text caption for readers that cannot render the card (older apps, search, push notifications). The caption holds the event count and the date range only, never a title or a location.
- A snapshot. The card never loads more events and never refreshes. Fetch the events first, then send every occurrence and the exact range you fetched. A recurring event arrives as separate occurrences with unique ids. Dates outside the range show as “not supplied”, never as free time.
- Display only. Nothing is answered and nothing comes back. The call returns at once and viewing the card never starts a turn.
- Everyone in the session sees the details. Only post a calendar where the person agreed to share it with that audience.
- Time zones. Timed events show in each viewer’s own time zone. All-day events keep their dates.
- All or nothing. If anything is invalid, nothing is posted and the error lists each problem with the path of the field to fix.
- Safe to retry.
requestIdis a UUID you generate once per card. Calling again with the samerequestIdand the same content returns the card already posted (created: false). The samerequestIdwith different content is refused with409 chat.calendar_request_conflict, and so is a retry after the card’s message was deleted. - Rate limit. At most 5 new cards per minute per stream and agent:
429 chat.calendar_rate_limitedwith the seconds to wait. Retries of an existing card do not count.
| Field | Type | Notes |
|---|---|---|
requestId |
UUID | Generate once per card; reuse it on a retry. |
streamId |
UUID | The stream to post in. Your agent must be a member. |
threadSessionId |
UUID, optional | Put the card in that thread, by its session id. |
replyToMessageId |
UUID, optional | Put the card in the thread of that message. With threadSessionId too, both must name the same thread. |
heading |
string, optional | Up to 200 characters. |
timeZone |
string | The IANA zone the range and all-day dates are in, for example Europe/Berlin. |
range |
object | { start, end }, offset-bearing ISO timestamps, half-open, at most 366 days. |
events |
array | Up to 200 events. Every event must overlap the range. The whole input is at most 64 KiB. |
initialView |
string, optional | day, week (the default), month or agenda. |
initialDate |
date, optional | YYYY-MM-DD, the date the card opens on. |
labels |
object, optional | Plain strings that replace the card’s English text. |
A timed event is { id, kind: "timed", title, start, end } with offset-bearing timestamps such as 2026-11-17T09:00:00+01:00. An all-day event is { id, kind: "all_day", title, startDate, endDateExclusive } with YYYY-MM-DD dates and an exclusive end. Every event may also carry:
| Field | Type | Notes |
|---|---|---|
description |
string, optional | Up to 2000 characters of plain text. |
location |
string, optional | Up to 200 characters. |
url |
string, optional | An https link, up to 2048 characters, without credentials. |
color |
string, optional | blue, purple, green, orange, red, pink, teal or gray. |
The event id is a unique lowercase slug (letters, digits, - or _, at most 40 characters). Titles are at most 200 characters.
{ "requestId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2e", "streamId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2f", "heading": "Team week", "timeZone": "Europe/Berlin", "range": { "start": "2026-11-16T00:00:00+01:00", "end": "2026-11-23T00:00:00+01:00" }, "initialView": "week", "events": [ { "id": "standup", "kind": "timed", "title": "Standup", "start": "2026-11-17T09:00:00+01:00", "end": "2026-11-17T09:15:00+01:00", "color": "blue" }, { "id": "offsite", "kind": "all_day", "title": "Offsite", "startDate": "2026-11-19", "endDateExclusive": "2026-11-21" } ]}Result
Section titled “Result”{ interactionId, messageId, created }. Nothing is returned to you about viewing: browsing, opening details and full screen never create a response or start another turn. You can read the stored card back with get_ui_interaction and its interactionId; the result is the input you posted.
Errors
Section titled “Errors”400 chat.calendar_invalid_request lists each problem with the path of the field, for example events.0.url or range.end. Common causes: a time without an offset, an unknown time zone, an event outside the range, a duplicate event id, a range longer than 366 days, more than 200 events, an http link, and input over 64 KiB. Fix the listed fields and call again.