amazing-marvin-complete-mcp

convert_category_or_project

Idempotent

Convert categories to projects or projects to categories in place, preserving ID, creation time, and children. Optionally clear project fields to create a clean category for permanent conversions.

Instructions

EXPERIMENTAL: Convert project→category or category→project IN PLACE via /doc/update (Full Access Token; there is no official conversion endpoint, and this relies on undocumented server behavior that Marvin could change). Same _id, createdAt and children remain — conversion is a pure type change (verified against the live API 2026-08-29: the server accepts and persists the change in both directions, and the app renders correctly after an API-set change). LOSSLESS BY DEFAULT (since 1.5.0): only type is changed — the same semantics as the app's correct conversion path (the right-click/hover menu, verified as a lossless round trip 2026-08-30: all project fields incl. firstScheduled preserved through project→category→project). Project fields remaining on the category are then intentional round-trip data; the type guard in update_category_or_project only prevents NEW project fields from being written to it. If you want a clean category for a permanent conversion: set clear_project_fields=True (mimics the app's Edit Settings path — a bug in their tracker; also clears firstScheduled, which that path otherwise leaves behind) and receive the values in removed_project_fields. Note: the app's correct path (right-click/hover) is not in the menu by default — it is added via the gear icon directly in the right-click menu → Add action (app-verified 2026-08-31), so unmodified apps only show the buggy path. Do NOT convert a category that contains subcategories into a project — projects cannot contain categories (risk of orphans/cycles; check get_children first).

Input Schema

TableJSON Schema

Name	Required	Description
`to`	Yes	Target type to convert to
`item_id`	Yes	ID of the project/category to convert (from get_categories)
`clear_project_fields`	No	Only for to='category': True = clear day / dueDate / priority / isFrogged / firstScheduled (like the app's buggy Edit Settings path — yields a CLEAN category without e.g. a deadline badge, for a permanent conversion); the previous values are then returned in removed_project_fields. Default False = lossless, like the app's correct path

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.4.2Aug 31, 2026

addedInput schema / properties / clear_project_fields

Added value: +{
+  "default": false,
+  "description": "Only for to='category': True = clear day / dueDate / priority / isFrogged / firstScheduled (like the app's buggy Edit Settings path — yields a CLEAN category without e.g. a deadline badge, for a permanent conversion); the previous values are then returned in removed_project_fields. Default False = lossless, like the app's correct path",
+  "type": "boolean"
+}

First observedv1.3.0Aug 29, 2026

TDQS

A4.6/5.0

Behavior5/5

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

The description is highly transparent: it discloses the undocumented /doc/update endpoint, the Full Access Token requirement, in-place mutation with same _id/createdAt/children, lossless default behavior, and the risk of orphans/cycles. This goes well beyond the annotations and gives the agent crucial operational context.

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 well-structured and front-loaded with the essential conversion semantics. Some verification dates and app-path details could be trimmed without losing actionability, but they support the tool's experimental nature and are not padding.

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 an experimental and potentially risky conversion tool, the description covers prerequisites, side effects, field preservation/clearing behavior, return values, and a critical warning. An output schema exists, so return-value documentation is not required here; the description is operationally complete.

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%, but the description adds meaningful nuance beyond the schema: it explains the default False for clear_project_fields means lossless conversion, clarifies what gets cleared when True, and notes that removed values are returned in removed_project_fields. This is useful supplementary meaning for a documented parameter set.

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 an explicit, specific operation: 'Convert project→category or category→project IN PLACE'. This clearly distinguishes it from sibling create/update tools and explains the core type-changing behavior.

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?

The description gives strong usage context: it warns not to convert a category with subcategories, tells the agent to check get_children first, and explains when to choose clear_project_fields=True vs the lossless default. However, it does not explicitly contrast itself with update_category_or_project or other siblings, so the alternative-selection guidance is mostly implied.

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