Skip to main content
Glama

Create a calendar event

event_create

Create one-off or repeating events in a shared flat calendar and notify other flat members. Requires a title and start time; supports all-day events, locations, and recurrence rules.

Instructions

Add a new event, one-off or repeating, to the flat calendar. Use it for something new; use event_update to change an existing event, and absence_create instead when a member is away. Not idempotent: calling it twice creates two events. The other flat members are notified about the new event, not the caller. An endsAt before startsAt fails with ends_before_start. Returns the created event with its id and a warning that is null unless the push delivery could not be confirmed.

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>",
      "startsAt": "<startsAt>"
    },
    "name": "event_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleYesShort name of the event, shown in the calendar and the notification.
allDayNotrue for an event that lasts the whole day (no clock time), false for one at a specific time. Defaults to false.
endsAtNoOptional end as ISO 8601 datetime with offset, not before startsAt. Omit or send null for an event without an end time.
wgCodeNoShare code of the flat (code from wg_list). Leave it out when the account belongs to one flat.
locationNoOptional place, for example "Kitchen" or an address.
startsAtYesStart as ISO 8601 datetime with offset, for example 2026-12-05T19:00:00+01:00; the year must be 1900..2200. For an all-day event only the date counts: send the date at T00:00:00Z.
recurrenceNoRepeat rule, an RFC 5545 subset with parts separated by ";", for example "FREQ=WEEKLY;BYDAY=MO,TH;COUNT=10". FREQ=DAILY|WEEKLY|MONTHLY|YEARLY is required; optional INTERVAL 1..365, BYDAY (MO..SU), COUNT 1..366, UNTIL. Anything else fails with recurrence_invalid.
descriptionNoOptional longer details for the event.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.1.1
    • addedInput schema / properties / allDay / description
      Added value: +"true for an event that lasts the whole day (no clock time), false for one at a specific time. Defaults to false."
    • addedInput schema / properties / description / description
      Added value: +"Optional longer details for the event."
    • addedInput schema / properties / endsAt / description
      Added value: +"Optional end as ISO 8601 datetime with offset, not before startsAt. Omit or send null for an event without an end time."
    • addedInput schema / properties / location / description
      Added value: +"Optional place, for example \"Kitchen\" or an address."
    • changedInput schema / properties / recurrence / description
      Previous value: -"RFC 5545 subset, separated by \";\": FREQ=DAILY|WEEKLY|MONTHLY|YEARLY (required), INTERVAL 1..365, BYDAY (MO..SU), COUNT 1..366, UNTIL. Otherwise recurrence_invalid."New value: +"Repeat rule, an RFC 5545 subset with parts separated by \";\", for example \"FREQ=WEEKLY;BYDAY=MO,TH;COUNT=10\". FREQ=DAILY|WEEKLY|MONTHLY|YEARLY is required; optional INTERVAL 1..365, BYDAY (MO..SU), COUNT 1..366, UNTIL. Anything else fails with recurrence_invalid."
    • addedInput schema / properties / startsAt / description
      Added value: +"Start as ISO 8601 datetime with offset, for example 2026-12-05T19:00:00+01:00; the year must be 1900..2200. For an all-day event only the date counts: send the date at T00:00:00Z."
    • addedInput schema / properties / title / description
      Added value: +"Short name of the event, shown in the calendar and the notification."
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already flag readOnlyHint=false, idempotentHint=false and destructiveHint=false, but the description goes well beyond them: not idempotent (twice = two events), the caller is not notified while other flat members are, endsAt before startsAt yields ends_before_start, and the return is the event with its id plus a nullable push-delivery warning. That is a genuinely rich behavioral profile.

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

Conciseness5/5

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

Four sentences and roughly one hundred words, front-loaded with action and routing, then failure mode, then side effects, then return shape. Each sentence carries distinct, non-redundant information.

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 eight parameters, no output schema, and no enum hints, the description still covers purpose, alternative routing, invalid-input failure mode, notification side effects and the return payload. Nothing an agent needs before invoking it correctly is missing.

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 percent, so the schema already carries every parameter's meaning, including the recurrence RFC 5545 subset and the all-day handling. The description adds only the endsAt/startsAt ordering rule and the hint that events may be repeating, so baseline 3 applies rather than credit for extra semantics.

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?

The description uses a specific verb and resource ("Add a new event ... to the flat calendar") and ties it to a scope (one-off or repeating). It explicitly contrasts itself with event_update and absence_create, so an agent can choose this tool without opening the schemas.

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?

When-to-use is explicit ("something new"), as are the when-not conditions and the sibling alternatives: event_update for changing existing events, absence_create for member absences. Nothing is left for the agent to guess.

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