amazing-marvin-complete-mcp

update_task

Idempotent

Modify fields on an existing task such as title, note, dates, labels, or sections. Use other tools for category/project moves, priority changes, or marking tasks done.

Instructions

Update fields on an existing TASK via /doc/update (Full Access Token). For categories/projects, use update_category_or_project. For priority, use set_priority. Always complete tasks via mark_done, never here. Strategy-dependent fields (start/end date, planned_week/month, review_date, backburner, orbit, the sections) can be set even when the strategy is disabled in the app — they just are not shown in the UI then. A clock time (Time/taskTime) and the task's reminder fields are set in the APP, not here — an MCP limitation (double-write sync, see set_reminder), NOT a Marvin limitation: Marvin fully supports times on tasks. Note on recurring tasks: never edit recurrence rules here — neither on a generated instance (recurring=true, id 'YYYY-MM-DD') nor on the generator document. Do that editing in the Marvin app. Simple field changes (title, note) on a single instance are fine. Note: Marvin's server can sporadically respond 500 on /doc/update (transient and atomic — no partial write); just retry. But a PERMANENT 500 (persists across retries) means the document does not exist — deleted, or a wrong/never-existing ID (the server responds 500 instead of 404 for missing IDs, verified live 2026-08-29). Fetch a fresh ID via get_categories/get_children.

Input Schema

TableJSON Schema

