amazing-marvin-complete-mcp

convert_category_or_project

Idempotent

Convert projects to categories or back, in place and losslessly. Preserves the same ID and all child items.

Instructions

Convert a project to a category or back, in place and losslessly. 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.8/5.0

Behavior5/5

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description goes well beyond these: it discloses that the tool relies on undocumented server behavior via /doc/update, that conversion is a pure type change preserving _id/createdAt/children, that project fields may remain on categories as intentional round-trip data, and that clear_project_fields=True clears specific fields and returns them in removed_project_fields. It also flags the risk of orphans/cycles. This is rich behavioral context that annotations alone do not provide, and it does not contradict them.

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 dense but every sentence earns its place: purpose, experimental risk, lossless semantics, the clean-category option, app-path context, and a critical safety warning. It is front-loaded with the core purpose and the most important caveat (EXPERIMENTAL). It is longer than average, but the complexity of the tool justifies the length; minor redundancy exists around the app's correct path being mentioned twice.

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 the tool's complexity, the 100% schema coverage, and the presence of an output schema, the description is complete. It covers the conversion direction, the undocumented endpoint risk, the lossless behavior, the clean-category alternative, the subcategory safety constraint, and the verification date. An agent has everything needed to decide whether and how to invoke this tool correctly.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the lossless default behavior, what clear_project_fields=True actually clears (day/dueDate/priority/isFrogged/firstScheduled), the relationship to the app's buggy Edit Settings path, and the return of removed_project_fields. It also clarifies that item_id comes from get_categories. This elevates the parameter guidance above the baseline.

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 a specific verb and resource: 'Convert a project to a category or back, in place and losslessly.' It clearly distinguishes the tool's bidirectional conversion behavior and immediately contrasts with the sibling update_category_or_project by explaining the type-change semantics. The experimental caveat and lossless-by-default detail further sharpen what this tool uniquely does.

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?

The description gives explicit when-to-use guidance: use for in-place type conversion, and explicitly warns 'Do NOT convert a category that contains subcategories into a project' with a reason (orphans/cycles) and a check to perform first (get_children). It also explains when to set clear_project_fields=True versus the default lossless path, and notes the app's correct path is not in the menu by default. This is thorough routing and exclusion guidance.

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