amazing-marvin-complete-mcp

update_category_or_project

Idempotent

Update a category or project: labels, color, icon, note, project fields. Update fields on an existing CATEGORY or PROJECT via /doc/update (Full Access Token). For tasks, use update_task.

Instructions

Update a category or project: labels, color, icon, note, project fields. Update fields on an existing CATEGORY or PROJECT via /doc/update (Full Access Token). For tasks, use update_task. Fields marked 'Projects ONLY' (day/due_date/priority/frog/size) are blocked for categories: if any of them is given, the tool first reads the document (1 extra API call) and refuses if it is a category. The reason is structural, not technical: a category can never be completed or checked off, and deadline, scheduling, priority and frog belong to things that can be finished — projects and tasks. The API accepts the fields on categories (live-tested 2026-09-11) but they are not meaningful there (rule 2026-09-11). label_ids applies to both categories and projects. Strategy-dependent fields (start/end date, planned_week/month, review_date, orbit) can be set even when the strategy is disabled in the app. Do not complete projects here (done via /doc/update skips the app's side effects) — that is done in the Marvin app. Note: Marvin's server can sporadically respond 500 on /doc/update (transient and atomic); 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

Name	Required	Description
`day`	No	Projects ONLY: schedule YYYY-MM-DD, 'today', or 'unassigned' to unschedule
`frog`	No	Projects ONLY: Dread/frog 1-4 (read in the app, 2026-10): 1=I dread this a little (A little), 2=I dread this (Dread), 3=I dread this a lot (A lot), 4=This might kill me (Toxic — requires 'Enable toxic frog level' in the account; Simple mode shows only one level). 0 removes
`icon`	No	Icon name with a library prefix ('lucide-Rocket', 'huge-happy'), '' removes. Rendered directly on categories; on projects only when Master List → Configure View → 'Show Custom Icon On' includes projects ('Categories & Projects' verified in the app 2026-08-31, 'Just Projects' 2026-09-18; the earlier wording 'projects never render their own icon' was wrong)
`note`	No	New note (replaces the existing one)
`size`	No	Projects ONLY: size XS/S/M/L/XL (taskSize 1-5), '' removes
`color`	No	Color '#rrggbb', '' removes
`orbit`	No	Orbit strategy: True = put in orbit (verified in the app 2026-08-29 on tasks: Orbit view + icon in Today). UNDOCUMENTED field
`title`	No	New title
`item_id`	Yes	ID of the category/project (from get_categories)
`due_date`	No	Projects ONLY: deadline YYYY-MM-DD, '' removes
`end_date`	No	Soft deadline YYYY-MM-DD (Start & End Dates strategy), '' removes
`priority`	No	Projects ONLY: 'high'=Most important (red), 'mid'=Very important (orange), 'low'=Important (yellow, the one-star level — NOT the app's 'Low priority', which projects do not have), '' removes. Projects use the string field priority, not isStarred (verified live 2026-08-29; mapping verified against the app's code 2026-08-30)
`label_ids`	No	New labels (replaces existing ones, [] removes all) — categories AND projects: categories have labels in the same field as projects, stored and rendered (live-tested + verified in the app 2026-09-11)
`parent_id`	No	Move to parent category ID, or 'root'
`backburner`	No	True = put in the backburner, False = take out. NOTE (verified in the app 2026-08-29 on tasks): only effective on unscheduled items — scheduling trumps the flag
`start_date`	No	Start date YYYY-MM-DD (Start & End Dates strategy), '' removes
`review_date`	No	Review date YYYY-MM-DD (Review Date strategy), '' removes
`planned_week`	No	Plan into a week: the week's Monday YYYY-MM-DD (Planning Ahead strategy), '' removes (the app's view may keep showing it until the client is reloaded — see update_task.planned_week)
`no_auto_orbit`	No	Orbit strategy: True = exempt from automatic orbiting. UNDOCUMENTED field (bool type verified in live data 2026-08-29)
`planned_month`	No	Plan into a month: YYYY-MM (Planning Ahead strategy), '' removes (the app's view may keep showing it until the client is reloaded — see update_task.planned_week)
`first_scheduled`	No	The app's bookkeeping field firstScheduled YYYY-MM-DD, '' removes — mainly for restoring the value from the convert tool's removed_project_fields after a conversion round trip (nothing backfills it, neither server nor app — verified 2026-08-29). Otherwise leave alone
`time_estimate_minutes`	No	Time estimate in minutes, 0 removes it. On projects the own estimate takes precedence; without one the project shows the sum of its children's (per Marvin support)

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.7.3Oct 13, 2026

changedInput schema / properties / frog / anyOf

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

changedInput schema / properties / frog / description

Previous value: -"Projects ONLY: frog 3=monster, 2=baby, 1=normal, 0=remove"New value: +"Projects ONLY: Dread/frog 1-4 (read in the app, 2026-10): 1=I dread this a little (A little), 2=I dread this (Dread), 3=I dread this a lot (A lot), 4=This might kill me (Toxic — requires 'Enable toxic frog level' in the account; Simple mode shows only one level). 0 removes"

addedInput schema / properties / size

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "XS",
+        "S",
+        "M",
+        "L",
+        "XL",
+        ""
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Projects ONLY: size XS/S/M/L/XL (taskSize 1-5), '' removes"
+}

