Upload a local file to a task as an attachment (v2).

Reads the file at file_path from the local filesystem and posts it to the task as multipart/form-data (the ClickUp file field is attachment). Files already stored in the cloud cannot be used here.

When to Use:

• To attach a document, image, or log file that exists on the local disk to a task.

When NOT to Use:

• To upload to a File-type Custom Field, or if you prefer the newer API — use clickup_create_entity_attachment (v3).

• To read existing attachments — use clickup_get_entity_attachments.

Returns: A confirmation with the new attachment's id and URL. The file bytes are never echoed back.

Examples:

• params = {"task_id": "abc", "file_path": "/tmp/report.pdf"}

• custom task ID: params = {"task_id": "PROJ-1", "file_path": "./log.txt", "custom_task_ids": true, "team_id": "123"}

Error Handling: A ValidationError before the request means the path is missing/empty/too large; a 404 means the task ID is wrong.

List the attachments of a task or File-type Custom Field (v3).

Calls GET /v3/workspaces/{workspace_id}/{entity_type}/{entity_id}/attachments and returns the page of attachments plus the cursor for the next page.

When to Use:

• To enumerate the files attached to a task (entity_type='attachments') or a File Custom Field (entity_type='custom_fields').

When NOT to Use:

• To upload a file — use clickup_create_entity_attachment or clickup_create_task_attachment.

Returns: Each attachment's title, id, size, and URL. When more results exist, the response includes the cursor to pass back as cursor for the next page.

Pagination: Cursor-based and asymmetric — the request takes cursor, the response returns next_cursor. Loop: pass the returned next_cursor back as cursor until it is absent.

Examples:

• task: params = {"workspace_id": "123", "entity_type": "attachments", "entity_id": "abc"}

• custom field: params = {"workspace_id": "123", "entity_type": "custom_fields", "entity_id": "fld-1", "limit": 20}

Error Handling: A 404 means the entity_id was not found — or the v3 attachments surface is not available on this Workspace at all (verified live on a Business-plan workspace: even reads 404). If both tools here 404 on ids that definitely exist, fall back to clickup_create_task_attachment (v2) for task files. A 400 usually means entity_type and entity_id do not match (e.g. a Custom Field ID with entity_type='attachments').

Upload a local file to a task or File-type Custom Field (v3).

Reads the file at file_path and posts it as multipart/form-data to POST /v3/workspaces/{workspace_id}/{entity_type}/{entity_id}/attachments. After uploading to a Custom Field (entity_type='custom_fields'), call clickup_set_custom_field_value to associate the uploaded file with a task.

When to Use:

• The modern replacement for clickup_create_task_attachment, and the only way to upload to a File-type Custom Field.

When NOT to Use:

• To read existing attachments — use clickup_get_entity_attachments.

Returns: A confirmation with the new attachment's id and URL (never the file bytes).

Examples:

• task: params = {"workspace_id": "123", "entity_type": "attachments", "entity_id": "abc", "file_path": "/tmp/a.png"}

• custom field: params = {"workspace_id": "123", "entity_type": "custom_fields", "entity_id": "fld-1", "file_path": "./a.png"}

Error Handling: A ValidationError before the request means the path is missing/empty/too large; a 404 means the entity_id was not found — or the v3 attachments surface is not available on this Workspace (verified live: some plans 404 on this endpoint entirely; use clickup_create_task_attachment for task files in that case).

List the Chat channels in a Workspace, with descriptor filters.

Returns Channels, DMs, and Group DMs the authorized user can see. Narrow the result with channel_types, is_follower, include_closed, or with_message_since. Results are cursor-paginated.

When to Use:

• To find a channel's id before reading it (clickup_get_chat_channel), posting to it, or listing its members.

• To enumerate only DMs (channel_types=["DM","GROUP_DM"]) or only followed channels (is_follower=true).

When NOT to Use:

• To read messages in a channel — that lives in clickup_get_chat_messages (chat_messages module).

Returns: A list of channels (name, id, type, visibility). When more results exist the response includes a next_cursor; pass it back as cursor to page forward.

Pagination: Cursor-based and asymmetric. Loop: call once, read next_cursor from the output, then call again with cursor=<next_cursor> until it is empty.

Examples:

• params = {"channel_types": ["CHANNEL"], "limit": 100}

• params = {"is_follower": true, "cursor": "eyJ..."}

Error Handling: 401 → bad token; 404 → unknown Workspace id. Errors return an Error ... string.

Create a Workspace-level Chat channel by name.

If a Channel with the given name already exists, ClickUp returns that existing Channel instead of creating a duplicate.

When to Use:

• To open a general, non-location-bound channel (e.g. "#announcements").

When NOT to Use:

• To attach a channel to a Space/Folder/List — use clickup_create_location_chat_channel.

• To start a direct message — use clickup_create_direct_message.

Returns: A confirmation with the channel's name, id, and visibility.

Examples:

• params = {"name": "announcements", "visibility": "PUBLIC"}

• params = {"name": "team-x", "user_ids": ["123", "456"], "topic": "Team X"}

Error Handling: 400 → bad payload; 401 → bad token. Errors return an Error ... string.

Create a Chat channel bound to a Space, Folder, or List.

The channel's name is derived from the location, so there is no name field — pass the location id and its type instead. The location is sent as {"id": <location_id>, "type": <space|folder|list>}.

When to Use:

• To give a specific Space/Folder/List its own conversation channel.

When NOT to Use:

• For a standalone, named channel — use clickup_create_chat_channel.

• For a DM — use clickup_create_direct_message.

Returns: A confirmation with the channel's name, id, and bound location.

Examples:

• params = {"location_id": "901300", "location_type": "space"}

• params = {"location_id": "L9", "location_type": "list", "visibility": "PRIVATE"}

Error Handling: 400 → bad location; 404 → location not found. Errors return an Error ... string.

Create (or return) a direct-message Chat channel with up to 15 users.

One recipient id makes a 1:1 DM; two or more make a Group DM. Omit user_ids (or pass an empty list) to create a Self DM. ClickUp returns the existing DM channel if one already exists for the same participant set.

When to Use:

• To message one or a few users directly rather than in a shared channel.

When NOT to Use:

• For a named or location-bound channel — use clickup_create_chat_channel or clickup_create_location_chat_channel.

Returns: A confirmation with the DM channel's id and participant count.

Examples:

• params = {"user_ids": ["123"]}

• params = {"user_ids": ["123", "456", "789"]}

• params = {} # Self DM

Error Handling: 400 → more than 15 users / bad id; 401 → bad token. Errors return an Error ... string.

Fetch a single Chat channel's metadata by id.

When to Use:

• To confirm a channel's type, visibility, topic, or bound location by id.

When NOT to Use:

• To list many channels — use clickup_get_chat_channels.

• To read its messages — use clickup_get_chat_messages.

Returns: The channel's name, id, type, visibility, topic, description, and location.

Examples:

• params = {"channel_id": "6-901300-8"}

Error Handling: 404 → channel not found. Errors return an Error ... string.

Update a Chat channel's name, description, topic, visibility, or location.

Send only the fields you want to change (at least one is required). Text is interpreted per content_format — text/md (default) or text/plain. To re-bind the channel to another Space/Folder/List, pass location_id and location_type together.

When to Use:

• To rename a channel, update its topic/description, or toggle visibility.

When NOT to Use:

• To delete a channel — use clickup_delete_chat_channel.

Returns: A confirmation listing the fields that were updated.

Examples:

• params = {"channel_id": "6-901300-8", "topic": "Sprint 42"}

• params = {"channel_id": "6-901300-8", "visibility": "PRIVATE"}

Error Handling: 400 → bad payload; 404 → channel not found. Errors return an Error ... string.

Permanently delete a Chat channel (Channel, DM, or location-bound).

When to Use:

• To remove a channel that is no longer needed.

When NOT to Use:

• To only hide/archive it — update its state via clickup_update_chat_channel.

Returns: A confirmation that the channel was deleted.

Examples:

• params = {"channel_id": "6-901300-8"}

Error Handling: 404 → channel not found. Errors return an Error ... string.

List the users following a Chat channel.

Followers receive notifications for the channel but are not necessarily members. Results are cursor-paginated.

When to Use:

• To see who is subscribed to a channel's activity.

When NOT to Use:

• To see who can access/post — use clickup_get_chat_channel_members.

Returns: A list of follower users (name, id, email). When more results exist the response includes a next_cursor; pass it back as cursor to page forward.

Pagination: Cursor-based. Loop with cursor=<next_cursor> until it is empty.

Examples:

• params = {"channel_id": "6-901300-8"}

