CLI and MCP server for NAVER WORKS / LINE WORKS — control messages, calendar, drive, mail, tasks, and boards from terminal or AI agents (Claude, Cursor)
The nworks server demonstrates moderate naming quality with consistent verb_noun patterns (send, list, create, update, delete) and tool annotations present. However, critical quality issues severely limit the score: (1) Parameter descriptions are completely absent from visible source code, no documentation of what inputs control or their valid values; (2) Output schemas are not documented, LLMs cannot predict response structure; (3) Error handling is not evident, no recovery guidance or error categorization; (4) Parameter constraints and formats not specified. While tool annotations (readOnlyHint, destructiveHint, idempotentHint) show awareness of pattern:tool-annotations, the fundamental schema and description documentation required by pattern:tool and pattern:tool-description is missing. Tool names are clear (e.g., nworks_calendar_create, nworks_drive_upload), but the absence of visible parameter documentation and output schema documentation is a critical gap. The tool-registry.ts shows annotation definitions but not the underlying parameter schemas used in tool registration.
Input parameter schemas not visible in source code. No Zod schema definitions, TypeScript interfaces, or JSON Schema declarations found for any tool parameters. Cannot verify parameter types, descriptions, constraints, enums, or validation rules. This violates pattern:tool and pattern:constrained-input, making tools non-discoverable and forcing LLMs to guess valid inputs.
Define explicit Zod schemas for ALL tool parameters with .describe() annotations. Example: z.object({ channel_id: z.string().describe('The ID of the target channel'), message_body: z.string().describe('The message text to send (max 5000 chars)') }). This must be visible in tool registration code.
Expand tool descriptions to 80 - 150 characters, answering: (1) What does this do? (2) When should I use it instead of related tools? (3) What does it return? Example: 'Send a message to a specific channel. Supports text and mentions. Returns message_id for downstream chaining.'
Add parameter descriptions for every input. For each parameter, document: data type, valid values/enums, range limits, format (regex/pattern), and examples. Example for channel_id: 'Channel identifier (returned by list_channels). Use the ID, not the channel name.'
Document output schemas. For each tool, add a comment or docstring specifying: response structure, field types, and field meanings. For list tools, include pagination fields (total, next_cursor, limit). Example: 'Returns { messages: [{ id, text, sender, timestamp }], total: number }'.
Implement pagination for all list-returning tools (calendar_list, drive_list, mail_list, task_list, board_posts, contact_list). Accept limit (default 20, max 100) and offset/cursor parameters. Return total_count or next_cursor. Cap default results at 20-50 items.
Add error message templates that guide LLM recovery. Example: 'User not found: "john_doe". Run nworks_directory_members to see available users.' Or: 'Invalid priority value "urgent". Must be one of: low, medium, high, critical.'
Parameter descriptions completely absent. While tool-level descriptions exist (e.g., 'Send message', 'Create calendar event'), individual parameter documentation is missing. LLMs cannot understand what each parameter controls, its expected format, valid values, constraints, or dependencies. Violates pattern:tool-description and pattern:parameter-annotation.
Output schemas not documented. No visible definition of tool response structures. LLMs cannot predict what fields will be returned, their types, or what values they can pass to downstream tools. Prevents proper tool chaining and forces agents to reason about response structure instead of planning. Violates pattern:tool and pattern:response-shaper.
No pagination or result limiting documented. Tools returning lists (nworks_calendar_list, nworks_drive_list, nworks_mail_list, nworks_task_list, nworks_board_posts, nworks_contact_list, etc.) do not document page/offset/limit parameters or result caps. Risk of context window exhaustion and degraded LLM reasoning on large result sets. Violates pattern:paginated-result.
No error handling guidance. No evidence of error messages that guide LLMs on recovery actions. When operations fail (e.g., invalid credentials, resource not found, permission denied), agents need actionable error messages with next steps. Violates pattern:recovery-guide and pattern:error-classification.
Tool descriptions are generic and brief (20 - 40 characters on average). Descriptions like 'Send message', 'List tasks', 'Create contact' lack context on WHEN to use each tool, WHAT it returns, and any prerequisites. Should be 50 - 200 characters with actionable guidance. Violates pattern:tool-description baseline of 194 chars average.
all 36 tools
Implement dry-run support for destructive operations (delete_calendar, delete_task, delete_contact, logout). Add optional confirm parameter. On confirm=false, return a confirmation_token. On confirm=true (with token), execute the operation. Prevents accidental deletions.
Add inter-tool dependency hints in descriptions. Example in nworks_message_send: 'If you only have a channel name, call nworks_message_members first to get the channel_id.' This guides agents to call discovery tools before write operations.
Move parameter schemas OUT of the defineTool helper and INTO the actual tool registration code (setup.ts, message.ts, etc.) so they are visible during code review. The current tool-registry.ts only defines annotations, not schemas.
Separate tool names to avoid verb overloading. 'nworks_contact_list', 'nworks_contact_get', and 'nworks_contact_create' are clear, but ensure all list tools use 'list' not 'get' when returning multiple items. Consistency aids LLM discoverability.
Add required vs optional parameter declarations. Example: 'channel_id (required)' vs 'thread_id (optional, for nested replies)'. Zod schema already supports this via .optional(), but descriptions must make it explicit.
Implement MRTR (Multi Round-Trip Request) pattern for complex workflows. For nworks_setup (save credentials), return result with input_required: 'Please verify the saved credentials by calling nworks_whoami.' This guides multi-step credential validation.
Add scope/permission declarations to tool descriptions. Example in nworks_mail_send: 'Requires: write:mail scope. Verify permissions with nworks_whoami before use.' This sets expectations for permission failures.