Return the tasks matching every supplied filter criterion.

Supports any combination of project, priority, tag, status, and a date window applied to either the due date (open tasks) or the completion timestamp (completed tasks).

Args: detail (str, optional): "compact" (default) or "full". Compact drops the heavy content/desc/checklist items blobs and bulky sync metadata, keeping id, projectId, title, dueDate, startDate, priority, status, isAllDay, timeZone, tags plus a contentPreview (first ~200 chars of content) so keyword search still works. Full returns the raw task objects unchanged. To edit a task, call ticktick_update_task with its id and only the fields to change, plus projectId for a completed task. filter_criteria (dict | str): A criteria object, or a JSON string that decodes to one. No value below reaches the query unchecked, and any key not on this list is an error rather than something ignored, so a mistyped key fails loudly. Recognised keys:

    * ``status``: ``"uncompleted"`` (default) or ``"completed"``.
      When ``"completed"`` you should supply
      ``completion_start_date`` and/or ``completion_end_date``;
      without dates the result is an empty list.
    * ``project_id`` (str): Limit to tasks in this project.
      Accepts the project's name as well as its ID
      (case-insensitive, trimmed). Two projects sharing a
      name is an error, not a guess, and so is a project the
      account does not have.
    * ``priority`` (int): 0=None, 1=Low, 3=Medium, 5=High. Must be
      a JSON integer; the string ``"3"`` and the float ``3.0`` are
      errors, as is any other value.
    * ``tag_label`` (str): Tag name (case-sensitive), non-empty.
      Surrounding whitespace is trimmed.
    * ``due_start_date`` / ``due_end_date`` (str): ISO date or
      datetime strings; only used when ``status='uncompleted'``.
      A value that cannot be read as a date is an error, so a
      window is never silently dropped, and a window that ends
      before it begins is an error too. Bounds apply at day
      granularity, so any time part is ignored rather than
      validated.
    * ``completion_start_date`` / ``completion_end_date`` (str):
      ISO date or datetime strings; only used when
      ``status='completed'``. Same date rules as above.
    * ``tz`` (str): Default IANA timezone applied to date filters,
      e.g. ``"Europe/London"``. A name that does not resolve is an
      error rather than being ignored, so results are never
      labelled with a zone that was not applied.
    * ``sort_by_priority`` (bool): Sort by descending priority.
      Must be a JSON boolean; the strings ``"true"``/``"false"``
      and ``1``/``0`` are errors.

Returns: JSON list of matching task objects (compact by default; see detail). Empty list if nothing matches. If a compact result would still exceed the size budget, the soonest-due matches are returned and a final _truncation_note element reports how many were omitted -- nothing is dropped silently. On invalid input or backend failure: {"error": "...", "status": "error"}. One error carries an extra key: outcome: "project_list_unverifiable" means the project list could not be refreshed to confirm project_id, so retry rather than concluding the project is gone.

Freshness: Uncompleted queries read local state, synced from the server at most once per throttle window (default 15s, TICKTICK_MCP_SYNC_TTL_SECONDS); a change made elsewhere within that window may not be visible yet -- call ticktick_sync to force a refresh. Completed queries are always fetched live.

Limitations: - TickTick caps get_completed at 100 results; very wide completion windows are truncated server-side. - Filtering happens client-side after the fetch, so additional criteria do not reduce the number of network requests. - Compact output is for browsing only; full content for one task is available via ticktick_get_by_id or detail="full".

Agent Usage Guide: - List open tasks in a project: {"status": "uncompleted", "project_id": "<id>"} - List completed tasks in the last 7 days: { "status": "completed", "project_id": "<id>", "completion_start_date": "2026-05-21", "completion_end_date": "2026-05-28" } - Find high-priority open tasks due this month, sorted: { "priority": 5, "due_start_date": "2026-05-01", "due_end_date": "2026-05-31", "sort_by_priority": true }

Returns completed tasks for a project that have NOT yet been marked as processed by a domain agent.

Could be called at the beginning of each conversation to check for new completions. After reviewing each returned task, call ticktick_mark_completion_processed to record that it has been handled.

A task completed through ticktick_complete_task is recorded by that tool, so what this returns is what was completed elsewhere, in the TickTick app or on another client, where a note may be waiting to be read. One exception: no recurring completion is recorded, because it files its completed instance under an id the completing call never sees, so that instance appears here whoever completed it.

Args: project_id (str): TickTick project ID or name to check. Required. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. days (int): How many days back to look for completions. Default 30.

Returns: JSON list of unprocessed task objects (may be empty). Each object includes: id, title, projectId, completedTime, content. Error: {"error": "...", "status": "error"}

Usage Guide: - Call once per project at the start of each conversation. - For each returned task: read the content field, log meaningful outcomes if appropriate, then call ticktick_mark_completion_processed. - Example: ticktick_get_unprocessed_completions( project_id="your_project_id_here", days=30 )

Records that a domain agent has processed a completed task.

Call this after reviewing each task returned by ticktick_get_unprocessed_completions. The task will no longer appear in future calls to that tool.

Args: task_id (str): Full TickTick task ID. Required. project_id (str): Project ID or name the task belongs to. Required. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. title (str, optional): Task title (stored for human-readable audit trail). completed_time (str, optional): ISO completion timestamp from the task object. notes (str, optional): Brief notes on how the completion was handled.

Returns: {"status": "ok", "task_id": "..."} on success. {"status": "already_processed", "task_id": "..."} if already recorded. {"error": "...", "status": "error"} on failure.

Usage Guide: - Call once per task after finishing your handling of it. - Example: ticktick_mark_completion_processed( task_id="abc123", project_id="your_project_id_here", title="Fix kitchen tap", completed_time="2025-06-01T19:00:00+01:00", notes="Replaced ceramic disc, resolved" )

Convert an ISO 8601 datetime string into TickTick's storage format.

TickTick uses YYYY-MM-DDTHH:MM:SS+0000 (UTC offset, no colon).

Args: datetime_iso_string (str): ISO 8601 datetime, e.g. "2026-04-13T20:45:00+01:00". Naive strings are accepted and interpreted in tz. tz (str): IANA timezone name used for the UTC conversion, e.g. "Europe/London" or "America/Los_Angeles".

Returns: On success: {"ticktick_format": "2026-04-13T19:45:00+0000"}. On parse error: {"error": "Invalid datetime format...", "status": "error"}. On any other conversion error: {"error": "Conversion failed: ...", "status": "error"}.

Agent Usage Guide: - Call this when you need to set startDate or dueDate on a task dict by hand. The ticktick_create_task and ticktick_update_task tools accept ISO strings directly and run this conversion internally.

Example: ticktick_convert_datetime_to_ticktick_format( datetime_iso_string="2026-04-13T20:45:00+01:00", tz="Europe/London", )

Create a new task.

Args: title (str): Task title. Required. project_id (str, optional): Project ID or name. Defaults to inbox. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. content (str, optional): Long-form content (markdown supported). desc (str, optional): Short description / checklist subtitle. all_day (bool, optional): True for all-day tasks. start_date (str, optional): ISO 8601 start datetime, e.g. "2026-04-13T09:00:00+01:00". due_date (str, optional): ISO 8601 due datetime. expected_day_of_week (str, optional): English weekday name. Required when due_date is set; mismatch returns an error. time_zone (str, optional): IANA timezone. Defaults to the system timezone for date conversion. reminders (list[str], optional): TickTick trigger strings, e.g. ["TRIGGER:-PT30M"]. repeat (str, optional): Recurrence rule (RFC 5545 RRULE). priority (int, optional): 0=None, 1=Low, 3=Medium, 5=High. sort_order (int, optional): Position within project. items (list[dict], optional): Subtask items.

Returns: JSON object containing the created task. _verification_warnings carries everything worth knowing about what landed: a response that did not match what was sent, a due date that is missing and so will fire no reminder at all or all-day and so no timed one, a title character TickTick parses as a marker, and content longer than the compact preview. On failure: {"error": "...", "status": "error"}.

Limitations: - builder() in ticktick-py sometimes omits dates, reminders, priority and timezone; we re-populate them after the call.

Agent Usage Guide: - Always pair due_date with expected_day_of_week. - Pass a project name directly, or list ids with ticktick_get_all(search="projects").

Example: ticktick_create_task( title="Replace kitchen tap washer", project_id="", due_date="2026-06-01T20:45:00+01:00", expected_day_of_week="Monday", time_zone="Europe/London", priority=3, )

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", })

Delete one or more tasks.

Args: task_ids (str | list[str]): A single task ID, or a list of IDs. An empty list returns an error. project_id (str, optional): Used to construct a minimal delete payload when get_by_id cannot find the task locally (typical for completed tasks). Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess.

Returns: {"status": "success", "deleted_count": N, "tasks_deleted_ids": [...]} on success. Tasks that could not be matched at all are returned as status="not_found" with missing_ids / invalid_ids arrays. Partial success surfaces warnings. Empty input: {"status": "error", "message": "No task IDs..."}.

Agent Usage Guide: - For tasks already completed in TickTick, supply project_id -- get_by_id does not see completed tasks.

Example: ticktick_delete_tasks( task_ids=["abc123", "def456"], project_id="", )

Return every open task in a project.

Args: project_id (str): The project's ID or name. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess. List them with ticktick_get_all(search="projects"). detail (str, optional): "compact" (default) or "full". Compact drops the heavy content/desc/checklist items blobs and bulky sync metadata, keeping id, projectId, title, dueDate, startDate, priority, status, isAllDay, timeZone, tags plus a contentPreview (first ~200 chars of content) so keyword search still works. Full returns the raw task objects unchanged.

Returns: Compact (default): JSON list of compact task objects. If the compact payload would still exceed the size budget, the soonest-due tasks are returned and a final _truncation_note element reports how many were omitted -- nothing is dropped silently. Full: JSON list of raw task objects (empty list if none). On failure: {"error": "...", "status": "error"}.