• params = {"channel_id": "6-901300-8", "cursor": "eyJ...", "limit": 100}

Error Handling: 404 → channel not found. Errors return an Error ... string.

List the users who are members of a Chat channel.

Members can access and post to the channel. Results are cursor-paginated.

When to Use:

• To audit who has access to a private channel or DM.

When NOT to Use:

• To see subscribers only — use clickup_get_chat_channel_followers.

Returns: A list of member users (name, id, email). When more results exist the response includes a next_cursor; pass it back as cursor to page forward.

Pagination: Cursor-based. Loop with cursor=<next_cursor> until it is empty.

Examples:

• params = {"channel_id": "6-901300-8"}

• params = {"channel_id": "6-901300-8", "cursor": "eyJ...", "limit": 100}

Error Handling: 404 → channel not found. Errors return an Error ... string.

List the messages in a Chat channel (newest first), cursor-paginated.

When to Use:

• To read a channel's conversation, or to grab a message id before replying, reacting, updating, or deleting.

When NOT to Use:

• To list channels themselves — use clickup_get_chat_channels (chat_channels).

• To read one message's replies — use clickup_get_chat_message_replies.

Returns: Each message's author, id, timestamp, reply count, and a content snippet. When more results exist the output includes a next_cursor to page forward.

Pagination: Cursor-based. Call once, read next_cursor, then call again with cursor=<next_cursor> until it is empty.

Examples:

• params = {"channel_id": "6-901..."}

• params = {"channel_id": "6-901...", "cursor": "eyJ...", "limit": 100}

Error Handling: 404 → unknown channel id; 401 → bad token. Errors return an Error ... string.

List the replies threaded under a Chat message, cursor-paginated.

When to Use:

• To read a thread hanging off a specific message.

When NOT to Use:

• To list top-level channel messages — use clickup_get_chat_messages.

Returns: Each reply's author, id, timestamp, and content snippet, plus a next_cursor when more replies exist.

Pagination: Cursor-based (see clickup_get_chat_messages).

Examples:

• params = {"message_id": "abc123"}

• params = {"message_id": "abc123", "cursor": "eyJ..."}

Error Handling: 404 → unknown message id. Errors return an Error ... string.

List the emoji reactions on a Chat message, cursor-paginated.

When to Use:

• To see who reacted to a message and with which emoji.

When NOT to Use:

• To add or remove a reaction — use clickup_add_chat_reaction / clickup_delete_chat_reaction.

Returns: Each reaction's emoji name and the user who added it, plus a next_cursor when more exist.

Pagination: Cursor-based (see clickup_get_chat_messages).

Examples:

• params = {"message_id": "abc123"}

Error Handling: 404 → unknown message id. Errors return an Error ... string.

List the users @-tagged (mentioned) in a Chat message, cursor-paginated.

When to Use:

• To find who was mentioned in a message (e.g. to follow up or notify).

When NOT to Use:

• To list a channel's members — use clickup_get_chat_channel_members (chat_channels).

Returns: Each tagged user's name and id, plus a next_cursor when more exist.

Pagination: Cursor-based (see clickup_get_chat_messages).

Examples:

• params = {"message_id": "abc123"}

Error Handling: 404 → unknown message id. Errors return an Error ... string.

List a Workspace's post subtype IDs (Announcement, Discussion, Idea, Update).

Subtype IDs are unique per Workspace and are required when sending a rich 'post' message: pass the chosen id via post_data={"subtype": {"id": "..."}} on clickup_send_chat_message (or clickup_send_chat_reply) with message_type='post'.

When to Use:

• Before sending a post-type chat message, to resolve the subtype id to use.

When NOT to Use:

• For plain messages — post subtypes only apply to message_type='post'.

Returns: Each subtype's name and id for the requested comment family.

Examples:

• params = {"comment_type": "post"}

Error Handling: 404 → unknown Workspace. Errors return an Error ... string.

Post a new message to a Chat channel.

Defaults to a plain 'message'. For a rich 'post' (Announcement/Discussion/Idea/ Update), set message_type='post' and pass the subtype id in post_data={"subtype": {"id": "..."}} — get the id from clickup_get_chat_subtypes.

When to Use:

• To send a message into a channel.

When NOT to Use:

• To reply within a thread — use clickup_send_chat_reply.

• To change an existing message — use clickup_update_chat_message.

Returns: A confirmation with the new message's id and channel.

Examples:

• params = {"channel_id": "6-901...", "content": "Deploy is green ✅"}

• params = {"channel_id": "6-901...", "content": "Q3 kickoff", "message_type": "post", "post_data": {"subtype": {"id": "123"}}}

Error Handling: 400 → bad body (e.g. content too long); 404 → unknown channel. Errors return an Error ... string.

Post a threaded reply under an existing Chat message.

When to Use:

• To respond within a message's thread.

When NOT to Use:

• To start a new top-level message — use clickup_send_chat_message.

Returns: A confirmation with the new reply's id and the parent message id.

Examples:

• params = {"message_id": "abc123", "content": "On it 👍"}

Error Handling: 400 → bad body; 404 → unknown parent message. Errors return an Error ... string.

Edit a Chat message's content, assignee, or resolved state.

Send only the fields you want to change; resolved is a top-level body field (not part of post_data).

When to Use:

• To fix a message's text, (re)assign it, or mark a post resolved/unresolved.

When NOT to Use:

• To remove a message entirely — use clickup_delete_chat_message.

• To react to it — use clickup_add_chat_reaction.

Returns: A confirmation naming the message and the fields changed.

Examples:

• params = {"message_id": "abc123", "content": "edited text"}

• params = {"message_id": "abc123", "resolved": true}

Error Handling: 404 → unknown message id. Errors return an Error ... string.

Permanently delete a Chat message (and its replies).

When to Use:

• To remove a message you posted in error.

When NOT to Use:

• To edit it instead — use clickup_update_chat_message.

Returns: A confirmation that the message was deleted.

Examples:

• params = {"message_id": "abc123"}

Error Handling: 404 → already gone / unknown id. Errors return an Error ... string.

Add an emoji reaction to a Chat message.

reaction is the lower-case emoji name (e.g. thumbsup, heart, tada); it is lower-cased for you.

When to Use:

• To react to a message with an emoji.

When NOT to Use:

• To remove a reaction — use clickup_delete_chat_reaction.

• To list reactions — use clickup_get_chat_message_reactions.

Returns: A confirmation naming the emoji and message.

Examples:

• params = {"message_id": "abc123", "reaction": "thumbsup"}

Error Handling: 400 → unknown emoji name; 404 → unknown message. Errors return an Error ... string.

Remove an emoji reaction from a Chat message.

reaction is the lower-case emoji name and is sent as a path segment.

When to Use:

• To undo a reaction you added.

When NOT to Use:

• To add one — use clickup_add_chat_reaction.

Returns: A confirmation that the reaction was removed.

Examples:

• params = {"message_id": "abc123", "reaction": "thumbsup"}

Error Handling: 404 → reaction/message not found. Errors return an Error ... string.

Add a new (empty) checklist to a task.

Checklists group related to-do items on a task; add items afterwards with clickup_create_checklist_item.

When to Use:

• Breaking a task into a set of trackable sub-steps that are not full tasks.

When NOT to Use:

• For work that needs its own assignee, due date, or status — create a subtask instead (clickup_create_task with a parent).

Returns: A confirmation string with the new checklist's name and id.

Examples: params = {"task_id": "9hz", "name": "Pre-launch checks"} params = {"task_id": "CUST-123", "name": "QA", "custom_task_ids": True, "team_id": "123"}

Error Handling: 404 means the task_id does not exist; 403 with custom_task_ids commonly means the team_id does not match the token's Workspace.

Rename a checklist and/or reposition it among a task's other checklists.

When to Use:

• Renaming a checklist, or reordering checklists on a task (position: 0 moves one to the top).

When NOT to Use:

• To resolve/reorder individual items — use clickup_edit_checklist_item.

Returns: A confirmation string with the updated checklist's name and id.

Examples: params = {"checklist_id": "b8a8...", "name": "Launch checklist"} params = {"checklist_id": "b8a8...", "position": 0}

Error Handling: 404 means the checklist_id does not exist.

Permanently remove a checklist (and all of its items) from its task.

When to Use:

• The checklist is no longer needed.

When NOT to Use:

• To remove a single item, use clickup_delete_checklist_item instead — this deletes the whole checklist.

Returns: A confirmation string naming the deleted checklist id.

Error Handling: 404 means the checklist_id does not exist (may already be deleted).

Add a new line item to an existing checklist.

When to Use:

