ticktick_filter_tasks
Filter TickTick tasks by project, priority, tag, status, and due or completion date, returning only tasks that match all criteria.
Instructions
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, fetch
the full object with ticktick_get_by_id first, then send
every field back via ticktick_update_task -- compact
output must never feed an update.
filter_criteria (dict | str): A criteria object, or a JSON string
that decodes to one. 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.
* ``priority`` (int): 0=None, 1=Low, 3=Medium, 5=High.
* ``tag_label`` (str): Tag name (case-sensitive).
* ``due_start_date`` / ``due_end_date`` (str): ISO date or
datetime strings; only used when ``status='uncompleted'``.
* ``completion_start_date`` / ``completion_end_date`` (str):
ISO date or datetime strings; only used when
``status='completed'``.
* ``tz`` (str): Default IANA timezone applied to date filters.
* ``sort_by_priority`` (bool): Sort by descending priority.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"}.
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 }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | compact | |
| filter_criteria | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |