ticktick-mcp

Overview Schema Source Related Servers Discussions Admin

ticktick_get_tasks_from_project

Retrieve every open task from a TickTick project by ID or name, excluding completed tasks, with compact or full detail options.

Instructions

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="" )

Input Schema

Name	Required	Description	Default
`detail`	No		compact
`project_id`	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.9/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 behavioral burden well. It discloses that completed tasks are excluded, explains compact versus full output, warns about size-budget truncation with a _truncation_note, documents the error shape, and describes the local-sync throttle window and ticktick_sync refresh path.

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?

The description is long but well structured with Args, Returns, Limitations, Freshness, and Example sections, and the key purpose is front-loaded. The example is marginal and some return-value detail overlaps with the output schema, but the length is largely justified by the missing schema descriptions and annotations.

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 lack of annotations and 0% schema description coverage, the description is complete enough to call the tool correctly. It covers parameters, output modes, truncation behavior, error handling, freshness, and alternatives, and the output schema further supports return-value details.

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 does. It explains that project_id accepts an ID or case-insensitive trimmed name, that 'Inbox' resolves specially, that duplicate names are an error, and that detail accepts 'compact' or 'full' with detailed differences between the two modes.

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 description opens with a specific verb and resource: 'Return every open task in a project.' It also clarifies scope by excluding completed tasks and distinguishes the tool from siblings such as ticktick_get_by_id, ticktick_update_task, and ticktick_get_all in the limitations section.

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?

It explicitly routes the agent to alternatives: use ticktick_get_all(search="projects") to list projects, ticktick_update_task to edit, ticktick_get_by_id for one task's full content, or detail="full" here. It also states that completed tasks are not included, making the when-not condition clear.

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

Deploy Server