amazing-marvin-complete-mcp

update_category_or_project

Idempotent

Update fields on an existing category or project, such as title, color, labels, or schedule. Rejects project-only fields for categories; use update_task for tasks.

Instructions

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) 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

TableJSON Schema

Name	Required	Description
`day`	No	Projects ONLY: schedule YYYY-MM-DD, 'today', or 'unassigned' to unschedule
`frog`	No	Projects ONLY: frog 3=monster, 2=baby, 1=normal, 0=remove
`icon`	No	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)
`note`	No	New note (replaces the existing one)
`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: rendered as the project's OWN estimate, no aggregation with the children's (verified in the app 2026-08-29)

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

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.9/5.0

Behavior5/5

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

Goes well beyond annotations (readOnly=false, idempotent=true, destructive=false) by disclosing a hidden cost (1 extra API call when blocked fields are supplied), refusal semantics, a hard prohibition on completing projects due to skipped side effects, transient vs permanent 500 behavior, and that the server returns 500 instead of 404 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.

Conciseness4/5

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

Long but front-loaded: the core verb, resource, scope, and sibling routing come first, and later sentences carry distinct error-handling and field-scoping facts. Dense rather than padded, though some parenthetical provenance dates could be trimmed.

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 21-parameter mutation tool with an output schema already present, the description covers the remaining agent-relevant unknowns: cross-type field applicability, refusal conditions, retry semantics, and the wrong-ID error shape. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds meaning the schema lacks: the structural rationale for 'Projects ONLY' blocking, confirmation that label_ids applies to both types, that icon is categories-only, and that strategy-dependent fields can be set even when the strategy is disabled.

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?

States a specific verb and resource ('Update fields on an existing CATEGORY or PROJECT via /doc/update') and immediately distinguishes itself from the sibling update_task for tasks. An agent can route between update_category_or_project, update_task, and create_category_or_project without opening schemas.

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-to-use routing ('For tasks, use update_task') plus explicit when-not guidance: 'Do not complete projects here' and the refusal behavior for category-blocked fields. Also names recovery alternatives (get_categories/get_children) for the missing-ID case.

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