ticktick-mcp

Overview Schema Source Related Servers Discussions Admin

ticktick_update_task

Update an existing TickTick task by merging only the fields you specify, preserving unmodified data, and validating due dates.

Instructions

Update an existing task without wiping unmodified fields.

The TickTick API requires the entire editable task on every update; any omitted field is wiped server-side. To prevent that we fetch the current task, then overlay ONLY the fields the caller explicitly set (exclude_unset=True).

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, and when status: 0 was set but the local completion record could not be cleared. The second 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 before the 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.

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

TableJSON Schema

Name	Required	Description	Default
`task_object`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0May 31, 2026

TDQS

A5/5.0

Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it reveals the destructive API behavior, the fetch-then-overlay mechanism, read-only fields being stripped, and the side effect that setting status: 0 clears local completion records. It also explains the meaning of _verification_warnings and failure responses.

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

Conciseness5/5

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

The description is long but densely informative and well organized with Args, Returns, Limitations, Agent Usage Guide, and Example sections. It is front-loaded with the most critical fact—the update-merge behavior—and each section earns its place by explaining a real operational pitfall.

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

Completeness5/5

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

Given the tool's complexity—API replace semantics, conditional field requirements, side effects on completion records, and verification warnings—the description covers every essential aspect an agent needs to call it correctly. The output schema exists, so not describing return values in detail is acceptable, and the failure format is explicitly covered.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it does: it states id is mandatory, all other task_object fields are optional, only explicitly set fields are changed, and dueDate requires expectedDayOfWeek. The concrete reschedule example further clarifies how the parameters combine, and the status-0 limitation gives behavioral meaning to a parameter value.

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 first line states a specific action and resource: 'Update an existing task without wiping unmodified fields.' This distinguishes it from siblings like create, delete, complete, and move, and the merge behavior is a defining feature. An agent immediately knows what the tool is for.

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

Usage Guidelines5/5

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

The Agent Usage Guide explicitly says to reschedule a task by sending a single update with the new dueDate and expectedDayOfWeek, and warns 'Do NOT complete and recreate.' This gives concrete when-to-use guidance and names the anti-pattern to avoid, which is strong alternative differentiation even without enumerating every sibling.

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

Deploy Server