amazing-marvin-complete-mcp

create_category_or_project

Instructions

Create a category or project with color, icon, labels and note. Create a category (via /doc/create, Full Access Token) or a project (via /addProject). Categories can contain categories; projects cannot. day/due_date/priority/frog are rejected for kind='category' for a structural reason, not a technical one: 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. startDate/endDate cannot be set at creation (/addProject ignores them, verified live 2026-08-29) — use update_category_or_project afterwards.

Note: project titles must not contain '#word' — /addProject has the same corruption bug as /addTask (the string is stored unresolved as parentId and the project becomes invisible) but ignores the X-Auto-Complete header (verified against the live API 2026-08-20), so the client blocks it locally before any API call. Category titles are unaffected (/doc/create parses nothing).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`day`	No	Projects ONLY: schedule on YYYY-MM-DD or 'today' (blocked for categories — a category is never completed)
`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)
`icon`	No	Icon name with a library prefix, e.g. 'lucide-Rocket' (Lucide, PascalCase) or 'huge-happy' (verified in the app 2026-08-29); the app's picker also allows emoji. 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)
`kind`	Yes	Kind
`note`	No	Note
`color`	No	Color '#rrggbb'. Categories ONLY at creation — /addProject ignores the field (verified live 2026-08-29); set project color with update_category_or_project afterwards
`title`	Yes	Name
`due_date`	No	Projects ONLY: deadline YYYY-MM-DD (blocked for categories — a category is never completed)
`priority`	No	Projects ONLY: priority as a string — 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). Projects do not use isStarred (verified live 2026-08-29; mapping verified against the app's code 2026-08-30)
`label_ids`	No	Label IDs (from get_labels) — categories AND projects: categories have labels, stored in the same field as projects' and rendered in the app (live-tested + verified in the app 2026-09-11)
`parent_id`	No	ID of the parent category, or 'root' for the top level	root
`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; mainly projects)
`planned_month`	No	Plan into a month: YYYY-MM (Planning Ahead strategy; mainly projects)
`time_estimate_minutes`	No	Time estimate in minutes. The project's own estimate takes precedence; without one the project shows the sum of its children's (per Marvin support)

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.7.3Oct 13, 2026

changedInput schema / properties / frog / anyOf

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

changedInput schema / properties / frog / description

Previous value: -"Projects ONLY: frog marker 1=normal, 2=baby, 3=monster"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)"

changedInput schema / properties / time_estimate_minutes / description

Previous value: -"Time estimate in minutes. NOTE: rendered as the project's OWN estimate — the UI does not aggregate it with the children's, despite the wiki's claim (verified in the app 2026-08-29)"New value: +"Time estimate in minutes. The project's 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, e.g. 'lucide-Rocket' (Lucide, PascalCase) or 'huge-happy' (verified in the app 2026-08-29); the app's picker also allows emoji. 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, e.g. 'lucide-Rocket' (Lucide, PascalCase) or 'huge-happy' (verified in the app 2026-08-29); the app's picker also allows emoji. 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, e.g. 'lucide-Rocket' (Lucide, PascalCase) or 'huge-happy' (verified in the app 2026-08-29); the app's picker also allows emoji. Categories ONLY — projects NEVER render their own icon (the flag stays; only the color is used)"New value: +"Icon name with a library prefix, e.g. 'lucide-Rocket' (Lucide, PascalCase) or 'huge-happy' (verified in the app 2026-08-29); the app's picker also allows emoji. 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 / day / description

Previous value: -"Projects ONLY: schedule on YYYY-MM-DD or 'today' (categories cannot be scheduled)"New value: +"Projects ONLY: schedule on YYYY-MM-DD or 'today' (blocked for categories — a category is never completed)"

changedInput schema / properties / due_date / description

Previous value: -"Projects ONLY: deadline YYYY-MM-DD (categories have no dueDate)"New value: +"Projects ONLY: deadline YYYY-MM-DD (blocked for categories — a category is never completed)"

changedInput schema / properties / label_ids / description

Previous value: -"Projects ONLY: label IDs (from get_labels)"New value: +"Label IDs (from get_labels) — categories AND projects: categories have labels, stored in the same field as projects' and rendered in the app (live-tested + verified in the app 2026-09-11)"

Changed1 schema field changedv1.4.0Aug 30, 2026

changedInput schema / properties / priority / description

Previous value: -"Projects ONLY: priority as a string — projects do not use isStarred (verified live 2026-08-29)"New value: +"Projects ONLY: priority as a string — 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). Projects do not use isStarred (verified live 2026-08-29; mapping verified against the app's code 2026-08-30)"

First observedv1.3.0Aug 29, 2026

TDQS

A4.2/5.0

Behavior5/5

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

With annotations already declaring non-readOnly, non-destructive and non-idempotent, the description adds genuinely new behavior: the category path requires a Full Access Token via /doc/create, project titles containing '#word' are blocked locally by the client before any API call because of an /addProject corruption bug, and /addProject silently ignores color and startDate/endDate. These are exactly the silent-failure disclosures 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.

Conciseness3/5

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

Purpose is front-loaded, but the prose is bloated with parenthetical verification dates ('live-tested 2026-09-11', 'verified live 2026-08-29') and restates constraints that already appear in the schema descriptions, such as the color and day/due_date restrictions. The startDate/endDate paragraph discusses fields that are not parameters of this tool, adding noise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. For a 15-parameter mutation tool with rich annotations, the description covers auth requirements, silent-ignores, and a local validation block, leaving only minor gaps (e.g., what happens on an invalid kind/field combination).

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already carries the per-parameter meaning, and much of the description's field commentary (color Categories ONLY, day/due_date blocked for categories, label_ids applies to both) duplicates it nearly verbatim. The description adds little parameter meaning beyond the schema, so the baseline of 3 applies.

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 opening sentence states a specific verb (Create) and the two resources (category or project) along with the fields it accepts. It also makes the structural distinction between the two kinds explicit (categories can contain categories; projects cannot), which lets an agent tell this apart from create_task and update_category_or_project 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?

It gives real routing guidance: use update_category_or_project afterwards for startDate/endDate, since /addProject ignores them at creation, and it explains why certain fields (day/due_date/priority/frog) are rejected for kind='category'. It never contrasts with create_task for task creation, so it stops short of fully explicit when/when-not/alternatives.

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

Deploy Server