Things MCP

Overview Schema Source Related Servers Discussions Admin

things_update_item

DestructiveIdempotent

Modify Things 3 tasks or projects: edit fields, complete/cancel/reopen, clear deadlines. Omitted fields stay unchanged; supply current revision and unique request ID.

Instructions

Edit supported fields, or complete/cancel/reopen a to-do or project. Use the latest revision and a unique UUID requestId. Omitted fields stay unchanged; deadline null clears it. No deletion or arbitrary property editing.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`target`	Yes
`changes`	Yes
`requestId`	Yes
`expectedRevision`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv1.0.2Sep 8, 2026

addedInput schema / properties / changes / properties / addTagIds

Added value: +{
+  "items": {
+    "maxLength": 128,
+    "minLength": 1,
+    "pattern": "^[A-Za-z0-9_-]+$",
+    "type": "string"
+  },
+  "maxItems": 100,
+  "type": "array"
+}

addedInput schema / properties / changes / properties / appendNotes
```
Added value: +{
+  "maxLength": 10000,
+  "type": "string"
+}
```
addedInput schema / properties / changes / properties / appendTitle
```
Added value: +{
+  "maxLength": 4000,
+  "type": "string"
+}
```

addedInput schema / properties / changes / properties / cancellationDate

Added value: +{
+  "anyOf": [
+    {
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / changes / properties / collapsed
```
Added value: +{
+  "type": "boolean"
+}
```

addedInput schema / properties / changes / properties / completionDate

Added value: +{
+  "anyOf": [
+    {
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / changes / properties / creationDate

Added value: +{
+  "format": "date-time",
+  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+  "type": "string"
+}

addedInput schema / properties / changes / properties / keyboardShortcut
```
Added value: +{
+  "maxLength": 1,
+  "type": "string"
+}
```

addedInput schema / properties / changes / properties / modificationDate

Added value: +{
+  "format": "date-time",
+  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+  "type": "string"
+}

addedInput schema / properties / changes / properties / parentTagId

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 128,
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedInput schema / properties / changes / properties / prependNotes
```
Added value: +{
+  "maxLength": 10000,
+  "type": "string"
+}
```
addedInput schema / properties / changes / properties / prependTitle
```
Added value: +{
+  "maxLength": 4000,
+  "type": "string"
+}
```

addedInput schema / properties / changes / properties / removeTagIds

Added value: +{
+  "items": {
+    "maxLength": 128,
+    "minLength": 1,
+    "pattern": "^[A-Za-z0-9_-]+$",
+    "type": "string"
+  },
+  "maxItems": 100,
+  "type": "array"
+}

addedInput schema / properties / changes / properties / tagIds

Added value: +{
+  "items": {
+    "maxLength": 128,
+    "minLength": 1,
+    "pattern": "^[A-Za-z0-9_-]+$",
+    "type": "string"
+  },
+  "maxItems": 100,
+  "type": "array"
+}

First observedv0.83.0Sep 6, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Beyond the annotations, the description discloses important update semantics: omitted fields remain unchanged, deadline null clears the deadline, and arbitrary property editing is disallowed. It also emphasizes idempotency through requestId and concurrency control through expectedRevision, which the annotations only hint at.

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?

Three tight sentences front-load the action and immediately add the most important usage constraints. No filler or repetition exists, and every clause adds value.

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 high complexity of the schema, the presence of an output schema, and annotations for read/destructive/idempotent behavior, the description covers the essential semantics needed to call the tool correctly. The main slight gap is not explicitly stating which target kinds support which changes, but the schema's target enum and changes structure mitigate this.

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?

With 0% schema description coverage, the description compensates well for the critical parameters: requestId must be a unique UUID, expectedRevision must be the latest revision, and changes is a partial object where omitted fields are untouched and deadline null clears it. It does not individually explain every changes subfield, but the schema's names and enums carry some of that weight.

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 opens with a specific action ('Edit supported fields') and mentions status transitions (complete/cancel/reopen), which clearly distinguishes it from create/trash/move/duplicate siblings. It could be slightly more explicit about area/tag targets, but the core resource and verb are clear.

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 gives operational guidance such as using the latest expectedRevision and a unique UUID requestId, and it explicitly excludes deletion and arbitrary property editing. However, it does not name sibling tools like trash_item or create_item as alternatives, so when-to-use versus those tools is mostly implied rather than stated.

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