ticktick-mcp

Overview Schema Source Related Servers Discussions Admin

ticktick_update_task

Updates an existing TickTick task by sending only the fields you want to change, preserving all unmodified fields and avoiding accidental data loss.

Instructions

Update an existing task without wiping unmodified fields.

Send only the fields to change. The tool fetches the current task and overlays ONLY the fields the caller explicitly set (exclude_unset=True), sending the other editable fields back with them.

Args: task_object (TaskObject): Must include id. All other fields are optional; set only the ones you want to change. When dueDate is set you must also set expectedDayOfWeek.

Returns: JSON object containing the updated task. _verification_warnings is attached when the response did not match what we sent, when a reminders: [] removal could not be confirmed, and when status: 0 was set but the local completion record could not be cleared. That last one says nothing about whether the update itself landed. On failure: {"error": "...", "status": "error"}.

Limitations: - Read-only API fields (creator, etag, createdTime, modifiedTime, deleted, kind, isFloating) are stripped from the main update call. - Setting status: 0 also clears any local record of this task's earlier completion, so a later completion is surfaced by ticktick_get_unprocessed_completions again. A clear that fails is reported in _verification_warnings. - reminders: [] removes whatever reminders the task has at that moment, so do not send it back from an old copy of the task. _verification_warnings says so if the removal could not be confirmed. reminders: null leaves them alone. A non-empty list replaces them. Sending dueDate and startDate as null removes the date, and its reminders with it.

Agent Usage Guide: - To reschedule a task, send a single update with the new dueDate + expectedDayOfWeek. Do NOT complete and recreate.

Example: ticktick_update_task(task_object={ "id": "60ca9dbc8f08516d9dd56324", "projectId": "", "priority": 5, "dueDate": "2026-06-15T20:45:00+01:00", "expectedDayOfWeek": "Monday", "timeZone": "Europe/London", })

Input Schema

Name	Required	Description	Default
`task_object`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0May 31, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses the exclude_unset overlay mechanism, the read-only fields stripped before the call, the side effect of status:0 clearing local completion records, the reminders:[] destructive-replace semantics, and the _verification_warnings signal. That last point even qualifies that a status:0 warning says nothing about whether the update landed — exactly the kind of nuance an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Sections are front-loaded (core behavior, then Args, Returns, Limitations, Usage Guide, Example) and every block adds information. It is long, and some Args text repeats the opening line, but nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A mutation tool with no annotations and an output schema: the description correctly focuses on behavior and warnings rather than re-explaining return shape. Remaining gaps are the undocumented enum-like values (priority, status, repeat) that the schema does not describe either.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the TaskObject exposes ~20 properties, so the description must compensate — and it covers the high-risk ones: id required, dueDate requiring expectedDayOfWeek, reminders null vs [] vs list, null dueDate/startDate removing dates and reminders. It leaves priority values, status codes, repeat/repeatFlag format, and the allDay vs isAllDay duplication undocumented, so it is strong but not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource plus the defining behavioral trait ('without wiping unmodified fields'), which immediately separates it from ticktick_create_task and ticktick_complete_task. The Agent Usage Guide reinforces the distinction by explicitly naming complete-and-recreate as the wrong path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The Agent Usage Guide gives an explicit when-to-use rule with the alternative rejected ('To reschedule a task, send a single update... Do NOT complete and recreate'). It stops short of routing to the other plausible siblings, such as ticktick_move_task for project changes or ticktick_complete_task for status transitions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server