amazing-marvin-complete-mcp

delete_task

DestructiveIdempotent

Delete a task permanently, with no trash and no undo. Deletion via the API bypasses the app's trash and cannot be undone — use only when the user explicitly wants a deletion.

Instructions

Delete a task permanently, with no trash and no undo. Deletion via the API bypasses the app's trash and cannot be undone — use only when the user explicitly wants a deletion. If the task has reminders they are cleared and the server entries removed before the deletion, so that no notification arrives. An occurrence of a recurring task follows the app's two choices: 'this' adds the occurrence's day to the recurring task's deletedDates and deletes the occurrence; 'all' deletes all open occurrences and then the recurring task, completed occurrences are kept. If a step fails the response says which were done. THE APP'S VIEW: an open client does not render the deletion — reload the client (F5, restart of the desktop app) before the row is touched; a write from the app on the stale row recreates the document. A recurring task (db RecurringTasks) is deleted with scope 'all', on an occurrence or on the recurring task's own id — also before it has any occurrences (they are created only when a client opens after the day rolls over). Habit recurrences are not deleted here. Projects and categories: deleted only without open children — the tool reads /children first (one more call) and otherwise refuses, with the list, so that no children are left with a parent that does not exist. Completed children do not show in /children and are left behind with the parent gone. The project's notebook is not deleted (as in the app); the response gives its id for delete_notebook.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`scope`	No	Occurrence of a recurring task: 'this' = only this one (default), 'all' = the whole recurring task with all open occurrences (completed ones are kept). The recurring task's own id is accepted only with 'all'	this
`item_id`	Yes	ID of the task (or of a project/category without open children) to delete

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.7.3Oct 13, 2026

changedInput schema / properties / item_id / description

Previous value: -"ID of the document to delete"New value: +"ID of the task (or of a project/category without open children) to delete"

addedInput schema / properties / scope

Added value: +{
+  "default": "this",
+  "description": "Occurrence of a recurring task: 'this' = only this one (default), 'all' = the whole recurring task with all open occurrences (completed ones are kept). The recurring task's own id is accepted only with 'all'",
+  "enum": [
+    "this",
+    "all"
+  ],
+  "type": "string"
+}

First observedv1.3.0Aug 29, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: trash bypass, reminder/server-entry cleanup before deletion, partial-failure reporting, the pre-flight /children read that can add a call, completed-children left orphaned, and the stale-client recreation hazard. This is exactly the extra context destructive operations need.

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 critical warning is front-loaded, which is good, but the body is a dense wall of prose with a mid-block all-caps label and repeated restatement of the scope enum. The content is substantive, yet it is longer and less scannable than it needs to be for a two-parameter 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?

An output schema exists, so return values need not be described, yet the description still covers partial-failure reporting, the notebook-id handoff, and the client reload hazard. For a destructive, non-idempotent-looking operation, nothing an agent needs to call it safely is missing.

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 item_id and the scope enum are already documented in the schema, and the description's 'this'/'all' explanation largely restates it. It adds only marginal detail (the recurring task's own id accepted only with 'all', which the schema also states), so baseline 3 is appropriate.

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 and resource plus a crucial qualifier ('permanently, with no trash and no undo'), and immediately distinguishes scope: tasks and recurring occurrences here, habit recurrences excluded, and the project notebook handed off to delete_notebook. An agent can tell it apart from delete_notebook, delete_reminder and update_task without opening any 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?

Gives an explicit gate ('use only when the user explicitly wants a deletion'), states when the tool refuses (projects/categories with open children), names the sub-case behavior for 'this' vs 'all', and routes the notebook cleanup to a sibling. That is when-to-use, when-not, and alternatives in one pass.

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

Deploy Server