things-api 0.9.0 → 0.10.0

package/dist/mcp/server.js

@@ -13,37 +13,38 @@
  */
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { openThings } from "../client.js";
-import { PKG_VERSION } from "../contracts.js";
-import { diagnose } from "../diagnose.js";
-import { AREA_PREVIEW_LIMIT, DEFAULT_LIST_LIMIT, PROJECT_PREVIEW_LIMIT, capAreaSections, paginateList, paginateToday, previewSections, previewSomedaySections, } from "../read/pagination.js";
-import { resolveCap } from "../read/caps.js";
-import { ALL_DESC, AREA_LIMIT_DESC, DATE_FORMAT, LIMIT_DESC, PROJECT_LIMIT_DESC, REF_FORMAT, REMINDER_FORMAT, WHEN_VALUES, } from "../surface-copy.js";
-import { capabilitiesTable } from "../write/capabilities.js";
-import { OPERATION_KINDS } from "../write/operations.js";
-import { BOUNCE_MAX_ITEMS } from "../write/reorder.js";
+import { ALL_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, BOUNCE_MAX_ITEMS, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, hasTagPresence, LIMIT_DESC, MCP_WHEN_LABELS, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OPERATION_KINDS, openThings, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, ReferenceResolutionError, REMINDER_FORMAT, schemaWarnings, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
 function jsonResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
+/**
+ * A read result: like {@link jsonResult}, but the entity payload passes through
+ * the omit-empty transform (docs/design/contracts.md) so an empty optional
+ * field is absent, not null/[]. Mutation results keep their own shape and use
+ * jsonResult directly.
+ */
+function readResult(data) {
+    return jsonResult(omitEmpty(data));
+}
 /**
  * A read result carrying truncation metadata: the data (already limited) in
- * the first content block, and a second block with the {@link Pagination}
+ * the first content block, and a second block with the {@link Truncation}
  * numbers plus a one-line note the agent can read when rows were dropped.
  */
-function paginatedResult(data, pagination) {
-    const note = pagination.truncated
-        ? `showing ${pagination.shown} of ${pagination.total} items — pass limit (or all: true) to see more`
+function truncatedResult(data, truncation) {
+    const note = truncation.truncated
+        ? `showing ${truncation.shown} of ${truncation.total} items — pass limit (or all: true) to see more`
         : undefined;
     return {
         content: [
-            { type: "text", text: JSON.stringify(data) },
-            { type: "text", text: JSON.stringify({ pagination, ...(note !== undefined && { note }) }) },
+            { type: "text", text: JSON.stringify(omitEmpty(data)) },
+            { type: "text", text: JSON.stringify({ truncation, ...(note !== undefined && { note }) }) },
         ],
     };
 }
 /**
  * Grouped read result (anytime/someday): the per-block-truncated sections plus
- * a second block carrying the {@link GroupedPagination} counts and, when
+ * a second block carrying the {@link GroupedTruncation} counts and, when
  * anything was hidden, a one-line note the agent can read.
  */
 function groupedResult(data, grouped) {
@@ -52,11 +53,25 @@ function groupedResult(data, grouped) {
         : undefined;
     return {
         content: [
-            { type: "text", text: JSON.stringify(data) },
+            { type: "text", text: JSON.stringify(omitEmpty(data)) },
             { type: "text", text: JSON.stringify({ grouped, ...(note !== undefined && { note }) }) },
         ],
     };
 }
+/**
+ * Resolve one MCP cap (limit / area_limit / project_limit) against `all` into a
+ * row cap for the client: `null` = every row, `"conflict"` when an explicit
+ * value is combined with `all: true` (the tool returns a usage error), else the
+ * value or the default. The client re-applies the same semantics on what it
+ * receives; this copy owns the conflict detection the MCP surface reports.
+ */
+function resolveCap(value, all, defaultLimit) {
+    if (all === true && value !== undefined)
+        return "conflict";
+    if (all === true)
+        return null;
+    return value ?? defaultLimit;
+}
 /** Resolve MCP limit/all (flat read tools) into a row cap (null = every row). */
 function resolveLimit(args) {
     return resolveCap(args.limit, args.all, DEFAULT_LIST_LIMIT);
@@ -80,14 +95,14 @@ function mutationResult(result) {
             return jsonResult(result);
         case "blocked":
             return errorResult({
-                code: `blocked:${result.hazard ?? result.reason}`,
+                code: blockedCode(result),
                 message: result.detail,
                 ...(result.likelyCause !== undefined && { likelyCause: result.likelyCause }),
                 remediation: result.remediation,
             });
         case "verify-failed":
             return errorResult({
-                code: `verify-failed:${result.reason}`,
+                code: verifyFailedCode(result),
                 message: result.detail,
                 ...(result.likelyCause !== undefined && { likelyCause: result.likelyCause }),
                 ...(result.hint !== undefined && { remediation: result.hint }),
@@ -109,19 +124,73 @@ function mutationResult(result) {
 const READ_ONLY = { readOnlyHint: true };
 const NON_DESTRUCTIVE = { destructiveHint: false };
 const DESTRUCTIVE = { destructiveHint: true };
-const tagFilterShape = {
+/**
+ * The three tag-filter inputs shared by every tag-accepting tool. `tag` is an
+ * ARRAY — repeat a tag to AND several together (both keep hierarchy-descendant
+ * expansion, which `exact_tag` disables). In FLAT views (read_view, search, and
+ * the projects list of list_collections) `tag` honors container inheritance; in
+ * the SINGLE-CONTAINER tools (get_project, get_area) it matches a tag carried
+ * DIRECTLY on the item — that container's own inherited tags are ignored (every
+ * child inherits them, so an inheritance-inclusive match would be vacuous).
+ */
+const tagOnlyShape = {
     tag: z
-        .string()
+        .array(z.string())
+        .optional()
+        .describe(`Filter by tag (${REF_FORMAT}); repeat to AND several tags. Matches a direct, ` +
+        "container-inherited, or descendant tag (in a container tool the container's own " +
+        "inherited tags are ignored — the tag must be on the item itself)"),
+    exact_tag: z
+        .boolean()
+        .optional()
+        .describe("Match only the named tag(s), not their nested children"),
+    untagged: z
+        .boolean()
         .optional()
-        .describe(`Filter by tag (${REF_FORMAT}); includes items carrying any nested child tag`),
-    exact_tag: z.boolean().optional().describe("Match only the named tag, not its nested children"),
+        .describe("Only items with no tag (direct or inherited); not combinable with tag/exact_tag " +
+        "(in a container tool: no tag on the item itself, ignoring inherited tags)"),
 };
+const tagFilterShape = {
+    ...tagOnlyShape,
+    overdue: z
+        .boolean()
+        .optional()
+        .describe("Only open items past their deadline (due today is not overdue)"),
+};
+/**
+ * Map the MCP tool's snake_case tag inputs onto the shared {@link TagPresence}
+ * shape (canonical CLI-flag spelling) so the one set of contract predicates —
+ * {@link hasTagPresence}, {@link tagFlagConflict}, {@link tagFilterFields},
+ * {@link validateViewArgs} — serves both surfaces. The only difference is
+ * `exact_tag` → `exactTag`.
+ */
+function tagPresence(args) {
+    return {
+        ...(args.tag !== undefined && { tag: args.tag }),
+        ...(args.exact_tag !== undefined && { exactTag: args.exact_tag }),
+        ...(args.untagged !== undefined && { untagged: args.untagged }),
+    };
+}
+/** The MCP-voiced usage copy for the tag-filter mutual-exclusivity conflict. */
+const MCP_UNTAGGED_CONFLICT = "untagged does not combine with tag/exact_tag";
 const dryRunShape = {
     dry_run: z.boolean().optional().describe("Preview the planned change without applying anything"),
 };
+/** How a tag value may be expressed on any tag-accepting tool. */
+const TAG_REF_FORMAT = "each a tag name or a parent/child path; must exist unless create_tags is set";
+/** create_tags param, shared by every tag-accepting write tool. */
+const createTagsShape = {
+    create_tags: z
+        .boolean()
+        .optional()
+        .describe("Create any named tag that does not exist yet (nesting parent/child) before applying, " +
+        "instead of stopping on an unknown tag"),
+};
 const containerRef = (ref) => ({ uuid: ref, title: ref });
 /** Cap on project titles inlined into the server instructions. */
 const INSTRUCTIONS_MAX_PROJECTS = 100;
+/** A tag's display label: nested tags show `parent > child`. */
+const tagLabel = (t) => t.parent === null ? t.title : `${t.parent} > ${t.title}`;
 /**
  * Live-inventory preamble: conventions plus the user's actual areas, tags,
  * and open projects, read once at server start so models can reference real
@@ -146,13 +215,13 @@ function buildInstructions(getClient) {
         "- Every write tool accepts dry_run: true to preview the change without applying it. " +
             "Operations with cascading or permanent effects require the explicit confirmation " +
             "parameter named in their description; refused calls return an error saying what to pass.",
+        `- Read results are compact: ${OMIT_EMPTY_NOTE}`,
     ];
     try {
         const c = getClient();
         const areas = c.read.areas();
         const tags = c.read.tags();
         const projects = c.read.projects();
-        const tagLabel = (t) => t.parent === null ? t.title : `${t.parent.title} > ${t.title}`;
         const shown = projects.slice(0, INSTRUCTIONS_MAX_PROJECTS);
         const overflow = projects.length - shown.length;
         lines.push("", "Current inventory (read at server start — refresh with list_collections):", `- Areas (${areas.length}): ${areas.map((a) => a.title).join(", ") || "none"}`, `- Tags (${tags.length}): ${tags.map(tagLabel).join(", ") || "none"}`, `- Open projects (${projects.length}): ${shown.map((p) => p.title).join("; ") || "none"}` +
@@ -169,6 +238,24 @@ function buildInstructions(getClient) {
 function checklistTarget(args) {
     return args.index !== undefined ? { index: args.index } : { item: args.item ?? "" };
 }
+/**
+ * Derive the audit author for a client's writes from the MCP initialize
+ * handshake's clientInfo.name: lowercased, every run of non-alphanumerics
+ * collapsed to a single "-", leading/trailing dashes trimmed, capped at 32
+ * characters. An absent (or empty-after-sanitizing) client name falls back to
+ * the bare "mcp". The result is never caller-settable — it is the connecting
+ * client's own identity, so each client's writes are attributed to it.
+ */
+const MCP_ACTOR_PREFIX = "mcp";
+function deriveMcpActor(clientName) {
+    const slug = (clientName ?? "")
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/g, "-")
+        .replaceAll(/^-+|-+$/g, "")
+        .slice(0, 32)
+        .replaceAll(/-+$/g, "");
+    return slug === "" ? MCP_ACTOR_PREFIX : `${MCP_ACTOR_PREFIX}:${slug}`;
+}
 export function createThingsMcpServer(options = {}) {
     // One lazily-opened client for the server's lifetime; SQLite read
     // snapshots are per-statement, so fresh reads see external commits.
@@ -181,26 +268,70 @@ export function createThingsMcpServer(options = {}) {
         return client;
     };
     const server = new McpServer({ name: "things-api", version: PKG_VERSION }, { instructions: buildInstructions(getClient) });
+    // The audit author for every write on this connection, derived once from the
+    // client's handshake identity (clientInfo.name). Read per call: clientInfo is
+    // populated when the initialize handshake completes, before any tool can run.
+    // Not caller-settable — no tool argument overrides it.
+    const mcpActor = () => deriveMcpActor(server.server.getClientVersion()?.name);
+    /** Translate the shared MCP write-tool args into pipeline WriteOptions. */
+    const writeOptions = (args) => ({
+        actor: mcpActor(),
+        ...(options.maxDisruption !== undefined && { maxDisruption: options.maxDisruption }),
+        ...(args.dry_run === true && { dryRun: true }),
+        ...(args.verify_timeout_ms !== undefined && { verifyTimeoutMs: args.verify_timeout_ms }),
+        ...(args.acknowledge_checklist_reset === true && { acknowledgeChecklistReset: true }),
+        ...(args.acknowledge_project_reopen === true && { acknowledgeProjectReopen: true }),
+        ...(args.dangerously_permanent === true && { dangerouslyPermanent: true }),
+        ...(args.acknowledge_tag_subtree === true && { acknowledgeTagSubtree: true }),
+        ...(args.dangerously_drive_gui === true && { dangerouslyDriveGui: true }),
+        ...(args.create_tags === true && { createTags: true }),
+    });
     /** Run a handler, mapping environment/usage throws to tool errors. */
     const guard = async (fn) => {
         try {
             return await fn();
         }
         catch (err) {
+            // An unresolved reference (ambiguous or not-found uuid/partial-uuid/name)
+            // carries machine-readable candidates so a consumer can disambiguate as
+            // data, not by re-parsing the prose message.
+            if (err instanceof ReferenceResolutionError) {
+                return errorResult({
+                    code: err.code,
+                    message: err.message,
+                    details: { candidates: err.candidates },
+                });
+            }
             const message = err instanceof Error ? err.message : String(err);
             const code = err instanceof RangeError ? "usage" : "environment";
             return errorResult({ code, message });
         }
     };
-    const writeOptions = (args) => ({
-        actor: "mcp",
-        ...(args.dry_run === true && { dryRun: true }),
-        ...(args.verify_timeout_ms !== undefined && { verifyTimeoutMs: args.verify_timeout_ms }),
-        ...(args.acknowledge_checklist_reset === true && { acknowledgeChecklistReset: true }),
-        ...(args.acknowledge_project_reopen === true && { acknowledgeProjectReopen: true }),
-        ...(args.dangerously_permanent === true && { dangerouslyPermanent: true }),
-        ...(args.acknowledge_tag_subtree === true && { acknowledgeTagSubtree: true }),
-    });
+    /**
+     * A read handler wrapper: run through {@link guard}, then — on a successful
+     * result — append a meta block carrying any non-blocking schema warning (the
+     * same note the CLI prints), so a consumer sees when the Things database no
+     * longer matches the validated schema and its data may be incomplete. No
+     * block is added when the schema checks out or the read itself errored.
+     */
+    const readGuard = async (fn) => {
+        const result = await guard(fn);
+        if (result.isError === true)
+            return result;
+        let warnings = [];
+        try {
+            warnings = schemaWarnings(getClient().schemaStatus());
+        }
+        catch {
+            warnings = [];
+        }
+        if (warnings.length === 0)
+            return result;
+        return {
+            ...result,
+            content: [...result.content, { type: "text", text: JSON.stringify({ meta: { warnings } }) }],
+        };
+    };
     /** Resolve a uuid to to-do/project for the type-generic item tools. */
     const itemType = (uuid) => {
         const item = getClient().read.byUuid(uuid);
@@ -216,7 +347,7 @@ export function createThingsMcpServer(options = {}) {
         description: "Read a Things list as the app presents it: today (split into Today and This " +
             "Evening), inbox, anytime, upcoming, someday, logbook, or trash. For upcoming, " +
             "horizon > 1 also includes future occurrences of repeating items (up to 10 each). " +
-            "anytime/someday return sidebar-ordered sections (area + items; null area = the " +
+            "anytime/someday return sections in canonical order (area + items; null area = the " +
             "top-level block); children of someday/future-scheduled projects are excluded " +
             "from anytime — the project row represents them; someday lists each group's " +
             "project rows before its to-dos. Flat views (today/inbox/upcoming/logbook/trash) " +
@@ -224,10 +355,12 @@ export function createThingsMcpServer(options = {}) {
             "anytime/someday always return every group and cap per block instead — " +
             `area_limit (default ${AREA_PREVIEW_LIMIT}) per area block, and on anytime ` +
             `project_limit (default ${PROJECT_PREVIEW_LIMIT}) per project block. ` +
-            "all: true lifts every cap; the result's second block reports the counts.",
+            "all: true lifts every cap; the result's second block reports the counts. " +
+            OMIT_EMPTY_NOTE,
         inputSchema: {
             view: z.enum(["today", "inbox", "anytime", "upcoming", "someday", "logbook", "trash"]),
             ...tagFilterShape,
+            evening: z.boolean().optional().describe("today only: show only the This Evening section"),
             show_active_project_items: z
                 .union([z.boolean(), z.number().int().min(1)])
                 .optional()
@@ -268,7 +401,17 @@ export function createThingsMcpServer(options = {}) {
                 .describe("show everything (flat views: no row limit; anytime/someday: no per-block caps)"),
         },
         annotations: READ_ONLY,
-    }, async (args) => guard(() => {
+    }, async (args) => readGuard(() => {
+        // Tag-conflict AND overdue-applicability both derive from the shared
+        // contract: read_view honors overdue only on today/inbox/anytime/someday
+        // (the current-work views), matching FILTER_CONTRACT.
+        const validated = validateViewArgs(args.view, { ...tagPresence(args), overdue: args.overdue }, {
+            untaggedConflict: MCP_UNTAGGED_CONFLICT,
+            overdueRejected: `overdue applies to today/inbox/anytime/someday, not ${args.view}`,
+            overdueStatusWiden: "",
+        });
+        if (!validated.ok)
+            return usage(validated.message);
         // show_active_project_items is the preferred name; active_project_items
         // stays accepted as a compatibility alias.
         const showActiveProjectItems = args.show_active_project_items ?? args.active_project_items;
@@ -283,6 +426,9 @@ export function createThingsMcpServer(options = {}) {
         if (args.view !== "someday" && showActiveProjectItems !== undefined) {
             return usage("show_active_project_items applies only to someday");
         }
+        if (args.view !== "today" && args.evening === true) {
+            return usage(`evening applies only to today, not ${args.view}`);
+        }
         if (args.view === "someday" && args.project_limit !== undefined) {
             return usage("project_limit does not apply to someday — pass a number as show_active_project_items " +
                 "to cap that section's project lists");
@@ -296,63 +442,63 @@ export function createThingsMcpServer(options = {}) {
             return usage("pass at most one of area_limit/project_limit / all");
         }
         const c = getClient();
-        const filter = {
-            ...(args.tag !== undefined && { tag: args.tag }),
-            ...(args.exact_tag === true && { exactTag: true }),
-        };
+        const filter = validated.filter;
         switch (args.view) {
             case "today": {
-                const { data, pagination } = paginateToday(c.read.today(filter), limit);
-                return paginatedResult(data, pagination);
+                const { view, truncation } = c.read.today({
+                    ...filter,
+                    ...(args.evening === true && { eveningOnly: true }),
+                    limit,
+                });
+                return truncatedResult(view, truncation);
             }
             case "inbox": {
-                const { data, pagination } = paginateList(c.read.inbox(filter), limit);
-                return paginatedResult(data, pagination);
+                const { items, truncation } = c.read.inbox({ ...filter, limit });
+                return truncatedResult(items, truncation);
             }
             case "anytime": {
-                const limits = { area: areaLimit, project: projectLimit };
-                const { data, grouped } = previewSections(c.read.anytime(filter), limits);
-                return groupedResult(data, grouped);
+                const { view, grouped } = c.read.anytime({ ...filter, areaLimit, projectLimit });
+                return groupedResult(view, grouped);
             }
             case "upcoming": {
-                const { data, pagination } = paginateList(c.read.upcoming({
+                const { items, truncation } = c.read.upcoming({
                     ...filter,
                     ...(args.horizon !== undefined && { horizon: args.horizon }),
-                }), limit);
-                return paginatedResult(data, pagination);
+                    limit,
+                });
+                return truncatedResult(items, truncation);
             }
             case "someday": {
                 const active = showActiveProjectItems;
                 if (typeof active === "number" && args.all === true) {
                     return usage("pass at most one of a numeric show_active_project_items / all");
                 }
-                const limits = {
-                    area: areaLimit,
-                    // true = every item per project; a number caps each list.
-                    project: typeof active === "number" ? active : null,
-                };
-                const { data, grouped } = previewSomedaySections(c.read.someday({
+                const { view, grouped } = c.read.someday({
                     ...filter,
                     ...((active === true || typeof active === "number") && {
                         activeProjectItems: true,
                     }),
-                }), limits);
-                return groupedResult(data, grouped);
+                    areaLimit,
+                    // true = every item per project; a number caps each list.
+                    projectLimit: typeof active === "number" ? active : null,
+                });
+                return groupedResult(view, grouped);
             }
             case "logbook": {
-                const { data, pagination } = paginateList(c.read.logbook({ ...filter, limit: null }), limit);
-                return paginatedResult(data, pagination);
+                const { items, truncation } = c.read.logbook({ ...filter, limit });
+                return truncatedResult(items, truncation);
             }
             case "trash": {
-                const { data, pagination } = paginateList(c.read.trash({ limit: null }), limit);
-                return paginatedResult(data, pagination);
+                const { items, truncation } = c.read.trash({ limit });
+                return truncatedResult(items, truncation);
             }
         }
     }));
     server.registerTool("search", {
         description: "Find items by title/notes substring. Returns open, untrashed items by default; " +
             "include more with logged/trashed/all. Scope with project/area/tag — scope " +
-            "references must name existing items.",
+            "references must name existing items. " +
+            OMIT_EMPTY_NOTE,
         inputSchema: {
             query: z.string(),
             ...tagFilterShape,
@@ -374,33 +520,48 @@ export function createThingsMcpServer(options = {}) {
             limit: z.number().int().min(1).optional().describe(LIMIT_DESC),
         },
         annotations: READ_ONLY,
-    }, async (args) => guard(() => {
+    }, async (args) => readGuard(() => {
+        // Tag-conflict AND the overdue/status-widening incompatibility both
+        // derive from the shared contract (search: statusWidening = true).
+        const validated = validateViewArgs("search", {
+            ...tagPresence(args),
+            overdue: args.overdue,
+            logged: args.logged,
+            trashed: args.trashed,
+            all: args.all,
+        }, {
+            untaggedConflict: MCP_UNTAGGED_CONFLICT,
+            overdueRejected: "overdue does not apply to search",
+            overdueStatusWiden: "overdue lists open items; it does not combine with logged/trashed/all",
+        });
+        if (!validated.ok)
+            return usage(validated.message);
         const limit = resolveLimit(args);
         if (limit === "conflict")
             return usage("pass at most one of limit / all");
-        const { data, pagination } = paginateList(getClient().read.search(args.query, {
-            limit: null,
-            ...(args.tag !== undefined && { tag: args.tag }),
-            ...(args.exact_tag === true && { exactTag: true }),
+        const { items, truncation } = getClient().read.search(args.query, {
+            limit,
+            ...validated.filter,
             ...(args.project !== undefined && { project: args.project }),
             ...(args.area !== undefined && { area: args.area }),
             ...(args.type !== undefined && { type: args.type }),
             ...(args.logged === true && { logged: true }),
             ...(args.trashed === true && { trashed: true }),
             ...(args.all === true && { all: true }),
-        }), limit);
-        return paginatedResult(data, pagination);
+        });
+        return truncatedResult(items, truncation);
     }));
     server.registerTool("changes_since", {
         description: "List items created or modified since a moment — including trashed, logged, and " +
             "repeating items (inspect each item's fields to tell them apart). Edits to tags, " +
-            "areas, and checklist items do not mark the containing item as modified.",
+            "areas, and checklist items do not mark the containing item as modified. " +
+            OMIT_EMPTY_NOTE,
         inputSchema: {
             since: z.string().describe("ISO date-time, e.g. 2026-07-06T08:00:00"),
             ...limitShape,
         },
         annotations: READ_ONLY,
-    }, async (args) => guard(() => {
+    }, async (args) => readGuard(() => {
         const limit = resolveLimit(args);
         if (limit === "conflict")
             return usage("pass at most one of limit / all");
@@ -408,34 +569,54 @@ export function createThingsMcpServer(options = {}) {
         if (Number.isNaN(since.getTime())) {
             return usage(`since is not a parseable date: ${args.since}`);
         }
-        const { data, pagination } = paginateList(getClient().read.changes({ since, limit: null }), limit);
-        return paginatedResult(data, pagination);
+        const { items, truncation } = getClient().read.changes({ since, limit });
+        return truncatedResult(items, truncation);
     }));
     server.registerTool("get_item", {
         description: "Full detail for one item by uuid: notes, schedule, reminder, deadline, tags " +
             "(direct and inherited), checklist with per-item state, repeat schedule, and its " +
-            "project/area/heading.",
+            "project/area/heading. " +
+            OMIT_EMPTY_NOTE,
         inputSchema: { uuid: z.string() },
         annotations: READ_ONLY,
-    }, async (args) => guard(() => {
+    }, async (args) => readGuard(() => {
         const item = getClient().read.byUuid(args.uuid);
         return item === null
-            ? errorResult({ code: "not-found", message: `no record with uuid ${args.uuid}` })
-            : jsonResult(item);
+            ? errorResult({ code: "not-found", message: noUuidMatch("item", args.uuid) })
+            : readResult(item);
     }));
     server.registerTool("get_project", {
-        description: "One project's full contents: metadata plus its to-dos grouped under their headings.",
-        inputSchema: { uuid: z.string().describe("Project uuid or unique name") },
+        description: "One project's full contents: metadata plus its to-dos grouped under their headings. " +
+            "The tag filters keep only the child to-dos matching by their own tags (a heading left " +
+            "with none is dropped). " +
+            OMIT_EMPTY_NOTE,
+        inputSchema: {
+            uuid: z.string().describe("Project uuid or unique name"),
+            ...tagOnlyShape,
+            overdue: z
+                .boolean()
+                .optional()
+                .describe("Keep only child to-dos past their deadline (due today is not overdue); headings left empty are dropped"),
+        },
         annotations: READ_ONLY,
-    }, async (args) => guard(() => jsonResult(getClient().read.projectView(args.uuid))));
+    }, async (args) => readGuard(() => {
+        if (tagFlagConflict(tagPresence(args)))
+            return usage(MCP_UNTAGGED_CONFLICT);
+        return readResult(getClient().read.projectView(args.uuid, {
+            overdue: args.overdue === true,
+            ...tagFilterFields(tagPresence(args)),
+        }));
+    }));
     server.registerTool("get_area", {
         description: "One area's contents: metadata plus its direct to-dos (active first), its " +
-            "projects in sidebar order, later (scheduled/repeating/someday), and logged items. " +
+            "projects in canonical order, later (scheduled/repeating/someday), and logged items. " +
             `The project-rows and direct-to-dos sections are capped at ${AREA_PREVIEW_LIMIT} each ` +
             "by default (project_limit / area_limit adjust them; all: true lifts both); the " +
-            "second result block reports the counts.",
+            "second result block reports the counts. " +
+            OMIT_EMPTY_NOTE,
         inputSchema: {
             ref: z.string().describe("Area uuid or unique name"),
+            ...tagOnlyShape,
             area_limit: z
                 .number()
                 .int()
@@ -448,28 +629,70 @@ export function createThingsMcpServer(options = {}) {
                 .min(1)
                 .optional()
                 .describe(`maximum project rows to return (default ${AREA_PREVIEW_LIMIT})`),
+            overdue: z
+                .boolean()
+                .optional()
+                .describe("Keep only rows (loose to-dos AND child projects) whose own deadline is past (due today is not overdue); no descent into project contents"),
             all: z.boolean().optional().describe("return both sections in full (no caps)"),
         },
         annotations: READ_ONLY,
-    }, async (args) => guard(() => {
+    }, async (args) => readGuard(() => {
+        if (tagFlagConflict(tagPresence(args)))
+            return usage(MCP_UNTAGGED_CONFLICT);
         const areaLimit = resolveCap(args.area_limit, args.all, AREA_PREVIEW_LIMIT);
         const projectLimit = resolveCap(args.project_limit, args.all, AREA_PREVIEW_LIMIT);
         if (areaLimit === "conflict" || projectLimit === "conflict") {
             return usage("pass at most one of area_limit/project_limit / all");
         }
-        const limits = { area: areaLimit, project: projectLimit };
-        const { data, grouped } = capAreaSections(getClient().read.areaView(args.ref), limits);
-        return groupedResult(data, grouped);
+        const { view, grouped } = getClient().read.areaView(args.ref, {
+            overdue: args.overdue === true,
+            ...tagFilterFields(tagPresence(args)),
+            areaLimit,
+            projectLimit,
+        });
+        return groupedResult(view, grouped);
     }));
     server.registerTool("list_collections", {
         description: "List every project, area, or tag (tags include their parent-tag nesting). Use to " +
-            "refresh the inventory summarized in the server instructions.",
-        inputSchema: { kind: z.enum(["projects", "areas", "tags"]) },
+            "refresh the inventory summarized in the server instructions. The tag filters scope " +
+            "the projects list by each project's own tags (areas/tags reject them). " +
+            OMIT_EMPTY_NOTE,
+        inputSchema: {
+            kind: z.enum(["projects", "areas", "tags"]),
+            ...tagOnlyShape,
+            overdue: z
+                .boolean()
+                .optional()
+                .describe("projects only: keep only projects past their deadline (due today is not overdue); areas/tags carry no deadline and reject it"),
+        },
         annotations: READ_ONLY,
-    }, async (args) => guard(() => {
+    }, async (args) => readGuard(() => {
         const c = getClient();
-        return jsonResult(args.kind === "projects"
-            ? c.read.projects()
+        // areas/tags are not dated entities and have no per-row tag list to
+        // filter — overdue and the tag filters are vacuous there, rejected
+        // fail-closed (the same style read_view uses for the wrong views). The
+        // decision derives from the contract: only the `projects` list carries
+        // a deadline (overdue) and per-row (inheritance-inclusive) tags; the
+        // `areas` list rejects both, and `tags` has no contract row.
+        const kindSpec = args.kind === "projects"
+            ? FILTER_CONTRACT.projects
+            : args.kind === "areas"
+                ? FILTER_CONTRACT.areas
+                : null;
+        if (args.overdue === true && (kindSpec === null || !kindSpec.overdue)) {
+            return usage(`overdue applies only to projects, not ${args.kind}`);
+        }
+        if ((kindSpec === null || kindSpec.tag === "rejected") &&
+            (hasTagPresence(tagPresence(args)) || args.untagged === true)) {
+            return usage(`the tag filters apply only to projects, not ${args.kind}`);
+        }
+        if (tagFlagConflict(tagPresence(args)))
+            return usage(MCP_UNTAGGED_CONFLICT);
+        return readResult(args.kind === "projects"
+            ? c.read.projects({
+                overdue: args.overdue === true,
+                ...tagFilterFields(tagPresence(args)),
+            })
             : args.kind === "areas"
                 ? c.read.areas()
                 : c.read.tags());
@@ -479,7 +702,7 @@ export function createThingsMcpServer(options = {}) {
     server.registerTool("add_todo", {
         description: "Create a to-do and return its uuid. Optionally schedule it, set a reminder or " +
             "deadline, tag it, give it a checklist, and place it in a project or area " +
-            "(optionally under an existing heading). Tags must name existing tags. A reminder " +
+            "(optionally under an existing heading). A reminder " +
             "requires when = today, evening, or a date. Adding into a completed or canceled " +
             "project reopens that project — pass acknowledge_project_reopen to confirm.",
         inputSchema: {
@@ -488,7 +711,7 @@ export function createThingsMcpServer(options = {}) {
             when: whenSchema,
             reminder: z.string().optional().describe(REMINDER_FORMAT),
             deadline: z.string().optional().describe(DATE_FORMAT),
-            tags: z.array(z.string()).optional().describe("Existing tag names"),
+            tags: z.array(z.string()).optional().describe(`Tags — ${TAG_REF_FORMAT}`),
             checklist_items: z.array(z.string()).optional(),
             project: z.string().optional().describe(`Destination project (${REF_FORMAT})`),
             area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
@@ -497,21 +720,29 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("Confirm adding into a completed/canceled project (this reopens it)"),
+            ...createTagsShape,
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.addTodo({
-        title: args.title,
-        ...(args.notes !== undefined && { notes: args.notes }),
-        ...(args.when !== undefined && { when: args.when }),
-        ...(args.reminder !== undefined && { reminder: args.reminder }),
-        ...(args.deadline !== undefined && { deadline: args.deadline }),
-        ...(args.tags !== undefined && { tags: args.tags }),
-        ...(args.checklist_items !== undefined && { checklistItems: args.checklist_items }),
-        ...(args.project !== undefined && { project: containerRef(args.project) }),
-        ...(args.area !== undefined && { area: containerRef(args.area) }),
-        ...(args.heading !== undefined && { heading: args.heading }),
-    }, writeOptions(args)))));
+    }, async (args) => guard(async () => {
+        const sugar = splitWhenSugar(args.when, args.reminder !== undefined, MCP_WHEN_LABELS);
+        if (sugar.kind === "error")
+            return usage(sugar.message);
+        const when = sugar.kind === "split" ? sugar.when : args.when;
+        const reminder = sugar.kind === "split" ? sugar.reminder : args.reminder;
+        return mutationResult(await getClient().write.addTodo({
+            title: args.title,
+            ...(args.notes !== undefined && { notes: args.notes }),
+            ...(when !== undefined && { when: when }),
+            ...(reminder !== undefined && { reminder }),
+            ...(args.deadline !== undefined && { deadline: args.deadline }),
+            ...(args.tags !== undefined && { tags: args.tags }),
+            ...(args.checklist_items !== undefined && { checklistItems: args.checklist_items }),
+            ...(args.project !== undefined && { project: containerRef(args.project) }),
+            ...(args.area !== undefined && { area: containerRef(args.area) }),
+            ...(args.heading !== undefined && { heading: args.heading }),
+        }, writeOptions(args)));
+    }));
     server.registerTool("update_todo", {
         description: "Update a to-do's title, notes, schedule, reminder, or deadline. " +
             "append_notes/prepend_notes add a line to the existing notes (exclusive with " +
@@ -545,13 +776,18 @@ export function createThingsMcpServer(options = {}) {
         if (args.deadline !== undefined && args.clear_deadline === true) {
             return usage("pass at most one of deadline / clear_deadline");
         }
+        const sugar = splitWhenSugar(args.when, args.reminder !== undefined, MCP_WHEN_LABELS);
+        if (sugar.kind === "error")
+            return usage(sugar.message);
+        const when = sugar.kind === "split" ? sugar.when : args.when;
+        const reminder = sugar.kind === "split" ? sugar.reminder : args.reminder;
         return mutationResult(await getClient().write.updateTodo(args.uuid, {
             ...(args.title !== undefined && { title: args.title }),
             ...(args.notes !== undefined && { notes: args.notes }),
             ...(args.append_notes !== undefined && { appendNotes: args.append_notes }),
             ...(args.prepend_notes !== undefined && { prependNotes: args.prepend_notes }),
-            ...(args.when !== undefined && { when: args.when }),
-            ...(args.reminder !== undefined && { reminder: args.reminder }),
+            ...(when !== undefined && { when: when }),
+            ...(reminder !== undefined && { reminder }),
             ...(args.clear_reminder === true && { reminder: null }),
             ...(args.deadline !== undefined && { deadline: args.deadline }),
             ...(args.clear_deadline === true && { deadline: null }),
@@ -618,11 +854,12 @@ export function createThingsMcpServer(options = {}) {
     server.registerTool("set_tags", {
         description: "Replace or extend a to-do's or project's tags. mode 'replace' (default) sets exactly " +
             "the given list — an empty list removes all tags; mode 'add' merges with the current " +
-            "tags. Tags must name existing tags (create them first with add_tag).",
+            "tags. Tags must exist unless create_tags is set (or create them first with add_tag).",
         inputSchema: {
             uuid: z.string(),
-            tags: z.array(z.string()).describe("Existing tag names"),
+            tags: z.array(z.string()).describe(`Tags — ${TAG_REF_FORMAT}`),
             mode: z.enum(["replace", "add"]).optional().describe("Default: replace"),
+            ...createTagsShape,
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
@@ -847,6 +1084,265 @@ export function createThingsMcpServer(options = {}) {
             ? jsonResult(r)
             : mutationResult(r.heading);
     }));
+    // -------------------------------------------- GUI-driven (Accessibility)
+    const driveGuiShape = {
+        dangerously_drive_gui: z
+            .boolean()
+            .optional()
+            .describe("Required: this drives the local Things app through its accessibility interface to " +
+            "make a change the app offers nowhere else. It briefly interacts with the app's UI " +
+            "on the machine running this server, and must be turned on first with `things config " +
+            "set ui-enabled true`. Intended for a dedicated always-on Mac."),
+    };
+    const WEEKDAY_ENUM = z.enum([
+        "sunday",
+        "monday",
+        "tuesday",
+        "wednesday",
+        "thursday",
+        "friday",
+        "saturday",
+    ]);
+    // The base rule (also used by create_repeating_project, which stays minimal —
+    // its own `deadline` is the project's due DATE, not the repeat's Add-deadlines).
+    const baseRepeatShape = {
+        frequency: z.enum(["daily", "weekly", "monthly", "yearly"]).describe("How often it repeats"),
+        interval: z.number().int().min(1).max(99).describe("Every N units (1–99)"),
+    };
+    const repeatRuleShape = {
+        ...baseRepeatShape,
+        after_completion: z
+            .boolean()
+            .optional()
+            .describe("Repeat N units AFTER each occurrence is completed, instead of on a fixed schedule"),
+        weekdays: z.array(WEEKDAY_ENUM).optional().describe("Weekly only: the weekdays it repeats on"),
+        monthly_day: z
+            .union([z.number().int(), z.literal("last")])
+            .optional()
+            .describe('Monthly/yearly only: a day of the month (1–31, or "last")'),
+        monthly_weekday: WEEKDAY_ENUM.optional().describe("Monthly/yearly only: a weekday for an nth-weekday rule (with monthly_ordinal)"),
+        monthly_ordinal: z
+            .union([z.number().int(), z.literal("last")])
+            .optional()
+            .describe('Monthly/yearly only: which weekday (1–5, or "last") with monthly_weekday'),
+        yearly_month: z
+            .number()
+            .int()
+            .min(1)
+            .max(12)
+            .optional()
+            .describe("Yearly only: the month (1–12)"),
+        ends_after: z.number().int().optional().describe("Stop after N occurrences"),
+        ends_on: z.string().optional().describe("YYYY-MM-DD — stop after this date"),
+        reminder: z.string().optional().describe("HH:mm — a reminder time on each occurrence"),
+        deadline: z.boolean().optional().describe("Give each occurrence a deadline"),
+        start_days_earlier: z
+            .number()
+            .int()
+            .optional()
+            .describe("With deadline: start each occurrence N days before its deadline"),
+    };
+    // oxlint-disable-next-line consistent-function-scoping -- kept beside repeatRuleShape it mirrors
+    const repeatExtras = (a, frequency) => {
+        const fields = {};
+        if (a.after_completion === true)
+            fields.afterCompletion = true;
+        if (a.weekdays !== undefined)
+            fields.weekdays = a.weekdays;
+        const anchor = a.monthly_day !== undefined
+            ? { day: a.monthly_day }
+            : a.monthly_weekday !== undefined || a.monthly_ordinal !== undefined
+                ? { weekday: a.monthly_weekday, ordinal: a.monthly_ordinal }
+                : undefined;
+        if (frequency === "monthly" && anchor !== undefined)
+            fields.monthly = anchor;
+        if (frequency === "yearly" && (a.yearly_month !== undefined || anchor !== undefined)) {
+            fields.yearly = { month: a.yearly_month, ...anchor };
+        }
+        if (a.ends_after !== undefined)
+            fields.ends = { kind: "after", count: a.ends_after };
+        else if (a.ends_on !== undefined)
+            fields.ends = { kind: "on-date", date: a.ends_on };
+        if (a.reminder !== undefined)
+            fields.reminder = a.reminder;
+        if (a.deadline === true)
+            fields.deadline = true;
+        if (a.start_days_earlier !== undefined)
+            fields.startDaysEarlier = a.start_days_earlier;
+        return fields;
+    };
+    server.registerTool("make_repeating", {
+        description: "Turn a plain to-do into a repeating one. This REPLACES the to-do with a new recurring " +
+            "series — the original disappears and a fresh repeating item takes its place, so it " +
+            "cannot be undone. Set the frequency and interval, and optionally the weekday set, " +
+            "monthly/yearly day, end bound, reminders, or deadline. Returns the new item's uuid.",
+        inputSchema: {
+            uuid: z.string().describe("The to-do to make repeating"),
+            ...repeatRuleShape,
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: DESTRUCTIVE,
+    }, async (args) => guard(async () => mutationResult(await getClient().write.run("todo.make-repeating", {
+        uuid: args.uuid,
+        frequency: args.frequency,
+        interval: args.interval,
+        ...repeatExtras(args, args.frequency),
+    }, writeOptions(args)))));
+    server.registerTool("reschedule_repeat", {
+        description: "Change a repeating to-do's rule in place, keeping the same item. Set the frequency and " +
+            "interval, and optionally the weekday set, monthly/yearly day, end bound, reminders, or " +
+            "deadline. This can be undone — it restores the previous rule.",
+        inputSchema: {
+            uuid: z.string().describe("The repeating to-do to reschedule"),
+            ...repeatRuleShape,
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: NON_DESTRUCTIVE,
+    }, async (args) => guard(async () => mutationResult(await getClient().write.run("todo.reschedule-repeat", {
+        uuid: args.uuid,
+        frequency: args.frequency,
+        interval: args.interval,
+        ...repeatExtras(args, args.frequency),
+    }, writeOptions(args)))));
+    server.registerTool("set_repeat_state", {
+        description: "Pause or resume a repeating to-do. 'pause' stops it spawning new occurrences but keeps " +
+            "its rule; 'resume' starts it again. The two are inverses of each other.",
+        inputSchema: {
+            uuid: z.string().describe("The repeating to-do"),
+            state: z.enum(["pause", "resume"]),
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: NON_DESTRUCTIVE,
+    }, async (args) => guard(async () => {
+        const op = args.state === "pause" ? "todo.pause-repeat" : "todo.resume-repeat";
+        return mutationResult(await getClient().write.run(op, { uuid: args.uuid }, writeOptions(args)));
+    }));
+    server.registerTool("reschedule_project_repeat", {
+        description: "Change a repeating project's rule in place, keeping the same project. Set the frequency " +
+            "and interval, and optionally the weekday set, monthly/yearly day, end bound, reminders, " +
+            "or deadline. This can be undone — it restores the previous rule.",
+        inputSchema: {
+            uuid: z.string().describe(`The repeating project to reschedule (${REF_FORMAT})`),
+            ...repeatRuleShape,
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: NON_DESTRUCTIVE,
+    }, async (args) => guard(async () => mutationResult(await getClient().write.run("project.reschedule-repeat", {
+        uuid: args.uuid,
+        frequency: args.frequency,
+        interval: args.interval,
+        ...repeatExtras(args, args.frequency),
+    }, writeOptions(args)))));
+    server.registerTool("set_project_repeat_state", {
+        description: "Pause or resume a repeating project. 'pause' stops it spawning new occurrences but keeps " +
+            "its rule; 'resume' starts it again. The two are inverses of each other.",
+        inputSchema: {
+            uuid: z.string().describe(`The repeating project (${REF_FORMAT})`),
+            state: z.enum(["pause", "resume"]),
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: NON_DESTRUCTIVE,
+    }, async (args) => guard(async () => {
+        const op = args.state === "pause" ? "project.pause-repeat" : "project.resume-repeat";
+        return mutationResult(await getClient().write.run(op, { uuid: args.uuid }, writeOptions(args)));
+    }));
+    server.registerTool("reorder_area", {
+        description: "Move an area to a new position in the area order. Give the area plus exactly one " +
+            "destination: before/after another area, or position first/last. The move is made by " +
+            "driving the Things window with the pointer — the app comes to the front and the " +
+            "sidebar may scroll while the area is dragged; the area's projects and to-dos are " +
+            "untouched. Area references are a uuid or a unique name.",
+        inputSchema: {
+            target: z.string().describe("The area to move (uuid or unique name)"),
+            before: z
+                .string()
+                .optional()
+                .describe("Place it immediately above this area (uuid or unique name)"),
+            after: z
+                .string()
+                .optional()
+                .describe("Place it immediately below this area (uuid or unique name)"),
+            position: z
+                .enum(["first", "last"])
+                .optional()
+                .describe("Move it to the top or bottom of the area list"),
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: NON_DESTRUCTIVE,
+    }, async (args) => guard(async () => mutationResult(await getClient().write.run("area.reorder", {
+        target: args.target,
+        ...(args.before !== undefined && { before: args.before }),
+        ...(args.after !== undefined && { after: args.after }),
+        ...(args.position !== undefined && { position: args.position }),
+    }, writeOptions(args)))));
+    server.registerTool("make_project_repeating", {
+        description: "Turn an existing project into a repeating one. This REPLACES the project with a new " +
+            "recurring series — the original disappears and a fresh repeating project takes its place " +
+            "(its area is kept), so it cannot be undone. An area-less project scheduled for Anytime is " +
+            "moved to Someday first (a cleanup-free intermediate step, shown by dry_run). Set the " +
+            "frequency and interval, and optionally the weekday set, monthly/yearly day, end bound, " +
+            "reminders, or deadline. Returns the new project's uuid.",
+        inputSchema: {
+            uuid: z.string().describe(`The project to make repeating (${REF_FORMAT})`),
+            ...repeatRuleShape,
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: DESTRUCTIVE,
+    }, async (args) => guard(async () => mutationResult(await getClient().write.makeRepeatingProject(args.uuid, {
+        frequency: args.frequency,
+        interval: args.interval,
+        ...repeatExtras(args, args.frequency),
+    }, writeOptions(args)))));
+    server.registerTool("create_repeating_project", {
+        description: "Create a project and make it repeating in one call. TWO operations: the project is " +
+            "created first and PERSISTS even if the make-repeating step refuses; then it is promoted " +
+            "(which drives the GUI). Give an area to place it, or omit it to create in Someday. Only a " +
+            "frequency and an interval are supported. Returns the new repeating project's uuid.",
+        inputSchema: {
+            title: z.string(),
+            notes: z.string().optional(),
+            area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
+            deadline: z.string().optional().describe(DATE_FORMAT),
+            todos: z.array(z.string()).optional().describe("Initial child to-do titles"),
+            ...baseRepeatShape,
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: DESTRUCTIVE,
+    }, async (args) => guard(async () => mutationResult(await getClient().write.createRepeatingProject({
+        title: args.title,
+        ...(args.notes !== undefined && { notes: args.notes }),
+        ...(args.area !== undefined && { area: containerRef(args.area) }),
+        ...(args.deadline !== undefined && { deadline: args.deadline }),
+        ...(args.todos !== undefined && { todos: args.todos }),
+        frequency: args.frequency,
+        interval: args.interval,
+    }, writeOptions(args)))));
+    server.registerTool("convert_to_project", {
+        description: "Convert a to-do or a heading into a project. This REPLACES the original with a new " +
+            "project (a converted to-do keeps its notes; a converted heading is promoted alongside " +
+            "its project and its to-dos move under the new project). The original is gone and this " +
+            "cannot be undone. Returns the new project's uuid.",
+        inputSchema: {
+            uuid: z.string().describe("The to-do or heading to convert"),
+            ...driveGuiShape,
+            ...dryRunShape,
+        },
+        annotations: DESTRUCTIVE,
+    }, async (args) => guard(async () => {
+        const item = getClient().read.byUuid(args.uuid);
+        if (item === null)
+            throw new RangeError(`no item with uuid ${args.uuid}`);
+        const op = item.type === "heading" ? "heading.convert-to-project" : "todo.convert-to-project";
+        return mutationResult(await getClient().write.run(op, { uuid: args.uuid }, writeOptions(args)));
+    }));
     server.registerTool("duplicate_item", {
         description: "Duplicate a to-do or project and return the copy's uuid; a duplicated project " +
             "includes its children. Not available for repeating items.",
@@ -887,7 +1383,7 @@ export function createThingsMcpServer(options = {}) {
             "clear_reminder works while the project is scheduled for today or this evening; a " +
             "reminder on a future date can only be changed, not cleared.",
         inputSchema: {
-            uuid: z.string(),
+            uuid: z.string().describe(`The project to update (${REF_FORMAT})`),
             title: z.string().optional(),
             notes: z.string().optional().describe("Replaces the whole notes body"),
             append_notes: z.string().optional(),
@@ -931,7 +1427,7 @@ export function createThingsMcpServer(options = {}) {
             "canceled project; its children stay completed/canceled unless restore_children " +
             "also reopens the ones that were resolved together with the project.",
         inputSchema: {
-            uuid: z.string().describe("Project uuid"),
+            uuid: z.string().describe(`The project (${REF_FORMAT})`),
             status: z.enum(["completed", "canceled", "open"]),
             children: z
                 .enum(["require-resolved", "auto-complete", "auto-cancel"])
@@ -976,7 +1472,7 @@ export function createThingsMcpServer(options = {}) {
         description: "Move a project into an area, or detach it from its current area. Pass exactly " +
             "one of area / detach. The project's status and schedule are unaffected.",
         inputSchema: {
-            uuid: z.string().describe("Project uuid"),
+            uuid: z.string().describe(`The project to move (${REF_FORMAT})`),
             area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
             detach: z.boolean().optional().describe("Remove the current area assignment"),
             ...dryRunShape,
@@ -993,20 +1489,26 @@ export function createThingsMcpServer(options = {}) {
     }));
     // ----------------------------------------------------------------- areas
     server.registerTool("add_area", {
-        description: "Create an area. Tags, when given, must name existing tags.",
+        description: "Create an area, optionally tagged. Tags must exist unless create_tags is set.",
         inputSchema: {
             title: z.string(),
-            tags: z.array(z.string()).optional().describe("Existing tag names"),
+            tags: z.array(z.string()).optional().describe(`Tags — ${TAG_REF_FORMAT}`),
+            ...createTagsShape,
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.addArea({ title: args.title, ...(args.tags !== undefined && { tags: args.tags }) }, writeOptions(args)))));
     server.registerTool("update_area", {
-        description: "Rename an area and/or replace its tags (the full set; tags must name existing tags).",
+        description: "Rename an area and/or replace its tags (the full set). Tags must exist unless " +
+            "create_tags is set.",
         inputSchema: {
             target: z.string().describe(`Area to update (${REF_FORMAT})`),
             title: z.string().optional().describe("New name"),
-            tags: z.array(z.string()).optional().describe("Existing tag names (full replacement)"),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe(`Tags (full replacement) — ${TAG_REF_FORMAT}`),
+            ...createTagsShape,
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
@@ -1133,10 +1635,10 @@ export function createThingsMcpServer(options = {}) {
                 params: z.record(z.string(), z.unknown()),
                 options: z
                     .object({
-                    acknowledgeChecklistReset: z.boolean().optional(),
-                    acknowledgeProjectReopen: z.boolean().optional(),
-                    dangerouslyPermanent: z.boolean().optional(),
-                    acknowledgeTagSubtree: z.boolean().optional(),
+                    acknowledge_checklist_reset: z.boolean().optional(),
+                    acknowledge_project_reopen: z.boolean().optional(),
+                    dangerously_permanent: z.boolean().optional(),
+                    acknowledge_tag_subtree: z.boolean().optional(),
                 })
                     .optional(),
             }))
@@ -1146,10 +1648,29 @@ export function createThingsMcpServer(options = {}) {
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        const results = await getClient().write.batch(args.ops, {
+        // Map each op's snake_case acknowledgements into the batch engine's
+        // option names, and apply the process-wide disruption ceiling — batch
+        // takes it per-op, and MCP exposes no per-op override, so it is uniform.
+        const ceiling = options.maxDisruption;
+        const ops = args.ops.map((op) => {
+            const o = op.options;
+            const opts = {
+                ...(o?.acknowledge_checklist_reset === true && { acknowledgeChecklistReset: true }),
+                ...(o?.acknowledge_project_reopen === true && { acknowledgeProjectReopen: true }),
+                ...(o?.dangerously_permanent === true && { dangerouslyPermanent: true }),
+                ...(o?.acknowledge_tag_subtree === true && { acknowledgeTagSubtree: true }),
+                ...(ceiling !== undefined && { maxDisruption: ceiling }),
+            };
+            return {
+                op: op.op,
+                params: op.params,
+                ...(Object.keys(opts).length > 0 && { options: opts }),
+            };
+        });
+        const results = await getClient().write.batch(ops, {
             ...(args.dry_run === true && { dryRun: true }),
             ...(args.fail_fast === true && { failFast: true }),
-            actor: "mcp",
+            actor: mcpActor(),
         });
         return jsonResult(results);
     }));
@@ -1157,7 +1678,7 @@ export function createThingsMcpServer(options = {}) {
         description: "Reorder items within Today, This Evening, the Inbox, Someday (loose to-dos or " +
             "area-less someday projects — one kind per call), a " +
             "project's to-dos, a project's headings (scope=headings — children move with " +
-            "their heading), an area, or the top-level sidebar projects (scope=projects — " +
+            "their heading), an area, or the top-level projects (scope=projects — " +
             "each project takes a brief someday/anytime round-trip) — the given uuids move " +
             "to the TOP in the given order; unlisted items keep their relative order below. " +
             "Today/inbox/someday/project/headings/area ordering must first be enabled once " +
@@ -1191,24 +1712,59 @@ export function createThingsMcpServer(options = {}) {
         ...(args.strategy !== undefined && { strategy: args.strategy }),
     }, writeOptions(args)))));
     server.registerTool("undo", {
-        description: "Undo the last N changes made through this interface, newest first (changes made " +
-            "directly in the Things app cannot be undone here). Some changes cannot be " +
-            "reversed — permanent deletions, or changes whose prior state is unknown — and are " +
-            "reported as irreversible; a to-do brought back from an undone delete returns to " +
-            "the Inbox without its schedule. Undoing the creation of an area or tag deletes it " +
-            "permanently — requires dangerously_permanent.",
+        description: "Undo the last N changes, newest first (changes made directly in the Things app " +
+            "cannot be undone here). By default this undoes only changes made through THIS " +
+            "connection — this client's own writes; it will not touch the user's own edits, or " +
+            'another client\'s, unless you pass by="*" (all authors) or a specific author name; ' +
+            "pass a txn token to undo one exact change. Some changes cannot be reversed — " +
+            "permanent deletions, or changes whose prior state is unknown — and are reported as " +
+            "irreversible; a to-do brought back from an undone delete returns to the Inbox " +
+            "without its schedule. Undoing the creation of an area or tag deletes it " +
+            "permanently — requires dangerously_permanent. An undo is refused when the item " +
+            "changed outside this interface since (its list or project, status, schedule, " +
+            "trashed state, or a field like the title moved) — pass " +
+            "acknowledge_out_of_band_changes to overwrite it anyway.",
         inputSchema: {
             last: z.number().int().min(1).optional().describe("How many to unwind (default 1)"),
+            by: z
+                .string()
+                .optional()
+                .describe('Whose changes to undo: an exact author name, or "*" for everyone. Defaults to ' +
+                "this client's own writes (only changes made through this connection). Matches " +
+                "exactly. Selects WHICH changes to undo, and never a change already undone. Not " +
+                "combinable with txn."),
+            txn: z
+                .string()
+                .optional()
+                .describe("Undo exactly the one change with this undo token (the undoToken field returned " +
+                "by the mutation); immune to interleaving. Not combinable with last/by."),
             dangerously_permanent: z.boolean().optional(),
+            acknowledge_out_of_band_changes: z
+                .boolean()
+                .optional()
+                .describe("Proceed even when the item changed outside this interface since (in the Things app " +
+                "or by another tool) — overwrites whatever the out-of-band change left, instead of " +
+                "refusing."),
             ...dryRunShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
+        if (args.txn !== undefined && (args.last !== undefined || args.by !== undefined)) {
+            return usage("txn cannot be combined with last or by");
+        }
         const items = await getClient().write.undo({
             ...(args.last !== undefined && { last: args.last }),
+            ...(args.txn !== undefined && { txn: args.txn }),
+            // Asymmetric default: agents must not clobber the user's own edits (or
+            // another client's) without explicitly opting in via by:"*". Scoped to
+            // this client's own handshake identity, so each session undoes its own.
+            ...(args.txn === undefined && { by: args.by ?? mcpActor() }),
             ...(args.dry_run === true && { dryRun: true }),
             ...(args.dangerously_permanent === true && { dangerouslyPermanent: true }),
-            actor: "mcp",
+            ...(args.acknowledge_out_of_band_changes === true && {
+                acknowledgeOutOfBandChanges: true,
+            }),
+            actor: mcpActor(),
         });
         return jsonResult(items);
     }));
@@ -1226,8 +1782,10 @@ export function createThingsMcpServer(options = {}) {
     server.registerTool("doctor", {
         description: "Check the environment: whether the Things app and its database are reachable, " +
             "whether changes can be made, any one-time setup still needed (macOS permissions, " +
-            "the app's 'Enable Things URLs' setting), and whether the environment changed since " +
-            "the last successful write, with steps to fix.",
+            "the app's 'Enable Things URLs' setting), whether the environment changed since " +
+            "the last successful write, and a sync-health summary (whether the app is running, how " +
+            "recently the data changed, and — when a Things Cloud account is attached — the last " +
+            "sync attempt), with steps to fix.",
         inputSchema: {
             probe_automation: z
                 .boolean()