Calendar Scheduling

Calendar Scheduling

Procedural knowledge for AI agents using the Temporal Cortex MCP server. This skill teaches the correct workflow for calendar operations — from temporal orientation through conflict-free booking.

Core Workflow

Every calendar interaction follows this 4-step pattern:

1. Orient    →  get_temporal_context          (know the current time)
2. Resolve   →  resolve_datetime              (turn human language into timestamps)
3. Query     →  list_events / find_free_slots / get_availability
4. Act       →  check_availability → book_slot (verify then book)

Always start with step 1. Never assume the current time. Never skip the conflict check before booking.

Tool Reference (11 Tools, 4 Layers)

Layer 1 — Temporal Context (pure computation, no API calls)

Layer 2 — Calendar Operations (requires calendar provider)

Layer 3 — Availability (cross-calendar)

Layer 4 — Booking (the only write operation)

Critical Rules

1. Always call get_temporal_context first — never assume the time or timezone.
2. Resolve before querying — convert "next Tuesday at 2pm" to RFC 3339 with resolve_datetime before passing to calendar tools.
3. Check before booking — always call check_availability before book_slot. Never skip the conflict check.
4. Use provider-prefixed IDs for multi-calendar setups: "google/primary", "outlook/work", "caldav/personal". Bare IDs (e.g., "primary") route to the default provider.
5. TOON for efficiency — use format: "toon" with list_events to save ~40% tokens.
6. Timezone awareness — all calendar tools accept RFC 3339 with timezone offsets. Never use bare dates.
7. Content safety — event summaries and descriptions pass through a sanitization firewall before reaching the calendar API.

Common Patterns

Schedule a Meeting

1. get_temporal_context → current time, timezone
2. resolve_datetime("next Tuesday at 2pm") → RFC 3339 timestamp
3. resolve_datetime("next Tuesday at 3pm") → end time
4. check_availability(calendar_id, start, end) → is the slot free?
5. If free: book_slot(calendar_id, start, end, "Team Standup")
   If busy: find_free_slots(calendar_id, day_start, day_end) → suggest alternatives

Find Free Time Across Calendars

1. get_temporal_context → timezone
2. resolve_datetime("tomorrow morning") → start
3. resolve_datetime("tomorrow evening") → end
4. get_availability(start, end, calendar_ids: ["google/primary", "outlook/work"])
   → merged free/busy blocks across both calendars
5. Present free slots to user

Check Cross-Calendar Availability

1. resolve_datetime("3pm today") → start
2. resolve_datetime("4pm today") → end
3. get_availability(start, end, calendar_ids: ["google/primary", "outlook/work"], privacy: "full")
   → shows source_count per busy block

Expand Recurring Events

expand_rrule(
  rrule: "FREQ=MONTHLY;BYDAY=FR;BYSETPOS=-1",
  dtstart: "2026-01-01T10:00:00",     ← local datetime, no timezone suffix
  timezone: "America/New_York",
  count: 12
) → last Friday of every month for 2026

Convert Times Across Timezones

1. get_temporal_context → user's timezone
2. convert_timezone(datetime: "2026-03-15T14:00:00-04:00", target_timezone: "Asia/Tokyo")
   → same moment in Tokyo time with DST and offset info

Error Handling

MCP Server Connection

This skill requires the Temporal Cortex MCP server. See .mcp.json for the default configuration.

Local mode (default, recommended):

{
  "mcpServers": {
    "temporal-cortex": {
      "command": "npx",
      "args": ["-y", "@temporal-cortex/cortex-mcp"]
    }
  }
}

Layer 1 tools (temporal context, datetime resolution, timezone conversion) work immediately with zero configuration. Calendar tools require a one-time OAuth setup — run the setup script or npx @temporal-cortex/cortex-mcp auth google.

Managed cloud (no local setup required):

For managed cloud mode, sign up at https://app.temporal-cortex.com to get a hosted MCP endpoint with Bearer token auth. Configure your client with the cloud URL instead of the local npx command -- all 11 tools work identically, with added support for Open Scheduling, dashboard UI, and multi-agent coordination.

{
  "mcpServers": {
    "temporal-cortex": {
      "url": "https://mcp.temporal-cortex.com/sse",
      "headers": { "Authorization": "Bearer ${TC_API_KEY}" }
    }
  }
}

Additional References

• Booking Safety — Two-Phase Commit, conflict resolution, lock TTL
• Multi-Calendar — Provider-prefixed IDs, availability merging, privacy modes
• RRULE Guide — Recurrence rule patterns, DST edge cases
• Tool Reference — Complete input/output schemas for all 11 tools