---
name: calendar-lookup
description: How to query calendar events and meetings correctly — tool priority and API pitfalls.
metadata:
  activation:
    keywords: [calendar, events, meeting today, next meeting, outlook calendar, tomorrow schedule, upcoming meetings, 今日安排, 今日日程, 明日日程, 查日历, 查日程, 会议查询]
    patterns:
      - "(?i)\\b(what|any|show|list|check|get|retrieve|fetch|find|look\\s*up)\\s+(my\\s+)?(meetings?|events?|calendar|schedule|agenda)\\b"
      - "(?i)\\b(meeting|event|schedule|agenda|calendar)s?\\s+(today|tomorrow|this week|next week|on\\s+\\w+day)\\b"
      - "(?i)(日程|会议|开会|几点开会|今天有什么会|明天.*日程|后天.*日程|明日安排)"
  requires:
    tools: [MCP_calendar]
---


Use this skill to query calendar events and meetings.

## Tool priority

1. `MCP_m365copilot_CopilotChat` — primary read path for natural-language calendar questions.
2. `MCP_calendar_ListEvents` — structured fallback/readback API.
3. `MCP_mail_SearchMessages` — invite/reminder/context fallback.
4. `MCP_calendar_ListCalendarView` — **DO NOT USE** (returns false empties).

## Core rules

1. Get user timezone first: `MCP_calendar_GetUserDateAndTimeZoneSettings(userIdentifier="me")`.
2. Query a slightly wider time window than the exact boundary when correctness matters.
3. Convert returned times to user timezone before replying.
4. Prefer parallel queries — e.g. call WorkIQ and ListEvents concurrently.

## Read workflows

### Today / tomorrow / a date

Preferred:
1. Ask `MCP_m365copilot_CopilotChat` for meetings on that date.
2. Return a brief summary.

Fallback:
1. Get mailbox timezone via `MCP_calendar_GetUserDateAndTimeZoneSettings`.
2. Query `MCP_calendar_ListEvents` with:
   - `startDateTime = "YYYY-MM-DDT00:00:00"`
   - `endDateTime = "YYYY-MM-DDT23:59:59"`
   - `timeZone = mailbox timezone`
   - `select = "id,subject,start,end,location,organizer,isAllDay,showAs,type,recurrence"`
3. Interpret returned times carefully (may be UTC).

### Find a meeting by title

Preferred:
1. Ask `MCP_m365copilot_CopilotChat` for the meeting by title/date.

Fallback:
1. Use `MCP_calendar_ListEvents` with `meetingTitle = partial title` and a reasonable time window.
2. If mail context matters, also search `MCP_mail_SearchMessages`.

### Find meeting invite / reminder / recap

Use `MCP_mail_SearchMessages` for invite emails, reminders, webinar registrations, and recap emails with decks/recordings.

## Safe creation rule

1. Create the event with calendar APIs.
2. Immediately read it back.
3. Verify subject, start/end time, and timezone interpretation.
4. Only confirm to the user after verification.

## Safe modify/delete rule

1. Find the target with WorkIQ and/or a narrow `ListEvents` query.
2. If recurring, be cautious — exact instance resolution may be unreliable.
3. If exact target is unclear, ask once before taking action.

## Pitfalls

- `MCP_calendar_ListCalendarView` returns false empties — use `ListEvents` instead
- `attendeeEmails` is not a strict filter — do not rely on it alone
- `meetingTitle` works as a partial title filter only
- Returned event times may come back in UTC even when another timezone is requested
- Recurring instance lookup is unreliable (`ListEvents` may only expose the master)
- Do not trust event creation without read-back verification

