update_mailbox

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

With no annotations provided, the description carries the full disclosure burden. It thoroughly covers error types (imap_required, unsupported_gmail_system_label, validation_error), special cases for Gmail system labels, and path-traversal sanitization. It doesn't explicitly state that the operation is non-destructive to the mailbox content, but the rename/move semantics are implicit. This is strong coverage.

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 longer than most, but it is well-structured with clear headings and bullet points, and the core purpose is front-loaded. Every sentence carries necessary information about behavior, errors, or conditions. It could arguably be tightened, but the density of essential details justifies the length.

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?

The tool has moderate complexity (two delivery paths, authentication requirements, Gmail restrictions), and the description addresses all of these thoroughly. It explains parameter combinations, error scenarios, and prerequisites. Although there is an output schema, the description still covers the necessary contextual and prereq info an agent needs to call it correctly.

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%, but the description adds substantial value beyond the schema: it explains the interplay between new_name and new_parent, the None defaults, the top-level move via empty string, and the sanitization behavior. The description resolves ambiguities that the schema alone would leave, such as what happens when both are null (error) and how Gmail paths are treated.

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: rename and/or re-parent an existing mailbox. Clearly distinguishes from siblings like create_mailbox and delete_mailbox by focusing on modification. The first sentence is unambiguous.

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?

Explicitly explains two delivery paths (rename vs move) with conditions on which parameters to set, the requirement that at least one be provided, and the IMAP credentials prerequisite for moves. Also clarifies unsupported Gmail paths with actionable error responses, so an agent knows exactly when to use rename vs move and what to expect.

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