This server has significant structural and documentation gaps. Tool naming is verb-based and mostly clear, but descriptions are inconsistent in quality. Input schemas are present for all tools but lack important details like minLength, maxLength, and enum constraints for string fields. Parameter descriptions are repetitive and generic. Output schemas are not documented at all. Error handling is present in code but not reflected in tool descriptions. Security concerns around credential handling are mitigated by server-side injection but not documented in tool specs. The `__email_address__` parameter is overloaded and appears in every tool, creating verbosity and unclear semantics, the server should abstract this to a request context rather than expose it as a user-facing parameter.
__email_address__ exposed as a required parameter in every tool. This is internal implementation detail (credential context) that should be abstracted into server-side request metadata or context, not exposed to LLM. Adds noise and confusion to every tool signature.
Add complete output schemas for all 10 tools. Document the structure returned by the API: fields, types, examples. Use JSON Schema format in tool definition.
Remove __email_address__ from tool parameters. Instead, store the authorized email in server-side context (e.g., environment variable, request metadata, or session state). Modify tools to accept only non-authentication parameters. This reduces parameter clutter and removes credential leakage risk.
Add JSON Schema constraints to parameters: enums for 'color', minLength/maxLength for strings, min/max for numeric fields (reminder times, image dimensions). Example: 'reminder': {'type': 'integer', 'minimum': 0, 'maximum': 10080, 'description': 'Minutes before event to remind (0-10080)'}.
For message template tools, flatten or provide clearer documentation of nested structures. For 'send_feed_template_to_me', document valid values for 'item_op' (is it arithmetic operator like '+', '-'?). Provide an example payload in a separate schema or documentation link.
Enhance tool descriptions to explain use cases and selection criteria. E.g., 'send_feed_template_to_me: Rich message with image, description, and action buttons. Use when sharing articles, products, or curated content. Supports rich formatting and social metadata (likes, comments).'
Implement pagination for 'get_calendar_list'. Add 'limit' (default 20, max 100) and 'offset' or 'cursor' parameters. Document in description: 'Returns up to 20 calendars per request. Use offset/limit for pagination.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Parameter descriptions lack format constraints. 'color' field in calendar tools has no enum or pattern. String fields like 'name', 'title', 'description' have no minLength/maxLength. Numeric fields ('reminder', 'image_width') lack min/max bounds. LLMs cannot validate inputs before calling.
Message template tools have overly complex nested schemas with inadequate descriptions. E.g., 'send_feed_template_to_me' has deeply nested 'content.item_content.items' array with objects containing 'item' and 'item_op' properties, no description of what these fields mean or valid values for 'item_op'.
Tool descriptions do not explain use cases or when to select one template type over another. Why send_text_template vs send_feed_template? What is the difference in UX? Descriptions are bare one-liners that do not guide LLM selection.
No pagination support or result limits documented. 'get_calendar_list' returns raw API response without documented limits. If a user has 1000+ calendars, response could be massive and blow context window.
Error handling exists in code (BaseKakaoCalendarToolHandler.run_tool) but is not reflected in tool descriptions. LLMs cannot anticipate error states or recovery actions. No indication of retryable vs fatal errors, or what to do if token refresh fails.
Destructive operations (delete_sub_calendar) lack confirmation or dry-run support. Code contains no confirmation gate, agent can delete calendars without preview.
Tool naming convention: 'send_*_to_me' is awkward. If all messages are sent to the authenticated user, this is implicit. Better: 'send_text_message', 'send_feed_message', etc. Current phrasing is redundant and slightly anthropomorphic.
Document error conditions in tool descriptions. E.g., 'delete_sub_calendar: Irreversible operation. Returns error if calendar_id not found or user lacks permission. No undo available.'
Add a confirmation/dry-run step for 'delete_sub_calendar'. Modify tool to accept a 'confirm' boolean parameter (default false). If false, return 'Would delete calendar: [name]. Call again with confirm=true to execute.' This prevents accidental data loss.
Rename message template tools to remove 'to_me' suffix. Suggested names: 'send_text_message', 'send_feed_message', 'send_list_message', 'send_location_message', 'send_calendar_event_message', 'send_product_message'. Cleaner and more composable.
Add a 'required' array to input schemas where applicable. Ensure only truly mandatory parameters are marked required; optional parameters should be explicit in schema.