Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
Four tools are explicitly defined in src/mcp_caldav/server.py with complete JSON schemas and descriptions. Naming follows verb_noun convention (caldav_list_calendars, caldav_create_event, caldav_get_event_by_uid, caldav_delete_event). Descriptions are present but vary in quality, most are 20-50 chars, below the 50-200 char baseline for LLM optimization. Schemas are present and properly typed with JSON Schema, including enums for reminder actions and recurrence frequency. However, parameter descriptions lack depth: many parameters are under-documented (e.g., 'Event title' for title, 'Event UID' for uid). caldav_create_event has the most comprehensive schema with nested objects and constraints; caldav_list_calendars and caldav_get_event_by_uid are minimal. Output schemas are not documented, the tool definitions show input only, not what these tools return. Error handling is not visible in the tool definitions. Missing documentation of return structure forces LLMs to guess at response fields.
Output schemas not documented. Tool definitions show only input schemas; return types and response field structures are not specified. LLMs cannot predict what fields to extract or chain with downstream tools.
Descriptions are below LLM optimization baseline (50-200 chars). caldav_list_calendars='List all available calendars' (28 chars), caldav_get_event_by_uid='Get a specific event by its UID' (31 chars), caldav_delete_event='Delete an event by its UID' (26 chars). Too terse to guide LLM selection in complex scenarios.
Parameter descriptions lack actionable context. 'Event UID' does not explain format or where to obtain it. 'Event title' does not specify length limits or constraints. 'Calendar index (default: 0)' does not explain how to discover valid indices or why calendar_index is used instead of calendar_name.
Recommendations
Document output schemas for all four tools. E.g. 'Returns a list of calendar objects with fields: {name: string, uid: string, index: integer, color?: string, read_only: boolean}'. Make response structures explicit so LLMs know what to extract.
Expand tool descriptions to 50-150 characters with context on WHEN and WHY to use each tool. E.g. caldav_list_calendars: 'List all available calendars to discover calendar names and indices before creating or querying events. Returns a table of calendars you can access.'
Replace calendar_index integer parameter with calendar_name string in caldav_create_event, caldav_get_event_by_uid, and caldav_delete_event. Accept human-readable names like 'Work' or 'Personal' instead of opaque indices. If the backend uses indices internally, map names to indices inside the tool. This matches the chat data model and eliminates the need for a separate discovery call.
Add per-parameter constraints and format hints. E.g. title: 'Event title (1-200 characters, required)', description: 'Event details (0-4000 characters, supports Markdown)', location: 'Physical or virtual location (string, max 500 chars)'.
Clarify timezone handling in caldav_create_event. E.g. 'Start time in ISO 8601 format with timezone (e.g., "2025-01-20T14:00:00Z" for UTC or "2025-01-20T14:00:00-05:00" for Eastern). If timezone is omitted, defaults to UTC.'
Simplify caldav_create_event attendees to accept a single format: array of email address strings. Map status updates to a separate update_event_attendee_status tool if needed. Overloaded parameter types confuse LLMs.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
caldav_create_event requires opaque 'calendar_index' parameter (integer). No tool exists to discover valid calendar indices. LLMs must call caldav_list_calendars first, but that tool's return structure is undocumented, unclear if it returns indices or names.
caldav_delete_event is destructive but lacks confirmation pattern or dry-run option. No recovery tool documented. Agents can permanently delete events without explicit user approval.
Error handling and recovery guidance not visible. No indication of what errors these tools return, whether they are retryable, or what the LLM should do on failure.
caldav_create_event start_time and end_time descriptions say 'ISO format (e.g., "2025-01-20T14:00:00")' but do not clarify timezone handling. Do inputs expect UTC, local, or timezone-aware ISO strings? Ambiguity invites parsing errors.
caldav_create_event attendees parameter accepts both strings (email addresses) and objects with email+status, but the schema and description do not clarify when each form is used or how to transition from one to the other.
caldav_create_event
Add a dry_run boolean parameter to caldav_delete_event (defaults to false) to support a two-step confirmation: dry-run to show what will be deleted, then call again with dry_run=false to confirm. Or document a confirmation/approval pattern in the description.
Document error cases and recovery paths. E.g. 'If calendar not found, call caldav_list_calendars to see available calendars. If event UID is invalid, call caldav_list_calendars and query events from that calendar first.'
Clarify recurrence rule semantics in caldav_create_event. E.g. 'Recurrence object defines a repeating schedule using iCalendar RRULE syntax. frequency is required; interval, count, until, and byday/bymonthday/bymonth are optional modifiers. Example: {"frequency": "WEEKLY", "byday": "MO,WE,FR", "count": 10} repeats every Monday, Wednesday, Friday for 10 occurrences.'
Add pagination support to caldav_list_calendars if the result set can be large. Include a limit parameter (default 20, max 100) and return total_count so LLMs know if more calendars exist.