Limitations: - Completed tasks are NOT included. - Compact output is for browsing only. To edit a task, call ticktick_update_task with its id and only the fields to change. Get the full content of a single task with ticktick_get_by_id, or pass detail="full".

Freshness: Local state is synced from the server at most once per throttle window (default 15s, TICKTICK_MCP_SYNC_TTL_SECONDS); an edit made elsewhere within that window may not be visible yet. Call ticktick_sync to force an immediate refresh.

Example: ticktick_get_tasks_from_project( project_id="" )

Mark a task as completed.

Completing a task here also records it as processed, so it does not come back from ticktick_get_unprocessed_completions. That queue is for completions made elsewhere, where a note may be waiting to be read. There is no need to call ticktick_mark_completion_processed afterwards.

Args: task_id (str): The task's full ID.

Returns: After a completion call, a JSON object carrying outcome. completed: the task is no longer open. It has usually left the active list, so no task object comes back; one that can still be read is returned at status=2. completed_recurring: the next occurrence, at status=0, with next_occurrence_id. uncertain: a non-recurring task is still open, with _verification_warnings saying so. completion_recorded reports whether the local record was written. Present only when a non-recurring task completed; absent wherever nothing was recorded, which is every recurring completion and outcome: "uncertain". The task is complete either way. Missing task: {"status": "not_found", "error": "..."}. Other failures: {"error": "...", "status": "error"}.

Limitations: - Once completed, the content field becomes immutable. Update content with resolution notes BEFORE calling this tool. - A recurring task's completion is never recorded, whatever the outcome: completing one files the completed instance under an id this tool never sees. That instance reaches the unprocessed queue. Do not mark the series id processed by hand instead; it is not the id the queue is showing.

Example: ticktick_complete_task(task_id="60ca9dbc8f08516d9dd56324")

Move a task into a different project.

Args: task_id (str): The task's full ID. new_project_id (str): Destination project's ID or name. Accepts the project's name as well as its ID (case-insensitive, trimmed; "Inbox" resolves to the inbox). Two projects sharing a name is an error, not a guess.

Returns: JSON object containing the moved task. If the target project cannot be looked up locally, the move is still attempted. Missing source task (no projectId field): {"status": "not_found", ...}. Other failures: {"error": "...", "status": "error"}.

Example: ticktick_move_task( task_id="60ca9dbc8f08516d9dd56324", new_project_id="", )

Nest child_task_id under parent_task_id.

Args: parent_task_id (str): The parent task's ID. child_task_id (str): The task to become a subtask. Must differ from parent_task_id and live in the same project.

Returns: On success: {"status": "success", "updated_parent_task": ..., "api_response": ...}. Missing child / parent: {"status": "not_found", "error": "..."}. Cross-project: {"error": "...same project...", "child_project": "...", "parent_project": "..."}.

Example: ticktick_make_subtask( parent_task_id="60ca9dbc8f08516d9dd56324", child_task_id="60ca9dbc8f08516d9dd56325", )

Look up any object (task, project, tag) by its ID.

Args: obj_id (str): The object's full ID.

Returns: JSON object of the matching record, or an empty object {} if nothing has that id. Branch on emptiness. On failure: {"error": "...", "status": "error"}.

Freshness: Local state is synced from the server at most once per throttle window (default 15s, TICKTICK_MCP_SYNC_TTL_SECONDS); an edit made elsewhere within that window may not be visible yet. Call ticktick_sync to force an immediate refresh.

Example: ticktick_get_by_id(obj_id="60ca9dbc8f08516d9dd56324")

Dump everything of a single kind from the local sync state.

Args: search (str): Either "tasks", "projects" or "tags" (case-insensitive). detail (str, optional): "compact" (default) or "full". Accepted for parity with the other list tools and validated here. It has no effect on the "projects"/"tags" searches (those return non-task records in full) nor on the currently inert "tasks" search -- for a compact task list use ticktick_filter_tasks or ticktick_get_tasks_from_project.

Returns: For "projects": JSON list, inbox prepended as {"id": <inbox>, "name": "Inbox"}. For "tags": JSON list of tag objects. For "tasks": see Limitations. Unknown search type: {"error": "Invalid search type...", "status": "error"}.

Limitations: - "tasks" triggers a fetch of every open task across all projects, but the current implementation returns None rather than a JSON string. Use ticktick_filter_tasks({"status": "uncompleted"}) for a proper (compact) JSON response.

Example: ticktick_get_all(search="projects")

Force an immediate refresh of TickTick state from the server.

The active-read tools (ticktick_get_by_id, ticktick_get_tasks_from_project, ticktick_filter_tasks) already auto-refresh at most once per throttle window (default 15s, overridable via TICKTICK_MCP_SYNC_TTL_SECONDS). Call this when you need an immediate refresh -- e.g. you just changed something in the TickTick app on another device, or a read looks stale and you want to be certain before acting.

Returns: {"status": "synced", "task_count": N, "project_count": M} on success. {"status": "error", "detail": "..."} if the refresh failed -- the previous (stale) state is still served by the read tools, so callers can continue with reduced confidence.

Example: ticktick_sync()