amazing-marvin-complete-mcp

create_task

Add a new task to Amazing Marvin using explicit fields for category, priority, labels, and scheduling. Use parameters instead of quick-add syntax, which is disabled here.

Instructions

Create a task in Amazing Marvin. 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). 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
`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.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.5/5.0

Behavior5/5

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

Annotations only declare the safety profile (write, non-destructive, non-idempotent), while the description discloses far more: X-Auto-Complete: false means titles are stored verbatim and quick-add syntax is NOT parsed, and silently ignored fields (startDate/endDate) are called out with live-verification dates. It also explains the failure mode of the shortcut path (a '#word' stored as parentId makes the task invisible), which is exactly the kind of consequence an agent cannot infer from annotations.

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

Conciseness3/5

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

Purpose and the key title-parsing rule are front-loaded, which is good, but the middle paragraph on Time/taskTime, reminders, events and time blocking is largely tangential to invoking this tool correctly, and the closing strategy paragraph is dense. For a 19-parameter tool some length is warranted, yet several sentences do not earn their place for a create call.

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?

With an output schema present the description need not explain return values, and it still covers the gaps structured data cannot: parser behavior, silently ignored fields, storage-vs-UI divergence for strategy fields, and inter-tool handoffs. Nothing an agent needs to call create_task correctly appears to be 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 already 100%, so the baseline is 3; the description earns an extra point by telling the agent which parameters to use in place of quick-add syntax (parent_id, day, priority, time_estimate_minutes, label_ids) and by clarifying that strategy-dependent fields (planned_week/month, review_date, backburner, sections) are persisted even when the strategy is off in the UI.

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 ('Create a task in Amazing Marvin') and immediately differentiates scope from siblings by naming update_task for start/end dates and by stating that time blocking belongs to time blocks, not this tool. An agent can separate create_task from create_event, create_time_block and update_task without opening a schema.

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

Usage Guidelines4/5

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

Gives concrete routing: set startDate/endDate with update_task after creation, set a clock Time in the app rather than via MCP, and prefer priority/frog parameters over date-based scheduling. It lacks an explicit 'use create_event instead when…' statement, so the event/time-block distinction is only implied.

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