ticktick-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.3.0
Disambiguation5/5
Each tool targets a distinct action or query type: project-scoped lists, generic filtering, unprocessed completions, CRUD operations, and utility conversions. Even the overlapping list tools (get_tasks_from_project vs filter_tasks) are clearly differentiated by their descriptions and intended use cases.
Naming Consistency5/5
All tools follow a consistent ticktick_ + verb + noun pattern in snake_case (e.g., create_task, update_task, complete_task, move_task, make_subtask, get_by_id). No style mixing or vague verbs; naming is uniform and predictable.
Tool Count5/5
With 14 tools, the server is well-scoped for a task management domain. Each tool covers a core operation or a special workflow without bloat, fitting neatly within the ideal 3-15 range.
Completeness5/5
The tool set covers the full task lifecycle: create, read (multiple retrieval modes), update, delete, complete, move, subtask creation, and sync. Minor gaps like get_all's broken 'tasks' mode are documented with a workaround, so agents can still achieve their goals.
Average 4.8/5 across 14 of 14 tools scored. Lowest: 4.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 53 commits in the last 12 weeks
- Last stable release on August 9, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under GPL 3.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses return states (null if not found, error format on failure) and freshness constraints with a suggestion to call ticktick_sync for immediate refresh. This is good behavioral context for a read operation.
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 front-loaded with the core purpose, followed by structured Args/Returns, a Freshness note, and an example. Every sentence adds value with no redundancy.
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?
For a simple lookup tool with one parameter and an output schema, the description is complete. It covers return types, error handling, and data freshness. The output schema handles return format specifics.
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 description coverage is 0%, but the description adds 'The object's full ID.' and provides an example. This compensates for the lack of schema descriptions, giving the agent meaningful guidance on the parameter.
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 clearly states 'Look up any object (task, project, tag) by its ID.' It uses a specific verb-resource pair ('look up' by ID) and distinguishes from sibling tools like ticktick_get_all or ticktick_get_tasks_from_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It provides an example and freshness notes but does not clarify when to prefer this over ticktick_get_all or ticktick_filter_tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It documents success and error states (not_found, cross-project), but does not discuss idempotency, side effects on parent task order, or authorization requirements.
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 concise with structured sections (Args, Returns, Example) and includes an example. Every sentence adds value without unnecessary fluff.
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?
Given the tool's simplicity, the description covers purpose, constraints, and error handling. However, it omits edge cases like what happens if the child is already a subtask elsewhere, and assumes output schema covers return structure.
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?
With 0% schema description coverage, the description provides clear, meaningful definitions for both parameters (parent_task_id and child_task_id), including the critical constraint that they must differ and be in the same project.
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 clearly states the verb 'nest' and the resources 'child_task_id under parent_task_id', distinguishing it from sibling tools like move_task or update_task. The example further reinforces the purpose.
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 description provides constraints (must differ, same project) and error cases, but does not explicitly compare to alternatives like ticktick_move_task or when to use subtasking vs. other organizational methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details the fetch-and-overlay mechanism, read-only field stripping, return format with verification warnings, and the validation-only nature of expectedDayOfWeek.
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?
Structured with Args, Returns, Limitations, Agent Usage Guide, and Example. Each section adds value, though slightly long. Well-organized and front-loaded with key behavior.
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 complexity of partial updates and read-only fields, the description covers all necessary behaviors: edge cases (dueDate+expectedDayOfWeek), return format, failure mode. Output schema exists, so return explanation is sufficient.
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 description coverage is 0%, so description compensates: explains task_object requires id, optional fields, and the dueDate+expectedDayOfWeek constraint. Example demonstrates usage. Could list more fields but schema already defines them.
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 clearly states the tool updates an existing task without wiping unmodified fields, explaining the underlying API behavior. It distinguishes from sibling tools like delete, create, and complete by focusing on partial updates.
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' provides explicit advice, such as rescheduling via a single update with dueDate and expectedDayOfWeek. It does not explicitly state when not to use, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: it states the side effect (content becomes immutable), describes return formats for success, not found, and other failures, and mentions verification warnings. This is comprehensive for a mutation tool.
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 well-structured with clear sections (one-line purpose, Args, Returns, Limitations, Example) and no redundant sentences. Every part adds value without unnecessary length.
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 simplicity (one parameter, no annotations, but has output schema), the description covers all necessary aspects: parameter semantics, return values, side effects, and an example. There are no gaps for an agent to use this tool correctly.
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?
The description adds meaning to the task_id parameter by labeling it as 'The task's full ID', which hints at the required format. Although schema coverage is 0%, the description compensates adequately for a single string parameter.
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 starts with a clear verb and resource: 'Mark a task as completed.' It distinguishes from siblings like ticktick_create_task or ticktick_delete_tasks by specifying the completion action and includes limitations unique to this operation.
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 description includes a limitations section advising to update content before calling, which provides usage context. However, it does not explicitly state when to use this tool versus alternatives like ticktick_update_task or ticktick_delete_tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the transparency burden. It discloses error behavior for empty input, partial success warnings, project_id name/ID resolution rules, and the 'not_found' return variant. This is comprehensive for a delete operation.
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 well-structured with Args, Returns, Agent Usage Guide, and Example sections. It is slightly verbose but every section adds meaningful detail, and the example clarifies usage without being redundant.
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 absence of annotations and minimal schema descriptions, the description covers all essential aspects: parameter semantics, edge cases, return formats, and conditional usage. It is fully sufficient for an agent to select and invoke the tool correctly.
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?
The schema provides only titles with zero description coverage, but the description thoroughly explains both parameters: task_ids type flexibility and empty-list error, plus project_id's optional fallback behavior and name/ID acceptance. This far exceeds schema information.
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 'Delete one or more tasks,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like ticktick_complete_task or ticktick_update_task. The scope is unambiguous.
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' explicitly states when to supply project_id (for completed tasks) and explains that get_by_id does not see completed tasks. This gives clear context for a nuanced scenario, though it does not explicitly contrast with alternative deletion-like tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return format (success and error), behavior for naive strings, and error types (parse vs conversion). No annotations exist, so description carries full burden and meets it well.
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?
Well-structured with clear sections (Purpose, Args, Returns, Usage Guide, Example). Each sentence adds value; front-loaded with main purpose.
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?
Tool has 2 simple parameters, output schema described in text. Description covers all necessary details for correct invocation and error handling.
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 has 0% coverage, but description fully explains each parameter with examples, including handling of naive strings for datetime_iso_string and IANA conventions for tz.
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?
Description clearly states it converts ISO 8601 datetime to TickTick's format, specifies the output format, and distinguishes itself from sibling tools that already perform this conversion internally.
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?
Explicitly says when to use this tool (when setting startDate/dueDate manually) and notes that create/update tools do this internally, providing clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses important behaviors: the return format including _verification_warnings, the warning added when due_date is missing, the exact handling of project_id (name or ID, case-insensitive, error on duplicate names), the requirement and mismatch error for expected_day_of_week, and a known limitation about the builder() omitting fields. This is exceptional transparency.
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 well-structured with clear sections (Args, Returns, Limitations, Agent Usage Guide, Example). It is long but every sentence adds meaningful information; the format is front-loaded with the core purpose and each section is appropriately placed. No redundancy or filler.
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?
For a complex tool with 14 parameters, the description covers all essential aspects: complete parameter documentation, return value structure, error handling, a real usage example, and a known limitation. Combined with the output schema presence, this provides a comprehensive understanding for an agent to use the tool correctly.
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%, placing the full burden on the description. It gives detailed semantics for every parameter: types, defaults, constraints, and format examples (e.g., ISO 8601 dates, TRIGGER:-PT30M, RFC 5545 RRULE, priority mapping). This goes far beyond what the schema alone provides.
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 "Create a new task." states a clear verb and resource, unambiguously distinguishing this tool from siblings like update, delete, and complete. The description then elaborates on the specific parameters and behavior of creation, leaving no doubt about its purpose.
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 provides practical instructions: always pair due_date with expected_day_of_week, and pass a project name directly or list ids with ticktick_get_all(search='projects'). It gives clear context for using the tool correctly, but it does not explicitly state when not to use it or directly contrast with alternative tools, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It details return values, error cases (not_found, error), and the edge case where the target project cannot be looked up locally (move still attempted). Project name resolution behavior is also clearly explained, covering case-insensitivity, trimming, Inbox resolution, and ambiguity errors. This is comprehensive transparency.
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 well-organized with a one-line summary, Args, Returns, and Example sections. Every sentence adds value: parameter details, behavior, error handling, and a concrete example. No redundancy or fluff; the structure is front-loaded and scannable.
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?
For a two-parameter move tool with no annotations and an output schema present, the description covers all necessary aspects: parameter semantics, return format, failure modes, and an example. It is complete even without relying on the output schema, and the explicit return behavior gives the agent full confidence in invoking the tool.
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?
The input schema provides no descriptions (0% coverage), only parameter names and types. The description adds rich meaning: task_id is the full ID, new_project_id accepts either ID or name with specific matching rules and error conditions. This fully compensates for the schema gaps.
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 begins with a clear, specific verb and resource: 'Move a task into a different project.' This directly distinguishes it from sibling tools like update, complete, or delete. The purpose is immediately understandable and unambiguous.
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 description gives clear context on when to use the tool (to move a task to another project) and provides detailed behavioral guidelines for the new_project_id parameter (name resolution, case-insensitivity, Inbox handling, ambiguity errors). While it doesn't explicitly mention alternatives or exclusions, the purpose is distinct enough among siblings that an agent can infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: return values for each search type (including the inbox prepended for projects), the limitation that tasks returns None, and error handling for invalid search types. It explains the detail parameter's inertness.
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 structured with sections (Args, Returns, Limitations, Example) but is somewhat verbose. However, every sentence adds value, and the key information is front-loaded.
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 complexity (multiple search types, quirks), the description is fully complete. It explains return values, limitations, and error handling, and references sibling tools for alternatives.
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%, but the description adds extensive meaning: explains the search parameter options and behavior of detail (accepted for parity, no effect on projects/tags). The example clarifies usage.
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 clearly states the tool dumps all items of a single kind (tasks, projects, tags) from local sync state. It differentiates from sibling tools like ticktick_filter_tasks and ticktick_get_tasks_from_project by specifying what this tool does that others don't.
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 description explicitly advises when to use this tool (to get all items of a type) and when not to (for tasks, due to limitations, recommending ticktick_filter_tasks instead). It also notes the detail parameter is accepted for parity but has no effect on some searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It fully discloses behavior: on success returns synced status with counts, on error returns an error detail and notes that stale state is still served. It also mentions the auto-refresh mechanism of read tools.
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 well-structured, with a clear statement, contextual explanation, return value specification, and an example. Every sentence adds value, and it is front-loaded with the core purpose.
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 has no parameters and an output schema exists (indicated by context), the description provides a complete picture: purpose, usage context, return format, and error handling. Nothing essential is missing.
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?
The tool has no parameters, and schema coverage is trivially 100%. According to guidelines, baseline is 4 for zero parameters. The description adds no parameter info, but it does provide context about return values and behavior, which is appropriate.
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 clearly specifies the tool's purpose: forcing an immediate refresh of TickTick state from the server. It distinguishes itself from sibling tools by contrasting with the auto-refresh behavior of read tools, leaving no ambiguity about what the tool does.
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 description explicitly states when to use this tool (immediate refresh needed, e.g., after changes in the TickTick app or stale reads) and implicitly when not to (relying on auto-refresh of read tools). It also explains that the read tools auto-refresh with a configurable TTL, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to fall back on, the description carries the full burden and does so excellently. It discloses freshness semantics (local state vs. live completed queries), truncation behavior with an explicit _truncation_note, server-side caps, client-side filtering implications, and the danger of feeding compact output into an update.
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?
Although long, the description is exceptionally well structured with clear sections (Args, Returns, Freshness, Limitations, Agent Usage Guide). Every sentence delivers actionable information; the front-loaded summary sentence is immediately followed by organized detail, making it easy to scan.
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?
The tool is complex (multi-criteria filtering, date windows, status-dependent behavior), and the description is fully complete: return formats, error schema, truncation semantics, staleness handling, and realistic examples. The presence of an output schema is noted, but the description adds beyond it by explaining the compact vs. full distinction and the conditions affecting results.
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?
The input schema provides zero descriptions for parameters, but the description compensates with exhaustive semantics: detail choices and their implications, all filter_criteria keys, types, defaults, accepted values (including priority mapping), date field applicability, case sensitivity, timezone defaults, and error conditions like ambiguous project names.
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 clear verb+resource: 'Return the tasks matching every supplied filter criterion.' It immediately distinguishes this from sibling tools (e.g., ticktick_get_all, ticktick_get_by_id, ticktick_get_tasks_from_project) by emphasizing filtering across multiple criteria rather than simple retrieval.
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 description provides an explicit 'Agent Usage Guide' with concrete JSON examples for open tasks, completed tasks in a date window, and high-priority tasks. It also names alternatives, such as using ticktick_get_by_id + ticktick_update_task for editing and ticktick_sync for forced refresh, and states when not to use compact output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and succeeds: it discloses truncation behavior with _truncation_note, sync throttle window, completed-task exclusion, and API behavior that wipes omitted fields on updates. These are actionable behavioral traits beyond schema/annotations.
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 organized into Args, Returns, Limitations, Freshness, and Example sections. Each sentence provides necessary information without filler; the length is justified by the tool's complexity and the absence of schema/annotation support.
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, the description covers purpose, all parameter semantics, return types, failure format, edge cases (duplicate names, truncation), freshness guarantees, and an example. It fully equips an agent to invoke and interpret results correctly.
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%, but the description fully compensates: project_id semantics include name-or-ID, case-insensitivity, trimming, 'Inbox' resolution, duplicate-name error, and how to list projects. The detail parameter is thoroughly explained with exact compact/full payload differences and contentPreview behavior.
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 'Return every open task in a project,' a specific verb and resource that clearly states the tool's purpose. It also distinguishes from siblings by explicitly noting completed tasks are not included, and the compact/full distinction adds further scoping.
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 Limitations section explicitly references alternatives: use ticktick_get_by_id for full task content/editing, ticktick_update_task for updates, ticktick_get_all for listing projects, and ticktick_sync for forced refresh. It also warns that compact output is for browsing only, giving clear when-to-use vs when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it is a read-only retrieval operation, returns unprocessed tasks, does not mark them as processed itself, and specifies error output format. It also explains edge cases like duplicate project names and case-insensitive name resolution. This exceeds expectations given the absence of annotations.
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 well-structured with clear sections (Args, Returns, Usage Guide) and a concise opening statement. While slightly verbose, every sentence adds meaningful information, and the example makes invocation explicit without redundancy.
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 moderate complexity, no annotations, and the presence of an output schema, the description still adds essential context: the return item fields, error format, and the required follow-up action. It fully prepares an agent to invoke the tool correctly and interpret its results.
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?
The input schema only provides names and types, but the description adds critical semantics: project_id accepts either ID or name, supports case-insensitive trimmed matching, resolves 'Inbox', and raises an error on ambiguous name collisions. It also explains the days parameter's meaning and default. This optimally compensates for the 0% schema description coverage.
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 uses a specific verb+resource ('Returns completed tasks for a project...') and clearly distinguishes the tool from siblings by emphasizing the 'NOT yet marked as processed' state. It also mentions the workflow with ticktick_mark_completion_processed, which sets it apart from generic task-listing tools.
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 states when to call it ('at the beginning of each conversation'), which sibling to use afterward (ticktick_mark_completion_processed), and includes a step-by-step Usage Guide with an example invocation. This leaves no ambiguity about the intended usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: the task will no longer appear in future calls to the companion tool, and it documents all return statuses (ok, already_processed, error). It also warns about ambiguous project names being an error, adding important behavioral detail.
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 well-structured with Args, Returns, and Usage Guide sections. It is front-loaded with the purpose and each section adds value; the example is illustrative without being redundant.
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?
Covers purpose, when to use, parameter semantics, return values, and behavioral side effects. The output schema exists but the description already explains the return format, and it fully compensates for the empty schema descriptions.
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 coverage is 0%, so the description's detailed parameter documentation is essential. It explains each parameter including project_id resolution rules (case-insensitive, trimmed, 'Inbox' special case, duplicate name error), and clarifies optional fields like title and completed_time.
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 begins with a specific verb+resource: 'Records that a domain agent has processed a completed task.' It clearly differentiates from sibling tool ticktick_complete_task by noting it should be called after reviewing tasks from ticktick_get_unprocessed_completions.
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?
Explicitly instructs to call 'after reviewing each task returned by ticktick_get_unprocessed_completions' and includes a usage guide with 'Call once per task after finishing your handling of it.' This provides clear when-to-use guidance and references the relevant sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![ticktick-mcp MCP server](https://glama.ai/mcp/servers/partymola/ticktick-mcp/badges/card.svg)](https://glama.ai/mcp/servers/partymola/ticktick-mcp)

Score Badge

Copy to your README.md:

[![ticktick-mcp MCP server](https://glama.ai/mcp/servers/partymola/ticktick-mcp/badges/score.svg)](https://glama.ai/mcp/servers/partymola/ticktick-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/partymola/ticktick-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server