Move an Outlook message to Deleted Items so it can be recovered until the folder is emptied; optionally keep it unread while removing it from the unread count.
Move a message (by ref or raw id) to Deleted Items — recoverable from there until you empty it. Marks it read first (mark_as_read=False to keep it unread) so deleted mail doesn't linger in your unread count.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | ||
| mark_as_read | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does real work: it discloses the soft-delete/recoverability model ('recoverable from there until you empty it') and an otherwise invisible side effect (message is marked read before deletion, configurable via mark_as_read). It stops short of error behavior for already-deleted or missing messages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler: destination and recoverability first, then the side effect and its override. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no annotations and no output schema, the description covers destination, reversibility, and side effects. What remains unstated (error/idempotency behavior on an already-deleted message, return value) is minor but not zero.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does for mark_as_read — naming the default's purpose (keep deleted mail out of the unread count) and the opt-out (mark_as_read=False). It also clarifies that message_id accepts either a reference or a raw id, which the bare 'string' schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Move a message ... to Deleted Items') plus the accepted identifier forms ('by ref or raw id'), which distinguishes it from move_message (arbitrary destination) and bulk_delete_messages (plural). An agent can pick it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The recoverable-vs-permanent distinction implies this is a soft delete, but it never states when to prefer delete_message over archive_message, move_message, or bulk_delete_messages, nor any precondition (e.g. message must not already be deleted). Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.