changedInput schema / properties / time_estimate_minutes / description

Previous value: -"Time estimate in minutes, 0 removes it. On projects: rendered as the project's OWN estimate, no aggregation with the children's (verified in the app 2026-08-29)"New value: +"Time estimate in minutes, 0 removes it. On projects the own estimate takes precedence; without one the project shows the sum of its children's (per Marvin support)"

Changed1 schema field changedv1.7.2Sep 18, 2026

changedInput schema / properties / icon / description

Previous value: -"Icon name with a library prefix ('lucide-Rocket', 'huge-happy'), '' removes. Rendered directly on categories; on projects only with Master List → Configure View → 'Show Custom Icon On' = 'Categories & Projects' (verified in the app 2026-08-31 — the earlier wording 'projects never render their own icon' was wrong)"New value: +"Icon name with a library prefix ('lucide-Rocket', 'huge-happy'), '' removes. Rendered directly on categories; on projects only when Master List → Configure View → 'Show Custom Icon On' includes projects ('Categories & Projects' verified in the app 2026-08-31, 'Just Projects' 2026-09-18; the earlier wording 'projects never render their own icon' was wrong)"

Changed1 schema field changedv1.7.1Sep 18, 2026

changedInput schema / properties / icon / description

Previous value: -"Icon name with a library prefix ('lucide-Rocket', 'huge-happy'), '' removes. ONLY meaningful on categories — projects never render their own icon (verified in the app 2026-08-29)"New value: +"Icon name with a library prefix ('lucide-Rocket', 'huge-happy'), '' removes. Rendered directly on categories; on projects only with Master List → Configure View → 'Show Custom Icon On' = 'Categories & Projects' (verified in the app 2026-08-31 — the earlier wording 'projects never render their own icon' was wrong)"

Changed3 schema fields changedv1.6.0Sep 12, 2026

changedInput schema / properties / label_ids / description

Previous value: -"Projects ONLY: new labels (replaces existing ones, [] removes all)"New value: +"New labels (replaces existing ones, [] removes all) — categories AND projects: categories have labels in the same field as projects, stored and rendered (live-tested + verified in the app 2026-09-11)"

changedInput schema / properties / planned_month / description

Previous value: -"Plan into a month: YYYY-MM (Planning Ahead strategy), '' removes"New value: +"Plan into a month: YYYY-MM (Planning Ahead strategy), '' removes (the app's view may keep showing it until the client is reloaded — see update_task.planned_week)"

changedInput schema / properties / planned_week / description

Previous value: -"Plan into a week: the week's Monday YYYY-MM-DD (Planning Ahead strategy), '' removes"New value: +"Plan into a week: the week's Monday YYYY-MM-DD (Planning Ahead strategy), '' removes (the app's view may keep showing it until the client is reloaded — see update_task.planned_week)"

Changed1 schema field changedv1.4.0Aug 30, 2026

changedInput schema / properties / priority / description

Previous value: -"Projects ONLY: priority 'high'/'mid'/'low', '' removes. Projects use the string field priority, not isStarred (verified live 2026-08-29)"New value: +"Projects ONLY: 'high'=Most important (red), 'mid'=Very important (orange), 'low'=Important (yellow, the one-star level — NOT the app's 'Low priority', which projects do not have), '' removes. Projects use the string field priority, not isStarred (verified live 2026-08-29; mapping verified against the app's code 2026-08-30)"

First observedv1.3.0Aug 29, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only cover the safety/idempotency profile; the description goes much further by disclosing the hidden extra read call (1 extra API call) when project-only fields are supplied, the Full Access Token requirement, replacement semantics for note/label_ids, and the 500-instead-of-404 convention for missing IDs.

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?

The core routing and blocking rules are front-loaded in the first two sentences, but the middle section is bloated with dated provenance notes ('live-tested 2026-09-11', 'verified 2026-08-29') and a philosophical justification for the category/project split that an agent does not need to invoke the 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?

Given 22 parameters and a mutation tool with only a bare annotation set, the description covers auth requirements, error semantics, cross-tool routing, refusal conditions, and strategy-dependent field behavior. With an output schema present, return values need no further explanation.

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 baseline is 3, but the description adds real meaning: which fields apply to categories versus projects, why day/due_date/priority/frog/size are refused on categories, and that label_ids works on both. A few parameters (orbit, no_auto_orbit, first_scheduled) are noted as undocumented, which is honest but leaves some residual ambiguity.

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 ('Update a category or project') and enumerates the editable surface. It explicitly routes task updates to update_task, so the agent can distinguish it from the closest sibling without opening either 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?

States when to use update_task instead, warns not to complete projects here because the app's side effects would be skipped, and explains the 'Projects ONLY' field blocking behavior on categories. It also gives explicit retry guidance for transient 500s versus permanent 500s.

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

Deploy Server