Move a message to a folder

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

Annotations only indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds critical behavioral disclosure not covered by annotations: the move reassigns a new id, invalidating the old one and requiring the returned id for follow-ups. It also clarifies the soft-delete semantics of the deleteditems destination. This is valuable, non-obvious behavior that an agent must know.

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?

The description is three sentences of high information density. It front-loads the core action, then the most critical behavioral caveat (new id), then the parameter-specific guidance. Every sentence adds value, and there is no redundant fluff or restating of the tool's name or title.

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?

Given the tool's simplicity (2 simple params, no output schema, no nested objects), the description covers all essential contexts: the action, the id reassignment side effect, the referral to mail_list_folders, and the soft-delete use case. An agent has everything needed to invoke it correctly and interpret the result. No critical information is missing.

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 100%, so both id and destinationId are documented. The description adds meaning for destinationId by referencing mail_list_folders and the soft-delete nuance, which helps an agent choose the right value. For id, it explains the consequence (new id) but that's more about output than the parameter itself. It supplements the schema meaningfully without repeating it, justifying above-baseline scoring.

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?

The description opens with a specific verb+resource: 'Moves a message to another mail folder.' It clearly distinguishes this from sibling tools like mail_delete_message (a delete, not a move) and mail_mark_read (a state change). The unique consequence of the move—the message receiving a NEW id—is stated up front, further differentiating it.

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 description gives clear context on when to use this tool: it references mail_list_folders for obtaining destinationId and explicitly explains that 'moving to deleteditems is how you soft-delete without mail_delete_message.' This provides a usage nuance relative to the delete tool, though it doesn't explicitly enumerate all alternative tools or exclusions. Overall, it offers solid guidance beyond the schema.

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