Telegram Calendar MCP

Create a new event or task

create_event

Create an event or task for the authenticated user. title is required (1–200 characters). start and end are ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone. timezone is an IANA name (default UTC) and stays the event zone: it is not replaced by the user timezone. rrule is an iCalendar RRULE string. status is active, done, undone, or cancelled. type is event or task. location is a short place name. waitSync defaults to true and waits for the external calendar so the response can include links; false responds immediately and links may be absent.

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": {
      "title": "<title>"
    },
    "name": "create_event"
  }
}

Input Schema

Name	Required	Description
`end`	No	ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone
`desc`	No	Description (up to 1000 characters)
`type`	No	event is a timed item; task is a to-do without a duration
`rrule`	No	iCalendar RRULE string for a repeating event
`start`	No	ISO 8601 date-time with offset, or YYYY-MM-DD for an all-day event in the event timezone
`title`	Yes	Event or task title (1–200 characters)
`allDay`	No	True when start and end are calendar dates without a time
`status`	No	Event status: active, done, undone, or cancelled
`location`	No	Short place name
`timezone`	No	IANA timezone of the event; stored as-is, not replaced by the user timezone
`waitSync`	No	Wait for the external calendar so the response can include links; default true
`calendarId`	No	Calendar that owns the event; omit for the default calendar

Output Schema

Name	Required	Description
`id`	Yes	Event id
`end`	No	End in the user timezone (ISO 8601)
`desc`	No	Description
`type`	No	event is a timed item; task is a to-do without a duration
`links`	No	External calendar links when sync has finished
`rrule`	No	iCalendar RRULE string when the event repeats
`start`	No	Start in the user timezone (ISO 8601)
`title`	Yes	Event or task title
`allDay`	No	True when the event is a calendar date without a time
`status`	No	Event status: active, done, undone, or cancelled
`location`	No	Short place name
`timezone`	No	IANA timezone stored on the event
`createdAt`	No	When the event was created (ISO 8601)
`updatedAt`	No	When the event was last changed (ISO 8601)
`calendarId`	No	Calendar that owns the event

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 9, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare non-read-only, non-destructive, non-idempotent, so credit goes for what is added: waitSync blocking semantics and the resulting presence/absence of links, and the guarantee that timezone is stored as-is and not overridden by the user timezone. Not covered: whether creating an event writes to an external calendar, duplicate behavior implied by idempotentHint=false, or failure modes on sync.

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?

Everything is front-loaded with the required field first, followed by formats, enums, and defaults; no filler sentences. It is a dense run-on of parameter clauses, which costs a point on readability but not on signal density.

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?

For a 12-parameter mutation tool with an output schema and full annotation coverage, the description supplies the essentials: required field, date formats, enum domains, defaults, and the one non-obvious side effect (waitSync). Gaps are calendarId and allDay, which only the schema carries, and the absence of routing guidance toward the update/status siblings.

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

Parameters3/5

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

Schema coverage is 100%, so baseline is 3. The description does add real meaning for waitSync ('waits for the external calendar so the response can include links; false responds immediately and links may be absent') and reinforces the timezone persistence rule, but it silently omits two present parameters, calendarId and allDay, and repeats the schema's format rules for start/end.

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?

States a specific verb and resource ('Create an event or task') and immediately ties it to the authenticated user, which distinguishes it from update_event, set_event_status, and delete_event in the sibling set. The title is required and the domain is unambiguous.

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?

The description establishes that this is the creation path but never says when to use it versus update_event or set_event_status, nor any precondition (existing calendar, duplicate handling). Usage is implied by the verb rather than stated, which is the minimum viable level.

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

All Telegram Calendar MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?