amazing-marvin-complete-mcp

create_task

Create a task in Amazing Marvin with category, day, priority, labels, estimate, sections, frog markers, due dates, and rewards.

Instructions

Create a task with category, day, priority, labels, estimate, sections. Prefer priority/frog over dates where possible.

The title is stored verbatim: this tool disables the server's shortcut parsing (X-Auto-Complete: false, verified against the live API 2026-08-20), so quick-add syntax like '#Category', '~15', '+YYYY-MM-DD' and '*p2' is NOT parsed — '#' in titles (e.g. ticket references) is therefore safe. Without this, every '#word' would corrupt the task (the string is stored unresolved as parentId, making the task invisible). Use the parameters instead: parent_id, day, priority, time_estimate_minutes, label_ids.

Note: startDate/endDate CANNOT be set here — /addTask ignores them (verified against the live API 2026-08-29). Set them with update_task after creation. A clock time (Time/taskTime) on the task: fully possible in Marvin, but it is set in the APP, not via this MCP — an MCP limitation, NOT a Marvin limitation. A set Time automatically becomes (with auto-created reminders enabled in the user's settings) a reminder at that time; the task does NOT become an event and blocks no time (time blocking = time blocks). The reason for the app route is the double-write sync — see set_reminder. Strategy-dependent fields (planned_week/month, review_date, backburner, is_reward/reward_points, the sections) are stored even when the strategy is disabled in the app — they just are not shown in the UI then.

Input Schema

TableJSON Schema

Name	Required	Description
`day`	No	Schedule on date YYYY-MM-DD, 'today', or 'unassigned' (= unscheduled, same as omitting). Same rules as update_task.
`frog`	No	Frog marker 1=normal, 2=baby, 3=monster
`note`	No	Note (markdown)
`title`	Yes	Task title
`due_date`	No	Deadline YYYY-MM-DD (use sparingly)
`priority`	No	Priority (isStarred): 3=Most important/red, 2=Very important/orange, 1=Important/yellow, -1=Low priority (down arrow; shown in the app only with 'Enable low priority' on in the Priorities strategy — the value is stored regardless). 0 is not valid here; omit for no priority
`is_reward`	No	Documented Task field with no observed function — normally do NOT use. The app's purchasable rewards are separate Rewards documents that the public API cannot reach at all (live-tested 2026-08-29: no endpoint exists, and app rewards are not Tasks); the flag on a Task produced no UI effect. Never combine with reward_points
`label_ids`	No	Label IDs (from get_labels)
`parent_id`	No	ID of the category/project the task belongs in (from get_categories). Omit for the Inbox. NOTE: the server does not validate the ID — a wrong parentId yields an orphan reachable only via date reads (live-tested 2026-08-29); repaired by running FIX_CYCLES() in the app's console
`backburner`	No	True = put in the backburner (dormant). NOTE: only effective on an UNSCHEDULED task — scheduling (day) trumps the flag in the UI (verified in the app 2026-08-29), so do not combine with day
`review_date`	No	Review date YYYY-MM-DD (Review Date strategy)
`planned_week`	No	Plan into a week: the week's Monday YYYY-MM-DD (Planning Ahead strategy)
`bonus_section`	No	'Essential' or 'Bonus' (bonusStructure strategy)
`daily_section`	No	Day section: 'Morning', 'Afternoon' or 'Evening' (dailyStructure strategy)
`planned_month`	No	Plan into a month: YYYY-MM (Planning Ahead strategy)
`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; points are claimed via claim_reward_points). Do not set together with is_reward
`custom_section`	No	ID of a custom section from strategySettings.customStructure (customStructure strategy)
`time_block_section`	No	Time block ID (from get_today_time_blocks, or time_block_id from create_time_block). Points the task at a time block; the task then appears under that block's section in Today. Three conditions (verified in the app 2026-09-17, 1.70.0.0, PWA + desktop): (1) the Time Block Sections strategy is on, (2) the day view is grouped by time block (Group by → Group by time block section — set per device, not synced; help article 1950243), (3) the task is scheduled on the block's day (day ≤ that date) — an unscheduled task with the field set is stored but does not appear in Today at all. Without (2) no sections render and the field looks inert. The field is sufficient on its own: the block needs no label/category/smart list, and blocks from create_time_block behave like blocks created in the app. The block's own Smart Time Block mapping (label/category) is a second, independent route that catches matching tasks without this field. The section shows before the block's start time (after its end: untested). The field is not exposed in the app's task settings — the app sets it when a task is added directly inside a block section
`time_estimate_minutes`	No	Time estimate in minutes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.7.1Sep 18, 2026

changedInput schema / properties / time_block_section / description

Previous value: -"Time block ID (from get_today_time_blocks, or time_block_id from create_time_block). NOTE: stored, but gives no visible link in Today (verified in the app 2026-08-29, and re-verified 2026-09-13 with app 1.70.0.0, PWA + desktop, Time Blocking on). In the app the link is carried by the block's own mapping to a label/category/smart list (see get_today_time_blocks), and a block shows its tasks only during its own clock time — to make a task appear in a block, give the block a category in the app and put the task there. Reported upstream"New value: +"Time block ID (from get_today_time_blocks, or time_block_id from create_time_block). Points the task at a time block; the task then appears under that block's section in Today. Three conditions (verified in the app 2026-09-17, 1.70.0.0, PWA + desktop): (1) the Time Block Sections strategy is on, (2) the day view is grouped by time block (Group by → Group by time block section — set per device, not synced; help article 1950243), (3) the task is scheduled on the block's day (day ≤ that date) — an unscheduled task with the field set is stored but does not appear in Today at all. Without (2) no sections render and the field looks inert. The field is sufficient on its own: the block needs no label/category/smart list, and blocks from create_time_block behave like blocks created in the app. The block's own Smart Time Block mapping (label/category) is a second, independent route that catches matching tasks without this field. The section shows before the block's start time (after its end: untested). The field is not exposed in the app's task settings — the app sets it when a task is added directly inside a block section"

Changed1 schema field changedv1.7.0Sep 13, 2026

changedInput schema / properties / time_block_section / description

Previous value: -"Time block ID (from get_today_time_blocks). NOTE: stored, but no visible section link renders in Today even with the Time Block Sections strategy active (verified in the app 2026-08-29) — visible section assignment is done in the app"New value: +"Time block ID (from get_today_time_blocks, or time_block_id from create_time_block). NOTE: stored, but gives no visible link in Today (verified in the app 2026-08-29, and re-verified 2026-09-13 with app 1.70.0.0, PWA + desktop, Time Blocking on). In the app the link is carried by the block's own mapping to a label/category/smart list (see get_today_time_blocks), and a block shows its tasks only during its own clock time — to make a task appear in a block, give the block a category in the app and put the task there. Reported upstream"

Changed1 schema field changedv1.6.0Sep 12, 2026

changedInput schema / properties / day / description

Previous value: -"Schedule on date YYYY-MM-DD, or 'today'. Omit for unscheduled."New value: +"Schedule on date YYYY-MM-DD, 'today', or 'unassigned' (= unscheduled, same as omitting). Same rules as update_task."

Changed1 schema field changedv1.4.2Aug 31, 2026

changedInput schema / properties / parent_id / description

Previous value: -"ID of the category/project the task belongs in (from get_categories). Omit for the Inbox. NOTE: the server does not validate the ID — a wrong parentId yields an orphan reachable only via date reads (live-tested 2026-08-29)"New value: +"ID of the category/project the task belongs in (from get_categories). Omit for the Inbox. NOTE: the server does not validate the ID — a wrong parentId yields an orphan reachable only via date reads (live-tested 2026-08-29); repaired by running FIX_CYCLES() in the app's console"

Changed3 schema fields changedv1.4.0Aug 30, 2026

changedInput schema / properties / parent_id / description

Previous value: -"ID of the category/project the task belongs in (from get_categories). Omit for the Inbox."New value: +"ID of the category/project the task belongs in (from get_categories). Omit for the Inbox. NOTE: the server does not validate the ID — a wrong parentId yields an orphan reachable only via date reads (live-tested 2026-08-29)"

changedInput schema / properties / priority / anyOf

Previous value: -[
-  {
-    "maximum": 3,
-    "minimum": 1,
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "maximum": 3,
+    "minimum": -1,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / priority / description

Previous value: -"Priority 1-3 (3=red/highest, 2=orange, 1=yellow)"New value: +"Priority (isStarred): 3=Most important/red, 2=Very important/orange, 1=Important/yellow, -1=Low priority (down arrow; shown in the app only with 'Enable low priority' on in the Priorities strategy — the value is stored regardless). 0 is not valid here; omit for no priority"

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 say readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, which is minimal. The description carries the full burden and does so richly: it discloses that shortcut parsing is disabled (X-Auto-Complete: false), that startDate/endDate are ignored by /addTask, that clock time must be set in the app, that strategy-dependent fields are stored even when disabled, and that parent_id is not validated (orphan risk). This is exactly the kind of behavioral context an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but every sentence earns its place: the quick-add warning, the startDate/endDate limitation, the clock-time explanation, and the strategy-field note are all non-obvious facts that prevent real errors. It is front-loaded with the core purpose and the most important caveat (shortcut parsing disabled) before the deeper notes. Slightly dense, but justified for a 19-parameter tool.

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 19-parameter creation tool with no meaningful annotations, the description covers the critical gaps: what the server ignores, what the app requires, what is stored but hidden, and what can corrupt data. The output schema exists, so return values need no explanation. The only minor omission is pagination or rate-limit behavior, but that is not essential for a single create call.

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 baseline is 3, but the description adds meaningful cross-parameter guidance: it tells the agent to use parent_id, day, priority, time_estimate_minutes, label_ids instead of quick-add syntax, and it explains the relationship between backburner and day (scheduling trumps the flag). It also warns against combining is_reward with reward_points. This goes beyond the schema's per-parameter descriptions.

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

Purpose5/5

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

The description opens with a specific verb and resource ('Create a task') and immediately enumerates the key fields (category, day, priority, labels, estimate, sections), which distinguishes it from sibling tools like update_task, create_event, and create_category_or_project. It also clarifies what the tool is NOT for (startDate/endDate, clock time), which sharpens the boundary further.

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

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance: prefer priority/frog over dates where possible, use parameters instead of quick-add syntax, and set startDate/endDate with update_task after creation. It also names the alternative tool (update_task) and explains the MCP limitation around clock times, so an agent knows exactly when to route elsewhere.

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