Output schemas not documented. The source code shows tool descriptions and input schemas, but no documented return types for any of the 30 tools. LLMs cannot plan downstream tool calls or extract needed data without knowing what fields a response contains.
Delete operations lack confirmation or dry-run support. Tools like delete_client, delete_project, delete_task, delete_tag, delete_time_entry, and bulk_delete_time_entries are destructive but provide no confirmation step or recovery guidance. Agents can permanently delete data without safeguards.
Document output schemas for all 30 tools. For each tool, describe the return type and key fields (e.g., 'Returns a Client object with fields: id (string), name (string), address (string), note (string), archived (boolean, default false).'). Include this in the tool registration or a separate schema document.
Add confirmation or dry-run support for destructive operations. Implement a pattern like 'delete_client' → returns a confirmation message with the client name and count of related projects, and requires an 'confirmed' parameter set to true. Or offer a 'confirm_delete_client' tool that must be called before the actual delete.
Improve error handling with categorization and recovery steps. When the Clockify API returns a 404, catch it and return: 'Client not found. Verify the workspace ID and client ID are correct, or call list_clients() to find the correct ID.' For rate limits (429), return: 'API rate limit reached. Retry in 60 seconds.' For auth errors (401), return: 'Invalid API key. Check CLOCKIFY_API_KEY environment variable.'
Expand descriptions for delete operations to 50-80 characters and clarify irreversibility. Example: 'Permanently delete a client. This cannot be undone. Related projects will orphan. Confirm the client ID and name before proceeding.'
Convert enum constraints from description text to JSON Schema enum fields. For example, 'status' in create_task should be: { 'type': 'string', 'enum': ['ACTIVE', 'DONE'], 'description': 'Task status. ACTIVE for ongoing work, DONE for completed tasks.' }. Apply this to all fields with fixed valid values.
Error handling does not guide recovery. The API client (src/api/client.ts) throws generic error messages like 'Clockify API error (${response.status}): ${errorText}' without categorizing errors or suggesting next steps. LLMs have no guidance on whether to retry, ask the user, or escalate.
Descriptions for delete operations are minimal (under 25 chars). Tools like delete_client, delete_project, delete_task, delete_tag, delete_time_entry have single-line descriptions ('Delete a client', 'Delete a project', etc.) that fail to clarify consequences or confirm irreversibility.
Parameter constraints incomplete. Numeric parameters like page and pageSize lack min/max bounds, and enum fields like status lack explicit value lists. For example, create_task status says 'ACTIVE or DONE (optional)' in a string description rather than declaring an enum schema.
No pagination guidance in tool descriptions. While list tools accept page/pageSize parameters, no description states the default page size, max results limit, or when to use pagination. LLMs may request 10,000 results and exhaust context.
Ambiguous parameter descriptions for complex objects. The update_workspace 'settings' parameter is described as 'Workspace settings object with optional properties: ...' but lacks a formal schema. The estimate parameter in create_project and update_project is described as 'Estimate object with estimate and type (AUTO|MANUAL) fields' without a typed schema object.
Dependencies between parameters undocumented. For example, create_task accepts assigneeIds but the description does not explain how to resolve user names to IDs, forcing an extra lookup call. Similarly, projectId and taskId in create_time_entry are optional but interdependent, the description does not clarify valid combinations.
create_taskcreate_time_entryupdate_time_entry
Add pagination guidance to list tool descriptions. Example: 'Returns up to 50 results per page by default. Use page and pageSize parameters to fetch additional results. Maximum pageSize is 100 to avoid context overflow.'
Document parameter dependencies. Add notes like: 'assigneeIds: (optional) Array of Clockify user IDs. To resolve a user by name, call list_users() first (not yet available, contact workspace admins for user IDs). If empty, the task is unassigned.' For create_time_entry, clarify: 'projectId and taskId are both optional but recommended. Tasks must belong to the same project as the time entry.'
Add pagination limits to numeric parameters. Example: { 'type': 'number', 'description': 'Page number (1-based). Default: 1', 'minimum': 1 } and { 'type': 'number', 'description': 'Results per page. Default: 50, max: 100', 'minimum': 1, 'maximum': 100 }.
Implement structured error responses. Instead of throwing raw errors, return objects like { 'success': false, 'error_code': 'RESOURCE_NOT_FOUND', 'error_message': 'Client not found with ID: xyz123', 'recovery_hint': 'Call list_clients() to find the correct client ID', 'suggestion': 'Did you mean: Acme Corp (ID: abc456)?' } so LLMs can programmatically handle and recover from errors.