wecom-get-todo-list

WeCom todo list query skill

wecom_mcp is an MCP tool; all operations are completed by calling this tool.

⚠️ Prerequisite: Before the first call to wecom_mcp , you must follow the wecom-preflight skill to perform the prerequisite check and ensure the tool has been added to the whitelist.

Through the wecom_mcp tool, query the WeCom todo list, supporting time filtering and pagination.

Behavior strategy

After querying the list, you must query details: This API only returns summary information such as todo IDs and statuses, and does not include the actual todo content and assignee. For users, a todo list without content is useless—what they want to know is "what to do", not a string of IDs. Therefore, every time you call get_todo_list and get the result, you must immediately use the returned todo_id list to call wecom-get-todo-detail to obtain complete details (content, assignee, etc.), and then display them to the user. This is not an optional step, but a necessary part of fulfilling the user's request.

When pagination is not fully retrieved, you must remind the user: The API is paginated, and it is not required to retrieve all data at once. But if in the response has_more is true, it means there are still more todos not returned—at this time, while displaying the current results, you must clearly tell the user "there are more todos not displayed. Do you need to continue viewing?" The user may not know there is more data afterward. If you do not say so, they will think what they see is all, which may cause important todos to be missed. This is an easily overlooked point with serious consequences, so please be sure to follow it.

Retry strategy: When encountering "returned HTTP error" or "HTTP request failed", actively retry, up to three times.

How to call

Use the wecom_mcp tool to call wecom_mcp call todo get_todo_list '<json格式的入参>'

Parameter descriptions

Parameter	Type	Required	Description
`create_begin_time`	string	❌	Creation start time, format:`YYYY-MM-DD HH:mm:ss`
`create_end_time`	string	❌	Creation end time, format:`YYYY-MM-DD HH:mm:ss`
`remind_begin_time`	string	❌	Reminder start time, format:`YYYY-MM-DD HH:mm:ss`
`remind_end_time`	string	❌	Reminder end time, format:`YYYY-MM-DD HH:mm:ss`
`limit`	number	❌	Maximum return count, default 10, maximum 20
`cursor`	string	❌	Pagination cursor, not passed on the first request, passed subsequently from the previous response's `next_cursor`

Return format

{
    "errcode": 0,
    "errmsg": "ok",
    "index_list": [
        {
            "todo_id": "TODO_ID",
            "todo_status": 1,
            "user_status": 1,
            "creator_id": "CREATOR_ID",
            "remind_time": "2025-06-01 09:00:00",
            "create_time": "2025-01-15 10:30:00",
            "update_time": "2025-01-16 14:20:00"
        }
    ],
    "next_cursor": "NEXT_CURSOR",
    "has_more": false
}

Returned field descriptions

Field	Type	Description
`index_list`	array	Todo list
`index_list[].todo_id`	string	Todo unique ID
`index_list[].todo_status`	number	Todo status:`0`-Completed,`1`-In progress,`2`-Deleted
`index_list[].user_status`	number	User status:`0`-Rejected,`1`-Accepted,`2`-Completed
`index_list[].creator_id`	string	Creator ID
`index_list[].remind_time`	string	Reminder time
`index_list[].create_time`	string	Creation time
`index_list[].update_time`	string	Update time
`next_cursor`	string	Next page cursor
`has_more`	boolean	Are there any more records?

The list returns todo summary information (excluding content and assignee). After getting the list, you must call wecom-get-todo-detail to get the full details before displaying them to the user.

Typical workflows

View the todo list (standard two-step process)

User asks: "Show me my recent todos" / "What todo items do I have?" / "How many things do I still need to do?"

Step 1: Get the todo list (only IDs and status, no content). Use the wecom_mcp tool to call wecom_mcp call todo get_todo_list '{}'
Step 2 (skipping is prohibited!): Use the returned todo_id list to call wecom-get-todo-detail to get the full details. Use the wecom_mcp tool to call wecom_mcp call todo get_todo_detail '{"todo_id_list": ["返回的TODO_ID_1", "返回的TODO_ID_2"]}'

Both steps are indispensable—only after getting the details can you show meaningful todo content to the user.

Step 3 (conditional execution): Check the has_more field returned in step 1. If it is true, when displaying the results you must remind the user: "The above are some of the todos; there are more todos not shown. Do you want me to continue viewing them?"—without this reminder, the user will think this is all of them.

Query by time range

User asks: "What todos were created this month?"

Use the wecom_mcp tool to call wecom_mcp call todo get_todo_list '{"create_begin_time": "2025-03-01 00:00:00", "create_end_time": "2025-03-31 23:59:59"}'

Paginated retrieval of a large number of todos

When the number of todos exceeds the single-page limit, retrieve pages in a loop using cursor :

First request (without cursor): Use the wecom_mcp tool to call wecom_mcp call todo get_todo_list '{"limit": 20}'. If retrieval is not complete and there are more todos, it returns has_more=true, next_cursor="CURSOR_1"
Second request (passing the previous next_cursor): Use the wecom_mcp tool to call wecom_mcp call todo get_todo_list '{"limit": 20, "cursor": "CURSOR_1"}', returns has_more=false, retrieval complete

Pagination rules:

The first request does not pass cursor
has_more is true , pass next_cursor as the cursor for the next request
has_more is false , stop requesting
During pagination, the time filter parameters remain unchanged
If you choose not to continue paging (for example, the current page's data is already sufficient), you must tell the user that there are more todos not shown and ask the user whether they need to continue viewing

Notes

Time format: All time parameters use the YYYY-MM-DD HH:mm:ss format. When the user says relative times such as "tomorrow" or "next Monday", calculate the specific date based on the current date.
Meaning of status values
- Todo status (todo_status）：0-completed,1-in progress,2-deleted
- User status (user_status）：0-rejected,1-accepted,2-completed
Error handling: If errcode is not 0, tell the user the error message in errmsg error message in
Details must be retrieved: This interface returns summary information (excluding content and assignee). After getting the list, you must immediately call wecom-get-todo-detail to get the full content before displaying it to the user; do not display only the list summary.
If pagination is not complete, you must remind: If the returned has_more is true, when displaying the results to the user, you must clearly state "there are more to-dos not displayed" and ask the user whether they need to continue viewing. The user does not know there is more data afterward; failing to remind them will lead to omissions.