mailwarden

undo_bulk_modify

DestructiveIdempotent

Revert a bulk label change exactly by applying the undo plan returned by bulk_modify. Restores lost labels and removes added ones, leaving messages already in the target state untouched.

Instructions

Revert a bulk_modify exactly, from the undo plan it returned (bulk_modify with undo:true). Pass steps unchanged: each step adds back the labels its messages lost and takes off the labels they gained, so a message that was already in the target state before the bulk change is left alone. Steps name labels by id, as the plan does; a label name is refused, because an unknown name would be created rather than restored. The plan restores the state read just before the bulk change. A label changed by hand since then is changed again by the undo, and a label deleted since then makes its step fail — reported in failed, the other steps still run. A label the bulk change created stays in the mailbox, empty. Set verify:true to read the labels back afterwards — one read per affected thread, however many steps name it. USE WHEN: the user wants a bulk change taken back, and the bulk_modify result carried undo. DO NOT USE: without a plan from bulk_modify (use bulk_modify or modify_labels), or to change labels in a new way — this applies exactly the steps it is given. SIDE EFFECTS: label changes on the listed messages; reversible again by the inverse.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "steps": "<steps>"
    },
    "name": "undo_bulk_modify"
  }
}

Input Schema

Name	Required	Description	Default
`steps`	Yes
`verify`	No

Output Schema

Name	Required	Description	Default
`failed`	Yes
`verified`	No
`submittedMessages`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.25.0Oct 29, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- removedInput schema / properties / steps / items / additionalProperties
```
Removed value: -false
```
Addedv0.23.0Oct 17, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already flag destructiveHint/idempotentHint, and the description adds substantial context beyond them: what each step does semantically, that hand-changed labels get re-changed, that a deleted label makes only its step fail and is reported in `failed` while other steps continue, and that a created label survives as an empty label. Nothing here contradicts the annotations.

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?

Front-loaded with the core action and the critical 'pass steps unchanged' instruction, then USE WHEN / DO NOT USE / SIDE EFFECTS sections. It is dense and slightly long — a couple of sentences (e.g. the restatement of what the plan represents) could be folded — but almost every sentence carries operative detail.

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?

A destructive mutation tool with a nested-array parameter and 0% schema coverage, yet the description covers input provenance, id-format constraint, partial-failure semantics, side effects, and verification cost. The `failed` return field is described, and an output schema exists to cover the rest.

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?

Schema coverage is 0%, so the description carries the full burden and does: `steps` must be passed unchanged from the plan, labels inside steps are named by id (a name is refused because an unknown name would be created rather than restored), and `verify` triggers one read per affected thread regardless of how many steps name it.

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+resource+scope: revert a bulk_modify exactly, using the `undo` plan that bulk_modify itself emitted. This immediately distinguishes it from bulk_modify and modify_labels, which are named later as the alternatives.

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?

Provides explicit USE WHEN (user wants a bulk change taken back and the bulk_modify result carried `undo`) and DO NOT USE (no plan from bulk_modify → use bulk_modify or modify_labels; or to make new label changes). Both the trigger and the exclusion are stated, not inferred.

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