Name	Required	Description
`day`	No	Schedule on YYYY-MM-DD, 'today', or 'unassigned' to unschedule
`note`	No	New note (replaces the existing one)
`orbit`	No	Orbit strategy: True = put in orbit (verified in the app 2026-08-29: shows in the Orbit view + orbit icon in Today). UNDOCUMENTED field (missing from the official data types)
`title`	No	New title
`item_id`	Yes	Task ID
`due_date`	No	Deadline YYYY-MM-DD, or '' to remove
`end_date`	No	Soft deadline YYYY-MM-DD (Start & End Dates strategy), '' removes
`label_ids`	No	New labels (IDs from get_labels; replaces existing ones, [] removes all)
`parent_id`	No	Move to category/project ID (not validated by the server — a wrong ID yields an orphan, live-tested 2026-08-29; repaired by running FIX_CYCLES() in the app's console)
`backburner`	No	True = put in the backburner, False = take out. NOTE: only effective on an UNSCHEDULED task — set day='unassigned' at the same time; scheduling trumps the flag in the UI (verified in the app 2026-08-29)
`start_date`	No	Start date YYYY-MM-DD, '' removes. Mechanics (verified in the app 2026-08-29): the Start Dates strategy hides BACKBURNER items until their start date — combine with backburner=true and day='unassigned'; a scheduled task is not affected
`review_date`	No	Review date YYYY-MM-DD, '' removes. Verified in the app 2026-08-29: shows in the Review view on the date; the day-view banner additionally requires the Review Alert workflow snippet
`planned_week`	No	Plan into a week: the week's Monday YYYY-MM-DD (Planning Ahead strategy; verified in the app 2026-08-29 — also shows in the month view), '' removes. The app's view: clearing propagates server-side, but with Planning Ahead on (2026-08-29) the task stayed in the month view even after switching views — ask the user to reload the client (F5 in the web app/PWA, restart of the desktop app) before a missing render is taken for an error
`bonus_section`	No	'Essential' or 'Bonus' (bonusStructure strategy), '' removes
`daily_section`	No	Day section 'Morning'/'Afternoon'/'Evening' (dailyStructure strategy), '' removes
`no_auto_orbit`	No	Orbit strategy: True = exempt the task from automatic orbiting (auto-orbit otherwise pulls in scheduled tasks). UNDOCUMENTED field (bool type verified in live data 2026-08-29)
`planned_month`	No	Plan into a month: YYYY-MM (Planning Ahead strategy, verified in the app 2026-08-29), '' removes
`reward_points`	No	Reward points the task AWARDS on completion (coin + points in the list row when the Rewards strategy is on, verified in the app 2026-08-29), 0 removes. Do not set together with isReward
`custom_section`	No	ID of a custom section from strategySettings.customStructure, '' removes
`perma_snooze_time`	No	Hide the task every day until HH:mm (permaSnoozeTime), '' removes. Verified in the app 2026-08-29
`time_block_section`	No	Time block ID (from get_today_time_blocks), '' removes. NOTE: stored, but no visible section link renders in Today even with the strategy active (verified in the app 2026-08-29)
`snooze_until_unix_ms`	No	Snooze the task until unix time in milliseconds (itemSnoozeTime), 0 removes. Verified in the app 2026-08-29: hides from Today AND the category view (the wiki's 'everywhere except the master list' does not hold for the category view)
`time_estimate_minutes`	No	Time estimate in minutes, 0 removes it

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.6.0Sep 12, 2026

changedInput schema / properties / planned_week / description

Previous value: -"Plan into a week: the week's Monday YYYY-MM-DD (Planning Ahead strategy; verified in the app 2026-08-29 — also shows in the month view), '' removes (client cache may linger until a view switch)"New value: +"Plan into a week: the week's Monday YYYY-MM-DD (Planning Ahead strategy; verified in the app 2026-08-29 — also shows in the month view), '' removes. The app's view: clearing propagates server-side, but with Planning Ahead on (2026-08-29) the task stayed in the month view even after switching views — ask the user to reload the client (F5 in the web app/PWA, restart of the desktop app) before a missing render is taken for an error"

Changed1 schema field changedv1.4.2Aug 31, 2026

changedInput schema / properties / parent_id / description

Previous value: -"Move to category/project ID (not validated by the server — a wrong ID yields an orphan, live-tested 2026-08-29)"New value: +"Move to category/project ID (not validated by the server — a wrong ID yields an orphan, live-tested 2026-08-29; repaired by running FIX_CYCLES() in the app's console)"

Changed1 schema field changedv1.4.0Aug 30, 2026

changedInput schema / properties / parent_id / description

Previous value: -"Move to category/project ID"New value: +"Move to category/project ID (not validated by the server — a wrong ID yields an orphan, live-tested 2026-08-29)"

First observedv1.3.0Aug 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare write/idempotent/non-destructive; the description adds far more: Full Access Token requirement, transient 500s being atomic with safe retry, permanent 500 meaning a missing document (server returns 500 not 404), strategy-dependent fields persisting while hidden in the UI, and the MCP-side limitation on clock times/reminders. These are exactly the operational facts an agent cannot get from structured fields.

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?

Front-loaded with purpose and sibling routing, and nearly every sentence earns its place with non-obvious operational detail. It is long, however, and the repeated 'verified in the app 2026-08-29' provenance tag appears ten-plus times and the planned_week sentence sprawls, adding noise to an otherwise tight structure.

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 23-parameter mutation tool with an output schema and annotations, the description covers the remaining agent-facing gaps: auth scope, error/retry semantics, missing-ID recovery via get_categories/get_children, recurring-task restrictions, and client-reload caveats. Nothing essential to calling it correctly 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?

Schema coverage is 100% so the per-parameter docs carry most of the load, but the description adds cross-cutting semantics the schema can't: strategy-dependent fields (start/end date, planned_week/month, review_date, backburner, orbit, sections) are settable even when the strategy is disabled, and the backburner/start_date interaction in the schema aligns with the description's note that scheduling trumps the flag. Useful, though not comprehensive beyond what the schema already states.

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?

Opens with a specific verb+resource+endpoint: 'Update fields on an existing TASK via /doc/update'. It immediately distinguishes itself from siblings by naming update_category_or_project, set_priority, and mark_done and stating what those handle instead. An agent can route correctly without opening any schema.

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?

Explicit when/not and alternatives: categories/projects go to update_category_or_project, priority to set_priority, completion to mark_done ('never here'). It also carves out recurring-task recurrence editing as forbidden and restricts simple field edits to single instances, which is a real usage boundary.

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