This Swift-based calendar MCP server defines 7 tools with complete input schemas and descriptions. However, there are systematic gaps in parameter descriptions, output schema documentation, and error handling guidance. Naming is clear and verb-prefixed throughout, which is good. The server correctly declares tool names with calendar_ prefix and action verbs (list, create, get, update, delete, search). Input schemas are present and properly typed for all tools. However, parameter descriptions are minimal, many lack context about expected formats, ranges, or when to use related tools. Output schemas are not documented at all, forcing LLMs to guess what fields will be returned. Error handling is minimal, no guidance on recovery, retry eligibility, or actionable fixes. The recurrence parameters in create_event and update_event are complex but lack validation or dependency documentation. No tool has security annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications. Strings like 'daily, weekly, monthly, yearly' appear in descriptions but should be enums for constraint enforcement.
Output schemas entirely missing. LLMs must guess what fields are returned from each tool call, forcing extra discovery calls and inference errors. None of the 7 tools document their response structure.
Recurrence parameters use prose enums instead of JSON Schema enums. 'recurrenceFrequency: daily, weekly, monthly, yearly' in description should be enum: ["daily", "weekly", "monthly", "yearly"] in schema. This forces LLMs to hallucinate valid values and violates constraint-driven input pattern.
Parameter descriptions lack format and constraint specification. Examples: 'Start date and time (YYYY-MM-DD HH:MM or YYYY-MM-DD)' uses examples instead of declarative rules; 'Event identifier' for eventId gives no hint about format, source, or nullability. PROJ)' is the pattern to follow.
Recommendations
Add output schema documentation for every tool. Document return type (array of events? single event object?) and all fields (event_id, title, start_date, end_date, location, recurrence_rule, etc.). Example: 'Returns: array of {event_id: string, title: string, start: ISO8601 datetime, end: ISO8601 datetime, location: string, notes: string}'.
Convert recurrenceFrequency from prose enum to JSON Schema enum. Change description from 'Recurrence frequency: daily, weekly, monthly, yearly (optional)' to formal constraint: 'enum: ["daily", "weekly", "monthly", "yearly"]. Recurrence frequency for the event.'
Explicitly document recurrence parameter dependencies in schema and descriptions. Add note: 'recurrenceWeekdays only applies if recurrenceFrequency is weekly or monthly. recurrenceDaysOfMonth only applies to monthly or yearly. recurrenceMonths only applies to yearly.'
Enhance date/time parameter descriptions with declarative format rules and timezone handling. Example: 'startDate: ISO8601 datetime string (YYYY-MM-DDTHH:MM:SS or YYYY-MM-DD for all-day). Timezone defaults to user's configured calendar timezone if not specified.'
Add error handling guidance to all tool descriptions. Example for calendar_delete_event: 'Error: event_not_found (404) → call calendar_search_events to find the event. Error: permission_denied (403) → user lacks calendar write access. Error: recurrence_series (409) → specify which occurrence to delete or delete entire series.'
Add destructiveHint annotation to calendar_delete_event in tool definition. Declare: 'destructiveHint: true' to signal to agents that this operation is irreversible and requires caution or confirmation.
No error handling guidance. Tools have no descriptions of what errors can occur (event not found, permission denied, timezone invalid) or what the LLM should do next (retry, ask user, try alternate tool).
Destructive operations lack security annotations and confirmation patterns. calendar_delete_event is marked DESTRUCTIVE but has no readOnlyHint/destructiveHint annotation in schema, and no confirmation or dry-run step to prevent accidental deletion. Per pattern:confirmation-request, agents make mistakes.
Undocumented parameter dependencies and constraints. Recurrence fields in create_event and update_event have complex interactions (recurrenceWeekdays only applies to weekly/monthly, recurrenceDaysOfMonth only to monthly/yearly, recurrenceMonths only to yearly) but schema does not declare these. LLMs cannot reason about valid combinations without explicit documentation.
Missing pagination and result limits. calendar_list_events and calendar_search_events do not document max results, pagination parameters (limit, offset, cursor), or total count in response.
Search tool (calendar_search_events) lacks specification of search scope. Does 'query' search title only, or title+notes+attendees? Case-sensitive? Substring or exact? Full-text? This forces LLMs to guess or make redundant calls to list_events and filter locally.
calendar_search_events
Implement confirmation/dry-run pattern for delete_event. Add optional parameter 'confirm_delete: boolean (default: false)' or return 'requires_confirmation: true' in response to force explicit confirmation before actually deleting.
Add pagination support to calendar_list_events and calendar_search_events. Add parameters: 'limit: integer (1 - 100, default 20)' and 'offset: integer (default 0)'. Return total_count and has_more in response to enable iterative fetching.
Clarify calendar_search_events scope in description: 'Searches event title and notes for the query string (case-insensitive substring match). Returns up to 20 matching events. To search attendees or location, use calendar_list_events and filter manually.'
Document timezone handling. Calendar operations likely involve timezone conversion, document whether times are treated as UTC, local, or calendar-specific. Example: 'Times are interpreted in the calendar's configured timezone. Use ISO8601 with explicit timezone (e.g., 2025-03-26T14:00:00-05:00) to override.'
Add parameter type hints to eventId, calendarId, query. Example: 'eventId: string (opaque calendar event identifier, returned by calendar_list_events or calendar_create_event).'
Document what fields can be updated in calendar_update_event. Note: 'You can update title, startDate, endDate, location, notes, allDay, and recurrence settings. Cannot change event permissions or attendee list via this tool.'
Add idempotentHint annotations. Tools like calendar_list_events and calendar_get_event are read-only and idempotent, mark them to signal safe retry to agents.