things3-mcp-server

Overview Schema Source Related Servers Discussions Admin

update_todo

Update an open to-do by Things ID or name search, allowing you to reschedule, set or remove a deadline, replace tags, or move it to another list.

Instructions

Update the first matching OPEN to-do (by todo_id or name query).

Input Schema

TableJSON Schema

Name	Required	Description
`tags`	No	If set, REPLACES the task's tags (comma-separated). Use add_tags to append without dropping existing tags.
`when`	No	Reschedule — "today", "tomorrow", "anytime", "someday" or ISO date.
`exact`	No	Require an exact name match instead of a substring match.
`query`	No	Name substring (or exact name if exact=True) identifying the task.
`todo_id`	No	Things id — takes precedence over query, matches exactly.
`deadline`	No	New deadline (due date) as ISO date "YYYY-MM-DD". Pass "none" to REMOVE an existing deadline. An empty string leaves the deadline untouched — that is not the same thing. Removing matters because Things puts a to-do back into Today whenever its deadline is due or overdue, regardless of when it is scheduled: a stale deadline silently clogs Today.
`move_to_list`	No	Move the task to a built-in list (e.g. "Anytime").

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv0.3.0Aug 21, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / deadline / description

Added value: +"New deadline (due date) as ISO date \"YYYY-MM-DD\".\nPass \"none\" to REMOVE an existing deadline. An empty string\nleaves the deadline untouched — that is not the same thing.\nRemoving matters because Things puts a to-do back into Today\nwhenever its deadline is due or overdue, regardless of when\nit is scheduled: a stale deadline silently clogs Today."

removedInput schema / properties / deadline / title
```
Removed value: -"Deadline"
```

addedInput schema / properties / exact / description

Added value: +"Require an exact name match instead of a substring match."

removedInput schema / properties / exact / title
```
Removed value: -"Exact"
```

addedInput schema / properties / move_to_list / description

Added value: +"Move the task to a built-in list (e.g. \"Anytime\")."

removedInput schema / properties / move_to_list / title
```
Removed value: -"Move To List"
```

addedInput schema / properties / query / description

Added value: +"Name substring (or exact name if exact=True) identifying the task."

removedInput schema / properties / query / title
```
Removed value: -"Query"
```

addedInput schema / properties / tags / description

Added value: +"If set, REPLACES the task's tags (comma-separated). Use add_tags\nto append without dropping existing tags."

removedInput schema / properties / tags / title
```
Removed value: -"Tags"
```

addedInput schema / properties / todo_id / description

Added value: +"Things id — takes precedence over query, matches exactly."

removedInput schema / properties / todo_id / title
```
Removed value: -"Todo Id"
```

addedInput schema / properties / when / description

Added value: +"Reschedule — \"today\", \"tomorrow\", \"anytime\", \"someday\" or ISO date."

removedInput schema / properties / when / title
```
Removed value: -"When"
```
removedInput schema / title
```
Removed value: -"update_todoArguments"
```
removedOutput schema / title
```
Removed value: -"update_todoDictOutput"
```

First observedv0.2.1Jul 10, 2026

TDQS

A3.5/5.0

Behavior3/5

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

With no annotations, the description carries the full disclosure burden. It communicates the important first-match-only and OPEN-only behavior, but it does not mention the destructive effects such as replacing tags or removing deadlines, nor what happens when no task matches or when neither todo_id nor query is provided.

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 a single front-loaded sentence with no filler. It places the most important behavior first: update, match kind, and state.

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

Completeness3/5

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

The description plus schema covers most invocation details, but the top-level guidance leaves a notable gap for a 7-parameter tool: it does not state that either todo_id or query must logically be supplied, nor does it explain the update behavior when no match is found or when multiple tasks match. The first-matching behavior partially helps, but edge-case expectations remain implicit.

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

Parameters3/5

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

All 7 parameters have rich schema descriptions that explain matching, tags replacement, deadline removal, and rescheduling. The top-level description adds only the high-level clue that lookup is by todo_id or query, so the schema already does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('update') and the resource ('first matching OPEN to-do'), and identifies how the task is found (by todo_id or name query). It does not explicitly name sibling tools like complete_todo or cancel_todo to distinguish from them, so it stops short of full sibling differentiation.

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

Usage Guidelines3/5

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

The description implies when to use it: update an existing open to-do rather than a completed one. It does not explicitly explain when to choose this over complete_todo, cancel_todo, or add_tags, although the schema's tags parameter does mention add_tags for the append case.

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

Deploy Server