• Adding a to-do line to a checklist created with clickup_create_checklist.

When NOT to Use:

• To create the checklist itself first — use clickup_create_checklist.

Returns: A confirmation string; when the API response includes the new item's id it is included, otherwise only the item name and checklist id are echoed.

Examples: params = {"checklist_id": "b8a8...", "name": "Write tests"} params = {"checklist_id": "b8a8...", "name": "Review PR", "assignee": 183}

Error Handling: 404 means the checklist_id does not exist; 400 for an invalid assignee id.

Rename, (un)resolve, reassign, or nest/un-nest a checklist item.

Nesting: pass parent (another item's checklist_item_id) to indent this item under it; pass clear_parent=True to move it back to the top level.

When to Use:

• Checking off progress (resolved=True), reassigning, or building a nested checklist structure.

When NOT to Use:

• To remove the item entirely, use clickup_delete_checklist_item.

Returns: A confirmation string describing the applied changes.

Examples: params = {"checklist_id": "b8a8...", "checklist_item_id": "9f1...", "resolved": True} params = {"checklist_id": "b8a8...", "checklist_item_id": "9f1...", "parent": "aa2..."} params = {"checklist_id": "b8a8...", "checklist_item_id": "9f1...", "clear_assignee": True}

Error Handling: 404 means the checklist_id or checklist_item_id does not exist.

Remove a single line item from a checklist (the checklist itself stays).

When to Use:

• The individual to-do is no longer relevant, but the rest of the checklist should remain.

When NOT to Use:

• To remove the whole checklist, use clickup_delete_checklist.

Returns: A confirmation string naming the deleted item id.

Error Handling: 404 means the checklist_id or checklist_item_id does not exist.

Add a comment to a task.

Posts to POST /task/{task_id}/comment.

When to Use:

• To leave feedback, ask a question, or hand off context on a task.

• To assign a follow-up action item via assignee/group_assignee.

When NOT to Use:

• To reply inside an existing comment thread — use clickup_create_threaded_comment.

• To comment on a List's info panel or a Chat view — use clickup_create_list_comment / clickup_create_chat_view_comment.

Returns: A confirmation string with the new comment's id, hist_id, and timestamp, or an Error ... string on failure.

Examples: params = {"task_id": "abc123", "comment_text": "Blocked on design review.", "notify_all": True}

Error Handling: 404 means the task id is wrong; 403 can mean you lack comment access on the task.

List comments on a task, newest first.

Calls GET /task/{task_id}/comment.

When to Use:

• To read discussion history on a task before acting on it.

When NOT to Use:

• To read replies inside a specific thread — use clickup_get_threaded_comments.

Returns: Markdown (default) or JSON list of comments with id, author, date, resolved state, assignee, and (truncated) text.

Pagination: Cursor-based, NOT limit/offset. Omit start/start_id for the most recent 25 comments (ClickUp's fixed page size — not configurable). To page to OLDER comments, pass the oldest comment's date as start and its id as start_id; the markdown output surfaces both values whenever a full page (25) comes back, so callers can loop until a short page signals the end.

Examples: params = {"task_id": "abc123"} params = {"task_id": "abc123", "start": 1508369194377, "start_id": "446750"}

Error Handling: 404 means the task id is wrong.

Add a comment to a List's info panel.

Posts to POST /list/{list_id}/comment.

When to Use:

• To leave a note on the List itself (not on an individual task) — e.g. a status update visible to everyone with access to the List.

When NOT to Use:

• To comment on a specific task — use clickup_create_task_comment.

Returns: A confirmation string with the new comment's id, hist_id, and timestamp, or an Error ... string on failure.

Examples: params = {"list_id": "901234", "comment_text": "Sprint scope finalized.", "notify_all": False}

Error Handling: 404 means the list id is wrong; 403 can mean you lack comment access on the list.

List comments on a List's info panel, newest first.

Calls GET /list/{list_id}/comment.

When to Use:

• To read the List-level discussion/status history.

When NOT to Use:

• To read comments on a specific task — use clickup_get_task_comments.

Returns: Markdown (default) or JSON list of comments with id, author, date, resolved state, assignee, and (truncated) text.

Pagination: Cursor-based (start/start_id), identical pattern to clickup_get_task_comments — see that tool's docstring for the full explanation. Omit both for the most recent 25 comments.

Examples: params = {"list_id": "901234"}

Error Handling: 404 means the list id is wrong.

Post a comment into a Chat view.

Posts to POST /view/{view_id}/comment. This is the legacy Chat-view comment surface (views of type=conversation); the newer, richer Chat API (channels + messages, all v3) lives in tools/chat_messages.py — prefer that module for new Chat integrations, and this tool only when you are already working with a Chat-type view id.

When to Use:

• To post into an existing Chat view when you already have its view_id.

When NOT to Use:

• To send a message in a modern Chat channel — use clickup_send_chat_message (tools/chat_messages.py) instead.

Returns: A confirmation string with the new comment's id, hist_id, and timestamp, or an Error ... string on failure.

Examples: params = {"view_id": "105", "comment_text": "Standup notes for today."}

Error Handling: 404 means the view id is wrong or is not a Chat-type view.

List comments in a Chat view, newest first.

Calls GET /view/{view_id}/comment.

When to Use:

• To read the message history of a legacy Chat-type view.

When NOT to Use:

• To read messages in a modern Chat channel — use clickup_get_chat_channel_messages (tools/chat_messages.py) instead.

Returns: Markdown (default) or JSON list of comments with id, author, date, and (truncated) text.

Pagination: Cursor-based (start/start_id), identical pattern to clickup_get_task_comments — see that tool's docstring for the full explanation. Omit both for the most recent 25 comments.

Examples: params = {"view_id": "105"}

Error Handling: 404 means the view id is wrong or is not a Chat-type view.

Edit a comment's text, (re)assign it, or toggle its resolved state.

Calls PUT /comment/{comment_id}. Works uniformly on task, List, Chat-view, and threaded-reply comments — they all share the same comment_id space.

When to Use:

• To fix a typo, add detail, reassign a comment's action item, or mark it resolved once addressed.

When NOT to Use:

• To remove a comment entirely — use clickup_delete_comment.

• To reply within a thread rather than editing — use clickup_create_threaded_comment.

Returns: A confirmation string naming the updated comment, or an Error ... string on failure.

Examples: params = {"comment_id": "446750", "comment_text": "Resolved — see PR #42.", "resolved": True}

Error Handling: 404 means the comment id is wrong; 403 can mean you don't own the comment and lack edit permission.

Permanently delete a comment.

Calls DELETE /comment/{comment_id}. Works uniformly on task, List, Chat-view, and threaded-reply comments.

When to Use:

• To remove a comment that was posted in error or is no longer relevant.

When NOT to Use:

• To just fix wording or mark it resolved — use clickup_update_comment instead of destroying history.

Returns: A confirmation string, or an Error ... string on failure.

Examples: params = {"comment_id": "446750"}

Error Handling: 404 means the comment id is wrong or was already deleted.

Reply inside an existing comment's thread.

Posts to POST /comment/{comment_id}/reply. Threaded replies keep a discussion nested under its parent comment instead of scattering related follow-ups as separate top-level task/list/Chat-view comments.

When to Use:

• To respond directly to a specific comment (task, List, or Chat-view) rather than starting a new top-level comment.

When NOT to Use:

• To start a new top-level comment — use clickup_create_task_comment / clickup_create_list_comment / clickup_create_chat_view_comment.

Returns: A confirmation string with the new reply's id, hist_id, and timestamp, or an Error ... string on failure.

Examples: params = {"comment_id": "446750", "comment_text": "Agreed, I'll update the estimate."}

Error Handling: 404 means the parent comment_id is wrong.

List the replies in a comment's thread.

Calls GET /comment/{comment_id}/reply. The parent comment itself is NOT included in the response — only its replies.

When to Use:

• To read the full discussion nested under a specific comment.

When NOT to Use:

• To read a task/list/Chat-view's top-level comments — use clickup_get_task_comments / clickup_get_list_comments / clickup_get_chat_view_comments.

Returns: Markdown (default) or JSON list of replies with id, author, date, and (truncated) text.

Pagination: Unlike the three top-level comment-listing tools, ClickUp does NOT expose start/start_id cursor pagination for replies — this endpoint returns the full thread in one call, so no cursor params are surfaced here.

Examples: params = {"comment_id": "446750"}

Error Handling: 404 means the parent comment_id is wrong.

List the Custom Fields accessible from a List.

Calls GET /list/{list_id}/field. This is the scope you almost always want before setting a value: it returns every field usable on the List's tasks — fields defined on the List plus those inherited from the parent Folder, Space, and Workspace. Each field object carries the id (a UUID you pass to clickup_set_custom_field_value), type, and type_config (for drop_down / labels fields, type_config.options[] holds the option UUIDs you set).

When to Use:

• To discover a field's id and its option UUIDs before calling clickup_set_custom_field_value on a task in this List.

When NOT to Use:

• For fields defined higher up only: prefer the narrowest scope that includes your task. Use clickup_get_folder_custom_fields, clickup_get_space_custom_fields, or clickup_get_team_custom_fields to inspect a specific level.

Returns: A markdown list of fields (name, type, id, and any options) or, with response_format="json", the raw field objects including full type_config.

Examples:

• params = {"list_id": "901100154842"}

• params = {"list_id": "901100154842", "include_applied_objects": true, "response_format": "json"}

Error Handling: 404 means the List id is wrong; 401/403 point to token or access issues.

List the Custom Fields available at a Folder scope.

Calls GET /folder/{folder_id}/field, returning fields defined on the Folder plus those inherited from the parent Space and Workspace.

When to Use:

• To audit which fields a Folder exposes to its Lists and tasks.

When NOT to Use:

• To find a field usable on a specific task — use clickup_get_list_custom_fields for the narrowest, task-applicable set.

Returns: A markdown list of fields (or raw JSON with response_format="json").

Examples:

• params = {"folder_id": "457"}

Error Handling: 404 means the Folder id is wrong; 401/403 point to token or access issues.

List the Custom Fields available at a Space scope.

Calls GET /space/{space_id}/field, returning fields defined on the Space plus those inherited from the Workspace.

When to Use:

• To audit which fields a Space exposes to its Folders, Lists, and tasks.

When NOT to Use:

• To find a field usable on a specific task — use clickup_get_list_custom_fields.

Returns: A markdown list of fields (or raw JSON with response_format="json").

Examples:

• params = {"space_id": "790"}

Error Handling: 404 means the Space id is wrong; 401/403 point to token or access issues.

List the Workspace-scoped Custom Fields.

Calls GET /team/{team_id}/field (ClickUp names the Workspace team_id), returning only fields defined at the top Workspace level.

When to Use:

• To inventory the organisation-wide Custom Fields shared across every Space.

When NOT to Use:

• To find a field usable on a specific task — use clickup_get_list_custom_fields, which also surfaces inherited fields.

Returns: A markdown list of fields (or raw JSON with response_format="json").

Examples:

• params = {"team_id": "9007200144"}

Error Handling: 404 means the Workspace id is wrong; 401/403 point to token or access issues.

Set a Custom Field's value on a task.

Calls POST /task/{task_id}/field/{field_id}. The request body is POLYMORPHIC — the shape of value is decided by the field's type, which you can read with clickup_get_list_custom_fields. Send the wrong shape and ClickUp answers 400. drop_down / labels take the option UUIDs found in the field's type_config.options[], not the display labels.

Value by field type:

Note: labels differ from tasks/people — labels take a plain array of UUIDs (the complete desired selection), NOT an {add, rem} object; {add, rem} is only for the tasks-relationship and people field types.

When to Use:

• To populate or overwrite a single Custom Field on one task after resolving its field_id (and any option UUIDs) via clickup_get_list_custom_fields.

When NOT to Use:

• To clear a field — use clickup_remove_custom_field_value instead of sending an empty value.

• To set many fields at once on create — pass the custom_fields array to the task create/update tools in the Tasks module instead.

Returns: A confirmation string (the endpoint returns an empty body on success).

Examples:

• text: params = {"task_id": "9hz", "field_id": "", "value": "In review"}

• number: params = {"task_id": "9hz", "field_id": "", "value": 42}

• date+time: params = {"task_id": "9hz", "field_id": "", "value": 1667367645000, "value_options": {"time": true}}

• drop_down: params = {"task_id": "9hz", "field_id": "", "value": "03efda77-c7a0-42d3-8afd-fd546353c2f5"}

• labels: params = {"task_id": "9hz", "field_id": "", "value": ["uuidA", "uuidB"]}

• tasks: params = {"task_id": "9hz", "field_id": "", "value": {"add": ["abcd1234"], "rem": []}}

• location: params = {"task_id": "9hz", "field_id": "", "value": {"location": {"lat": -28.016, "lng": 153.4}, "formatted_address": "Gold Coast QLD, Australia"}}

• custom id: params = {"task_id": "ABC-123", "field_id": "", "value": 42, "custom_task_ids": true, "team_id": "9007200144"}

Error Handling: 400 usually means the value shape does not match the field's type, or the field is not enabled for the task's custom task type; 404 means the task or field_id is wrong; if custom_task_ids=true you must also pass team_id.

Clear a Custom Field's value on a task.

Calls DELETE /task/{task_id}/field/{field_id}. This removes the value stored on the task only — it does NOT delete the field definition or any drop_down/labels options from the field's configuration.

When to Use:

• To empty a single field on a task (e.g. unset a drop_down or clear a date).

When NOT to Use:

• To change a value — use clickup_set_custom_field_value.

• To delete the field itself — that is a ClickApp/UI action, not this API.

Returns: A confirmation string (the endpoint returns an empty body on success).

Examples:

• params = {"task_id": "9hz", "field_id": ""}

• params = {"task_id": "ABC-123", "field_id": "", "custom_task_ids": true, "team_id": "9007200144"}

Error Handling: 404 means the task or field_id is wrong; if custom_task_ids=true you must also pass team_id.

List the Workspace's custom task types (a.k.a. custom items).

Calls GET /team/{team_id}/custom_item. Custom task types are the "task / milestone / bug / …" varieties a Workspace defines; their integer id is the custom_item_id used when creating tasks and is what a task-type-scoped Custom Field's applied_objects[].object_id points at. The default "Task" type is id 0 and is not returned by this endpoint.

When to Use:

• To resolve a custom task type name to its id before creating a typed task.

• To interpret applied_objects from the get-fields tools (include_applied_objects=true).

When NOT to Use:

• To read Custom Fields — use the get-fields tools above.

Returns: A markdown list of custom task types (id, name, plural, description) or, with response_format="json", the raw custom_item objects.

Examples:

• params = {"team_id": "9007200144"}

• params = {"team_id": "9007200144", "response_format": "json"}

Error Handling: 404 means the Workspace id is wrong; 401/403 point to token or access issues.

Search the Docs in a Workspace, optionally filtered by parent location.

Lists Docs across the Workspace and can narrow by creator, parent container, or archived/deleted state. Results are cursor-paginated.

When to Use:

• To find a Doc's id before reading (clickup_get_doc) or editing its pages.

• To enumerate every Doc under a Space/Folder/List (set parent_id + parent_type).

When NOT to Use:

• To read a specific Doc's content — use clickup_get_doc_pages instead.

• To create a Doc — use clickup_create_doc.

Returns: A list of Docs (name, id, parent, created date). When more results exist the response includes a next_cursor; pass it back as cursor to page forward.

Pagination: Cursor-based. Loop: call once, read next_cursor from the output, then call again with cursor=<next_cursor> until it is empty.

Examples:

• params = {"parent_id": "901300", "parent_type": "space"}

• params = {"cursor": "eyJ...", "limit": 100}

Error Handling: 401 → bad token; 404 → unknown Workspace id. Errors return an Error ... string.

Create a Doc, optionally placed directly in its final location.

Set parent_id + parent_type to create the Doc inside a Space, Folder, List, the Everything level, or the Workspace root in one call — no create-then-drag. The parent type maps to ClickUp's numeric enum: space→4, folder→5, list→6, everything→7, workspace→12. Omit both parent fields to create the Doc in the default (private) location.

When to Use:

• To start a new Doc where it belongs (e.g. a spec Doc inside a project List).

When NOT to Use:

• To add a page to an existing Doc — use clickup_create_page.

• To change an existing page's text — use clickup_edit_page.

Returns: A confirmation with the new Doc's name, id, and parent location.

Examples:

• params = {"name": "Q3 Spec", "parent_id": "901300", "parent_type": "list"}

• params = {"name": "Scratch", "create_page": false}

Error Handling: 400 → bad parent id/type pairing; 404 → parent not found. Errors return an Error ... string.

Fetch a single Doc's metadata (name, parent, timestamps).

When to Use:

• To confirm a Doc's parent location or creation details by id.

When NOT to Use:

• To read the Doc's text — use clickup_get_doc_pages.

• To list its page tree — use clickup_get_doc_page_listing.

Returns: The Doc's name, id, parent, workspace, creator, and created/updated times.

Examples:

• params = {"doc_id": "8cbq..."}

Error Handling: 404 → Doc not found. Errors return an Error ... string.

List a Doc's page tree (titles and ids only, nested — no content).

A lightweight outline of the Doc: the hierarchy of pages and subpages with their ids, without fetching any body text.

When to Use:

• To see a Doc's structure and grab a specific page id cheaply.

When NOT to Use:

• To read page content — use clickup_get_doc_pages or clickup_get_page.

Returns: An indented tree of page names and ids.

Examples:

• params = {"doc_id": "8cbq...", "max_page_depth": 2}

Error Handling: 404 → Doc not found. Errors return an Error ... string.

Fetch a Doc's pages with content (the full readable body of the Doc).

When to Use:

• To read everything a Doc contains in one call.

When NOT to Use:

• To read just one page — use clickup_get_page.

• To see structure without content — use clickup_get_doc_page_listing.

Returns: Each page's title, subtitle, and content (markdown by default). Very large Docs are truncated with a note.

Examples:

• params = {"doc_id": "8cbq...", "content_format": "text/plain"}

Error Handling: 404 → Doc not found. Errors return an Error ... string.

Add a page to an existing Doc (optionally nested under another page).

When to Use:

• To append a new section/page to a Doc you already created or found.

When NOT to Use:

• To create the Doc itself — use clickup_create_doc.

• To modify an existing page — use clickup_edit_page.

Returns: A confirmation with the new page's name and id.

Examples:

• params = {"doc_id": "8cbq...", "name": "Overview", "content": "# Hi"}

• params = {"doc_id": "8cbq...", "name": "Detail", "parent_page_id": "abc"}

Error Handling: 404 → Doc/parent page not found. Errors return an Error ... string.

Fetch one page of a Doc, including its content.

When to Use:

• To read or re-read a single page by id (e.g. before editing it).

When NOT to Use:

• To read every page — use clickup_get_doc_pages.

Returns: The page's title, subtitle, and content (markdown by default).

Examples:

• params = {"doc_id": "8cbq...", "page_id": "abc"}

Error Handling: 404 → page not found. Errors return an Error ... string.

Update a Doc page's title, subtitle, and/or content.

content_edit_mode controls how content is applied: replace (default) overwrites the page body, append adds to the end, prepend adds to the start — handy for logging into an existing page without a read-modify-write.

When to Use:

• To rename a page, change its subtitle, or overwrite/append/prepend content.

When NOT to Use:

• To create a new page — use clickup_create_page.

Returns: A confirmation naming the page, Doc, and edit mode used.

Examples:

• params = {"doc_id": "d", "page_id": "p", "content": "new body"}

• params = {"doc_id": "d", "page_id": "p", "content": "- log", "content_edit_mode": "append"}

Error Handling: 404 → page not found. Errors return an Error ... string.

Create a Folder inside a Space.

Calls POST /space/{space_id}/folder. Folders group Lists within a Space; a Folder created here starts empty (use the Lists tools to add Lists to it once t3-lists lands). ClickUp's Create Folder endpoint only accepts name in the body — to enable Folder-level statuses, call clickup_update_folder with override_statuses=true after creating.

When to Use:

• To organize related Lists under one container inside a Space.

When NOT to Use:

• To create a List that doesn't need a Folder (use the folderless-list tool in tools/lists.py once available).

• To duplicate an existing structure — use clickup_create_folder_from_template.

Returns: A confirmation string with the new Folder's name and id, or an Error ... string describing the failure.

Examples: params = {"space_id": "90130912", "name": "Q3 Launches"}

Error Handling: 404 means space_id doesn't exist or isn't accessible; 400 means the name is missing/invalid.

List the Folders in a Space.

Calls GET /space/{space_id}/folder. Returns each Folder's task/list counts and its override_statuses flag; use clickup_get_folder for the full status list and nested Lists of one Folder.

When to Use:

• To discover what Folders exist in a Space before creating or updating one.

• To check which Folders already override the Space's statuses.

When NOT to Use:

• To fetch one Folder's full detail — use clickup_get_folder.

• To list Lists that live directly in the Space (no Folder) — use the folderless-lists tool in tools/lists.py once available.

Returns: A markdown or JSON list of Folders, or an Error ... string.

Pagination: ClickUp returns the full Folder array in one response; this tool slices it client-side via limit/offset for context-window safety.

Examples: params = {"space_id": "90130912", "archived": False, "limit": 20, "offset": 0}

Error Handling: 404 means space_id doesn't exist or isn't accessible.

Fetch one Folder, including its Lists and status workflow.

Calls GET /folder/{folder_id}.

When to Use:

• To inspect a specific Folder's statuses, Lists, and override_statuses flag before deciding whether to update it.

When NOT to Use:

• To browse every Folder in a Space — use clickup_get_folders.

Returns: A markdown detail block or JSON object, or an Error ... string.

Examples: params = {"folder_id": "456", "response_format": "markdown"}

Error Handling: 404 means folder_id doesn't exist or isn't accessible.

Rename a Folder and/or toggle its status-override setting.

Calls PUT /folder/{folder_id}. Setting override_statuses=True moves this Folder (and Lists inside it, unless a List overrides further) from inheriting the Space's status workflow to a Folder-level custom one; this endpoint only flips the flag — inspect the resulting statuses with clickup_get_folder. Note: the status definitions themselves cannot be set through the public API (same limitation as Space statuses, verified live for Spaces) — define custom statuses in the ClickUp UI.

When to Use:

• To rename a Folder.

• To turn Folder-level status overrides on or off.

When NOT to Use:

• To change a single List's statuses — that is scoped to the List/Space tools, not this endpoint.

Returns: A confirmation string with the Folder's new name, or an Error ... string.

Examples: params = {"folder_id": "456", "name": "Q3 Launches (Renamed)", "override_statuses": True}

Error Handling: 404 means folder_id doesn't exist or isn't accessible; 400 means the name is missing/invalid.

Permanently delete a Folder and every List/Task inside it.

Calls DELETE /folder/{folder_id}. This cannot be undone via the API.

When to Use:

• To remove a Folder (and everything inside it) that is no longer needed.

When NOT to Use:

• To archive instead of destroy — use clickup_update_folder semantics via the Space's archive controls, not this tool, if you may need the data again.

Returns: A confirmation string, or an Error ... string.

Examples: params = {"folder_id": "456"}

Error Handling: 404 means folder_id doesn't exist or was already deleted.

Create a new Folder by replaying a Folder template.

Calls POST /space/{space_id}/folder_template/{template_id}. Fetch available template ids (always t--prefixed) with clickup_get_folder_templates first.

When to Use:

• To stamp out a repeatable Folder structure (Lists, statuses, views) instead of rebuilding it by hand with clickup_create_folder.

When NOT to Use:

• To create a plain empty Folder — use clickup_create_folder.

Returns: A confirmation string with the new Folder's id, or an Error ... string. If options.return_immediately is left at ClickUp's default, the template content may still be populating asynchronously — re-check with clickup_get_folder.

Examples: params = { "space_id": "90130912", "template_id": "t-7162342", "name": "Q4 Launch (from template)", "options": {"include_views": True, "old_due_date": True}, }

Error Handling: 404 means space_id or template_id doesn't exist; 400 means the name is missing/invalid.

List the Folder templates available in a Workspace.

Calls GET /team/{team_id}/folder_template. Template ids are t--prefixed and feed directly into clickup_create_folder_from_template.

When to Use:

• To discover which Folder template id to pass to clickup_create_folder_from_template.

When NOT to Use:

• To list actual Folders in a Space — use clickup_get_folders.

Returns: A markdown or JSON list of templates, or an Error ... string.

Pagination: ClickUp returns the full template array in one response; this tool slices it client-side via limit/offset for context-window safety.

Examples: params = {"team_id": "90130912", "limit": 20, "offset": 0}

Error Handling: 404 means team_id doesn't exist or isn't accessible.

Create a new Goal in a Workspace.

Goals group one or more Key Results (see clickup_create_key_result) that track progress toward a target date.

When to Use:

• Starting a new OKR / objective that will hold Key Results.

When NOT to Use:

• To add a Key Result to an existing Goal — use clickup_create_key_result.

• To change an existing Goal's fields — use clickup_update_goal.

Returns: A confirmation string with the new Goal's id and current fields.

Examples: params = {"name": "Grow MRR", "due_date": 1735689600000, "color": "#32a852"}

Error Handling: 404 usually means the team_id is wrong; 401 means the token is missing/invalid.

List the Goals in a Workspace, including any Goal Folders.

When to Use:

• Browsing all OKRs for a Workspace, or checking which are still open.

When NOT to Use:

• Fetching one Goal's full detail (including Key Results) — use clickup_get_goal.

Returns: Markdown (default) or JSON listing every Goal, including Goals nested inside Goal Folders. Each Goal's Key Results are summarized inline.

Pagination: This endpoint does not page server-side; display is capped at MAX_DISPLAY_GOALS (50) with a truncation note if exceeded. Use include_completed=false (default) to shrink the result set.

Examples: params = {"include_completed": True, "response_format": "json"}

Error Handling: 404 usually means the team_id is wrong; 401 means the token is missing/invalid.

Get a single Goal's full detail, including its Key Results.

When to Use:

• Inspecting one Goal's progress and Key Results before editing it.

When NOT to Use:

• Listing many Goals at once — use clickup_get_goals.

Returns: Markdown (default) or JSON with the Goal's fields and every Key Result.

Examples: params = {"goal_id": "e53a033c-1146-4b58-b498-7ec39b5661c2"}

Error Handling: 404 means the goal_id does not exist or was already deleted.

Update an existing Goal's name, due date, description, owners, or color.

Owners are changed incrementally via add_owners/rem_owners rather than a full replacement list.

When to Use:

• Renaming a Goal, pushing its due date, or changing who owns it.

When NOT to Use:

• Editing a Key Result's progress — use clickup_edit_key_result.

Returns: A confirmation string with the Goal's fields after the update.

Examples: params = {"goal_id": "e53a033c-1146-4b58-b498-7ec39b5661c2", "add_owners": [123]}

Error Handling: 404 means the goal_id does not exist; 400 means a field value was rejected (e.g. malformed color or due_date).

Permanently delete a Goal and all of its Key Results.

When to Use:

• Removing an OKR that is no longer tracked.

When NOT to Use:

• Removing a single Key Result but keeping the Goal — use clickup_delete_key_result.

Returns: A confirmation string on success.

Error Handling: 404 means the goal_id does not exist or was already deleted.

Add a Key Result (Target) to a Goal.

type determines how progress is tracked — see the module docstring. automatic requires task_ids and/or list_ids since progress is derived from those tasks/lists rather than manual steps_current edits.

When to Use:

• Breaking a Goal down into one or more measurable targets.

When NOT to Use:

• Updating an existing Key Result's progress — use clickup_edit_key_result.

Returns: A confirmation string with the new Key Result's id and fields.

Examples: params = { "goal_id": "e53a033c-1146-4b58-b498-7ec39b5661c2", "name": "Close 10 deals", "type": "number", "steps_start": 0, "steps_end": 10, "unit": "deals", "owners": [123], }

Error Handling: 404 means the goal_id does not exist; 400 means the type-specific fields (steps_start/steps_end/task_ids/list_ids) are inconsistent for the chosen type.

Update a Key Result's progress, note, name, owners, or task/list links.

steps_current moves progress along the range set by create_key_result (steps_start→steps_end); note attaches a short progress comment alongside the update.

When to Use:

• Logging progress on a manual (number/currency/boolean/percentage) Key Result.

When NOT to Use:

• Creating a brand-new Key Result — use clickup_create_key_result.

• Editing the parent Goal's own fields — use clickup_update_goal.

Returns: A confirmation string with the Key Result's fields after the update.

Examples: params = { "key_result_id": "8480-49bc-8c57-e569747efe93", "steps_current": 4, "note": "Closed another deal this week.", }

Error Handling: 404 means the key_result_id does not exist; 400 means steps_current is outside the type's valid range.

Permanently delete a Key Result (Target) from its Goal.

When to Use:

• Removing a target that no longer applies, while keeping the parent Goal.

When NOT to Use:

• Deleting the whole Goal (and all its Key Results) — use clickup_delete_goal.

Returns: A confirmation string on success.

Error Handling: 404 means the key_result_id does not exist or was already deleted.

Invite an external guest to a Workspace by email.

Guests are lighter-weight than full Workspace members: they only see the tasks/lists/folders explicitly shared with them via clickup_add_guest_to_task, clickup_add_guest_to_list, or clickup_add_guest_to_folder. Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Onboarding an external collaborator (client, contractor) who should only see specific items rather than the whole Workspace.

When NOT to Use:

• Adding a full internal team member — use clickup_invite_user_to_workspace instead (users see everything they're a member of by default).

Returns: A confirmation string with the invited guest's id and email, or an Error ... string on failure.

Examples: params = {"team_id": "123", "email": "contractor@example.com", "can_create_views": False}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 400 usually means the email is malformed or already a member/guest.

Update an existing guest's permission flags or custom role on a Workspace.

Only the fields you pass are sent; omitted fields are left unchanged on ClickUp's side. Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Adjusting what a guest can see (time tracking, estimates) or do (create views, edit tags) without removing and re-inviting them.

When NOT to Use:

• Changing what items a guest can access — use the per-task/list/folder clickup_add_guest_to_* / clickup_remove_guest_from_* tools for that.

Returns: A confirmation string listing the fields that were updated, or an Error ... string on failure.

Examples: params = {"team_id": "123", "guest_id": "456", "can_see_time_spent": False}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the guest id does not exist on this Workspace.

Look up a guest's permission flags and what has been shared with them.

Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Auditing what a guest can currently see/do before editing or removing them.

When NOT to Use:

• Looking up full Workspace members — use clickup_get_user instead.

Returns: Markdown summary (id, username, email, permission flags, and a count of shared tasks/lists/folders) or the raw JSON payload when response_format="json".

Examples: params = {"team_id": "123", "guest_id": "456"}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the guest id does not exist on this Workspace.

Revoke a guest's access to an entire Workspace.

This removes the guest from every task/list/folder they were shared on — it is not scoped to a single item. Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Offboarding an external collaborator entirely.

When NOT to Use:

• Revoking access to just one task/list/folder — use clickup_remove_guest_from_task / _list / _folder instead.

Returns: A confirmation string, or an Error ... string on failure.

Examples: params = {"team_id": "123", "guest_id": "456"}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the guest id does not exist on this Workspace.

Share a single task with an existing guest at a given permission level.

The guest must already exist on the Workspace (see clickup_invite_guest_to_workspace). Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Giving a guest visibility into exactly one task without exposing the rest of the list/folder/space.

When NOT to Use:

• Sharing an entire list or folder — use clickup_add_guest_to_list / clickup_add_guest_to_folder instead.

Returns: A confirmation string with the task id, guest id, and permission level, or an Error ... string on failure.

Examples: params = {"task_id": "abc123", "guest_id": "456", "permission_level": "edit"} params = {"task_id": "CUSTOM-1", "guest_id": "456", "permission_level": "read", "custom_task_ids": True, "team_id": "123"}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the task or guest id does not exist.

Revoke a guest's access to a single task.

Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Un-sharing one task from a guest while leaving their other shared items intact.

When NOT to Use:

• Removing the guest from the whole Workspace — use clickup_remove_guest_from_workspace.

Returns: A confirmation string, or an Error ... string on failure.

Examples: params = {"task_id": "abc123", "guest_id": "456"}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the task or guest id does not exist.

Share a List with an existing guest at a given permission level.

The guest gains visibility into every task in the List. Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Giving a guest access to a whole List of tasks at once.

When NOT to Use:

• Sharing just one task — use clickup_add_guest_to_task. Sharing an entire Folder — use clickup_add_guest_to_folder.

Returns: A confirmation string with the list id, guest id, and permission level, or an Error ... string on failure.

Examples: params = {"list_id": "789", "guest_id": "456", "permission_level": "comment"}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the list or guest id does not exist.

Revoke a guest's access to a List.

Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Un-sharing a whole List from a guest while leaving their other shared items intact.

When NOT to Use:

• Removing just one task — use clickup_remove_guest_from_task.

Returns: A confirmation string, or an Error ... string on failure.

Examples: params = {"list_id": "789", "guest_id": "456"}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the list or guest id does not exist.

Share a Folder with an existing guest at a given permission level.

The guest gains visibility into every List and task in the Folder. Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Giving a guest access to an entire Folder (all its Lists and tasks) at once.

When NOT to Use:

• Sharing just one List — use clickup_add_guest_to_list. Sharing just one task — use clickup_add_guest_to_task.

Returns: A confirmation string with the folder id, guest id, and permission level, or an Error ... string on failure.

Examples: params = {"folder_id": "321", "guest_id": "456", "permission_level": "create"}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the folder or guest id does not exist.

Revoke a guest's access to a Folder.

Note: Enterprise plan only — returns 403 on other plans.

When to Use:

• Un-sharing a whole Folder from a guest while leaving their other shared items intact.

When NOT to Use:

• Removing just one List or task — use clickup_remove_guest_from_list / clickup_remove_guest_from_task.

Returns: A confirmation string, or an Error ... string on failure.

Examples: params = {"folder_id": "321", "guest_id": "456"}

Error Handling: 403 means the Workspace is not on the Enterprise plan. 404 means the folder or guest id does not exist.

Verify connectivity and authentication against the ClickUp API.

Calls GET /user (the authorized-user endpoint) with the configured CLICKUP_API_TOKEN and reports who the token belongs to.

When to Use:

• As the first call after configuring the server, to confirm the token works.

• To debug 401/403 responses from other tools.

When NOT to Use:

• To look up other people in the Workspace (use the members tools instead).

Returns: A one-line OK summary with the authorized user's name, id, and email, or an Error ... string describing the failure.

Error Handling: 401 means the token is missing/invalid; connection errors point to network or CLICKUP_API_URL issues.

Create a new List inside a Folder.

Lists inside a Folder normally inherit the Folder's statuses unless the Folder itself overrides Space statuses. Use clickup_create_folderless_list instead when the target Space is not organized into Folders.

When to Use:

• Setting up a new List for a team/project that already has a Folder.

• Programmatically scaffolding a Workspace structure Folder-by-Folder.

When NOT to Use:

• The target Space has no Folders — use clickup_create_folderless_list.

• Copying an established List's tasks/views/custom fields — use clickup_create_list_from_template_in_folder instead.

Returns: A confirmation string with the new List's name and id, or an Error ... string.

Examples: params = {"folder_id": "12345", "name": "Sprint 24", "priority": 2} params = {"folder_id": "12345", "name": "Backlog", "markdown_content": "Unscheduled work"}

Error Handling: 404 means folder_id does not exist or is not accessible; 400 usually means name is missing or a duplicate is not allowed under this Folder.

Create a new List directly inside a Space, with no parent Folder.

Use this for Spaces that are not organized into Folders. Use clickup_create_list instead when the List belongs under an existing Folder.

When to Use:

• The Space has no Folder structure and Lists sit directly under it.

When NOT to Use:

• The Space is organized into Folders — use clickup_create_list so the new List lands in the right Folder.

• Copying an established List's tasks/views/custom fields — use clickup_create_list_from_template_in_space instead.

Returns: A confirmation string with the new List's name and id, or an Error ... string.

Examples: params = {"space_id": "67890", "name": "General"} params = {"space_id": "67890", "name": "Intake", "status": "green"}

Error Handling: 404 means space_id does not exist or is not accessible; 400 usually means name is missing or a duplicate is not allowed under this Space.

List the Lists that belong to a Folder.

When to Use:

• Enumerating every List inside a specific Folder.

When NOT to Use:

• The Space has no Folders — use clickup_get_folderless_lists.

• You already have the list_id and need full detail — use clickup_get_list.

Returns: Markdown (default) or JSON per response_format.

Pagination: ClickUp returns every List belonging to the Folder in one response; this tool then windows the result with limit/offset to keep responses small, reporting has_more and the next offset when applicable.

Examples: params = {"folder_id": "12345"} params = {"folder_id": "12345", "archived": True, "limit": 50}

Error Handling: 404 means folder_id does not exist or is not accessible.

List the Lists that live directly inside a Space (no Folder).

When to Use:

• Enumerating Lists in a Space that is not organized into Folders.

When NOT to Use:

• The Space uses Folders — use clickup_get_lists per Folder instead.

• You already have the list_id and need full detail — use clickup_get_list.

Returns: Markdown (default) or JSON per response_format.

Pagination: ClickUp returns every folderless List in the Space in one response; this tool then windows the result with limit/offset, reporting has_more and the next offset when applicable.

Examples: params = {"space_id": "67890"} params = {"space_id": "67890", "archived": True}

Error Handling: 404 means space_id does not exist or is not accessible.

Fetch full detail for a single List by id.

When to Use:

• You already know list_id and need its description, dates, color, priority, assignee, and parent Folder/Space.

When NOT to Use:

• Enumerating many Lists at once — use clickup_get_lists or clickup_get_folderless_lists.

Returns: Markdown (default) or JSON per response_format.

Examples: params = {"list_id": "901300123456"} params = {"list_id": "901300123456", "response_format": "json"}

Error Handling: 404 means list_id does not exist or is not accessible.

Update a List's name, description, dates, priority, assignee, or color.

Only fields you explicitly set are sent — omitted fields are left unchanged by ClickUp. Supports markdown_content for a formatted description (in place of plain content), and unset_status to clear the List's color designation entirely.

When to Use:

• Renaming a List, changing its description, due date, priority, or owner, or changing/clearing its color.

When NOT to Use:

• Changing a Task's own status — that is a Task Status, unrelated to a List's color-only status field.

Returns: A confirmation string with the updated List's name and id, or an Error ... string.

Examples: params = {"list_id": "901300123456", "name": "Sprint 25"} params = {"list_id": "901300123456", "markdown_content": "## Updated scope", "priority": 1} params = {"list_id": "901300123456", "unset_status": True}

Error Handling: 404 means list_id does not exist; 400 usually means an invalid field value (e.g. an out-of-range priority).

Permanently delete a List from the Workspace.

This removes the List and all of its Tasks. There is no undo via the API — confirm with the caller before invoking this on production data.

When to Use:

• Removing a List that is no longer needed.

When NOT to Use:

• Temporarily hiding a List — archive it via clickup_update_list instead of deleting (archiving is not exposed as a dedicated flag on this endpoint set; use the ClickUp UI or the List's archived state through the Folder/Space update tools if you need reversible hiding).

Returns: A confirmation string, or an Error ... string.

Examples: params = {"list_id": "901300123456"}

Error Handling: 404 means list_id does not exist or was already deleted.

Add an existing Task's membership to an additional List.

Requires the Tasks in Multiple Lists ClickApp to be enabled for the Workspace; without it ClickUp returns 403. This does not move the Task — it stays in its original (home) List and additionally appears in this one.

When to Use:

• A Task needs to appear in a second, cross-cutting List (e.g. a shared "This Sprint" List) without duplicating it.

When NOT to Use:

• Moving a Task to a different List entirely (removing it from its current List) — use the tasks module's move-task tool instead.

• The Tasks in Multiple Lists ClickApp is disabled for the Workspace — enable it first (ClickUp → Settings → ClickApps).

Returns: A confirmation string, or an Error ... string.

Examples: params = {"list_id": "901300123456", "task_id": "abc123"}

Error Handling: 403 means the Tasks in Multiple Lists ClickApp is not enabled for this Workspace. 404 means list_id or task_id does not exist.

Remove a Task's membership from an additional (non-home) List.

Requires the Tasks in Multiple Lists ClickApp to be enabled; without it ClickUp returns 403. You cannot remove a Task from its primary (home) List this way — only from additional Lists it was added to via clickup_add_task_to_list.

When to Use:

• Undoing a clickup_add_task_to_list call, or cleaning up a Task that no longer needs to appear in a secondary List.

When NOT to Use:

• Removing a Task entirely from its home List — that requires deleting the Task (see the tasks module) rather than this membership removal.

Returns: A confirmation string, or an Error ... string.

Examples: params = {"list_id": "901300123456", "task_id": "abc123"}

Error Handling: 403 means the Tasks in Multiple Lists ClickApp is not enabled, or you tried to remove the Task from its home List. 404 means list_id or task_id does not exist.

Create a new List inside a Folder by instantiating a List template.

Use clickup_get_list_templates to discover available template_id values (they carry a t- prefix, e.g. t-15363293). With return_immediately=True (the default) the response's List id may represent a List that is still being populated in the background for large templates — poll with clickup_get_list if you need to confirm completion.

When to Use:

• Scaffolding a new List that should start with a known set of statuses, views, or starter Tasks defined in a template.

When NOT to Use:

• The Space has no Folders — use clickup_create_list_from_template_in_space instead.

• No template fits — use clickup_create_list for a blank List.

Returns: A confirmation string with the new List's id, or an Error ... string.

Examples: params = {"folder_id": "12345", "template_id": "t-15363293", "name": "Sprint 24"} params = {"folder_id": "12345", "template_id": "t-15363293", "name": "Sprint 24", "return_immediately": False}

Error Handling: 400 means name is missing or already taken; 404 means the template, folder, or space was not found.

Create a new folderless List inside a Space by instantiating a template.

Use clickup_get_list_templates to discover available template_id values (they carry a t- prefix, e.g. t-15363293). With return_immediately=True (the default) the response's List id may represent a List that is still being populated in the background for large templates — poll with clickup_get_list if you need to confirm completion.

When to Use:

• Scaffolding a new folderless List that should start with a known set of statuses, views, or starter Tasks defined in a template.

When NOT to Use:

• The target Space uses Folders — use clickup_create_list_from_template_in_folder instead.

• No template fits — use clickup_create_folderless_list for a blank List.

Returns: A confirmation string with the new List's id, or an Error ... string.

Examples: params = {"space_id": "67890", "template_id": "t-15363293", "name": "General"}

Error Handling: 400 means name is missing or already taken; 404 means the template or space was not found.

List available List templates for a Workspace.

The t- prefixed id field returned here feeds the template_id parameter of clickup_create_list_from_template_in_folder and clickup_create_list_from_template_in_space.

When to Use:

• Discovering which List templates exist before instantiating one.

When NOT to Use:

• You already know the template_id — go straight to clickup_create_list_from_template_in_folder/_in_space.

Returns: Markdown (default) or JSON per response_format.

Pagination: ClickUp returns every template in one response; this tool then windows the result with limit/offset.

Examples: params = {} params = {"team_id": "90130012345", "limit": 50}

Error Handling: Raises a configuration error if team_id is omitted and CLICKUP_TEAM_ID is not set; 401/403 indicate a token or plan issue.

List the Workspace members with direct access to a List.

Calls GET /list/{list_id}/member. The response only includes members granted access directly on this List — it excludes people who can see the List because they belong to a User Group (group_id), or because they inherited access from the parent Folder, Space, or Workspace (team_id).

When to Use:

• To check who has explicit access to a specific List before assigning tasks or sharing sensitive content.

• To debug "why can't user X see this List" — if they're missing here, check Folder/Space sharing or User Group membership instead.

When NOT to Use:

• To find who has explicit access to one Task, use clickup_get_task_members.

• To manage User Group (ClickUp API name: "Team") membership, use clickup_get_user_groups / clickup_update_user_group.

Returns: A markdown (or JSON) list of members with id, username, and email.

Examples: params = {"list_id": "901300123456"} params = {"list_id": "901300123456", "response_format": "json"}

Error Handling: 404 means the List id doesn't exist or isn't visible to this token; 401 means CLICKUP_API_TOKEN is missing or invalid.

List the Workspace members with direct access to a Task.

Calls GET /task/{task_id}/member. The response only includes members granted access directly on this Task — it excludes people who can see it via a User Group (group_id) or inherited access from the List, Folder, Space, or Workspace (team_id).

When to Use:

• To check who can see a specific Task before sharing sensitive detail in a comment or attachment.

When NOT to Use:

• To find who has direct access to the whole List, use clickup_get_list_members.

• To find who is assigned to the Task (a different concept from who can see it), use the task-detail tools in the tasks module.

Returns: A markdown (or JSON) list of members with id, username, and email.

Examples: params = {"task_id": "9hz"} params = {"task_id": "DEV-123", "custom_task_ids": true, "team_id": "123456"}

Error Handling: 404 means the Task id doesn't exist or isn't visible to this token; 400 if custom_task_ids=True but team_id is missing.

Create a User Group (ClickUp's endpoint calls this a "Team") in a Workspace.

Calls POST /team/{team_id}/group. Despite the path living under /team/..., team_id here is the Workspace id — the resource created is a User Group, addressed afterwards by its own group_id (a UUID, e.g. "4bfdfcec-6f4f-40a7-b0d6-22660d51870d"). Never confuse the two: team_id = Workspace, group_id = User Group.

When to Use:

• To create a reusable named set of members (e.g. "QA", "Product") that can be @mentioned or assigned as a unit across Spaces/Folders/Lists.

When NOT to Use:

• To add/remove members on an existing group, use clickup_update_user_group instead of deleting and recreating it.

Returns: A confirmation string with the new group's group_id, name, and member count.

Examples: params = {"team_id": "123456", "name": "Product Managers", "members": [183, 812]}

Error Handling: 403 if the plan doesn't support User Groups or the token lacks permission; 400 if members contains invalid user ids. Note: adding a view-only guest to a group can convert them to a paid guest (billing impact) — ClickUp's own docs warn about this.

List the User Groups in a Workspace (ClickUp's endpoint slug: "getteams1").

Calls GET /group?team_id=.... NB the naming trap: the underlying ClickUp endpoint is historically named "Teams", but the resource returned is a User Group (group_id), not the Workspace itself (team_id) — pass the Workspace id via team_id and optionally narrow to specific groups via group_ids.

When to Use:

• To look up a group's group_id before calling clickup_update_user_group / clickup_delete_user_group.

• To audit which User Groups exist in a Workspace and who is in them.

When NOT to Use:

• To list plain (ungrouped) Workspace members, use a Workspace-members tool in another module — this tool only returns User Groups.

Returns: A markdown (or JSON) list of groups with group_id, name, handle, and member count.

Examples: params = {"team_id": "123456"} params = {"team_id": "123456", "group_ids": ["4bfdfcec-6f4f-40a7-b0d6-22660d51870d"]}

Error Handling: 400/404 if team_id is missing or invalid.

Rename a User Group and/or add/remove its members.

Calls PUT /group/{group_id} (ClickUp's endpoint slug is updateteam, but group_id here addresses a User Group, never a Workspace — do not pass a team_id in this field). Member changes use ClickUp's {"add": [...], "rem": [...]} shape nested under members; name and handle are replaced wholesale when provided.

When to Use:

• To rename a group, change its @mention handle, or add/remove members without deleting and recreating the group.

When NOT to Use:

• To create a brand-new group, use clickup_create_user_group.

• To remove the group entirely, use clickup_delete_user_group.

Returns: A confirmation string with the updated group's name, group_id, and resulting member count.

Examples: params = {"group_id": "4bfdfcec-6f4f-40a7-b0d6-22660d51870d", "name": "QA Team"} params = { "group_id": "4bfdfcec-6f4f-40a7-b0d6-22660d51870d", "add_member_ids": [123456], "remove_member_ids": [159753], }

Error Handling: 404 if group_id doesn't exist; 403 if the token lacks permission. Note: adding a view-only guest to a group can convert them to a paid guest (billing impact) — ClickUp's own docs warn about this.

Permanently delete a User Group from a Workspace.

Calls DELETE /group/{group_id} (ClickUp's endpoint slug is deleteteam, but this deletes a User Group, not the Workspace itself — group_id is never a team_id). Deleting the group does not delete the member accounts; members keep whatever direct or inherited access they already had outside the group.

When to Use:

• To remove a stale or duplicate User Group.

When NOT to Use:

• To remove a single member while keeping the group, use clickup_update_user_group with remove_member_ids instead.

Returns: A confirmation string once the group is deleted.

Examples: params = {"group_id": "4bfdfcec-6f4f-40a7-b0d6-22660d51870d"}

Error Handling: 404 if group_id doesn't exist (it may already be deleted); 403 if the token lacks permission.

List the Custom Roles configured for a Workspace.

Calls GET /team/{team_id}/customroles (team_id = Workspace id; this endpoint has no relation to User Groups/group_id). Custom Roles let a Workspace define named permission tiers layered on top of ClickUp's base roles (owner/admin/member/guest); each role's inherited_role shows which base role it extends.

Note: Custom Roles are an Enterprise plan feature — this endpoint returns 403 on other plans.

When to Use:

• To look up which Custom Role(s) exist, and who holds them, before assigning one to a user elsewhere.

When NOT to Use:

• To list User Groups (an unrelated, non-permission concept), use clickup_get_user_groups.

Returns: A markdown (or JSON) list of roles with id, name, the base role they extend, and (when include_members=True) member count.

Examples: params = {"team_id": "123456"} params = {"team_id": "123456", "include_members": false}

Error Handling: 403 on non-Enterprise plans; 404 if team_id is invalid.

List the Tasks, Lists, and Folders individually shared with the caller.

Calls GET /team/{team_id}/shared (team_id = Workspace id). This surfaces items shared directly with the authenticated user/token that they would not otherwise see via normal Space/Folder/List membership — distinct from User Group (group_id) membership, which grants access through a named group rather than a one-off share.

When to Use:

• To audit what has been individually shared with the current token's user, outside their normal Workspace hierarchy access.

When NOT to Use:

• To see who has access to a specific List/Task (the inverse direction — "who can see this" rather than "what's shared with me"), use clickup_get_list_members / clickup_get_task_members.

Returns: A markdown (or JSON) summary grouped into Tasks / Lists / Folders.

Examples: params = {"team_id": "123456"}

Error Handling: 404/401 if team_id is invalid or the token can't access the Workspace.