update_mailbox

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, and the description does not contradict them — the mutation framing is consistent. Beyond the annotations, it adds genuinely useful behavioral detail: the two execution mechanisms (AppleScript vs IMAP RENAME), the imap_required error for missing credentials, and the unsupported_gmail_system_label refusal with its rationale. This is valuable context that structured fields cannot express.

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 front-loaded with the purpose statement and uses headers, bullets, and inline code formatting to keep distinct behaviors scannable. It is longer than average, but every section maps to a concrete operational concern (delivery paths, validation, refusal conditions) so no sentence is wasted. Formatting trades some brevity for readability and earns its 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?

For a tool with 4 parameters, two execution paths, and multiple edge cases, the description is remarkably complete. It covers prerequisites (IMAP Keychain credentials), the validation rule, both error_type outcomes, and the Gmail system-label distinction between refused and allowed paths. An output schema exists, so return-value prose is appropriately omitted; nothing needed to call this correctly 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 per calibration the baseline is 3. The schema already thoroughly documents each parameter (leaf-name sanitization, None semantics, empty-string top-level move). The description adds value by explaining the interaction between new_name and new_parent — how their combination selects the delivery path — which goes slightly beyond the schema, but not enough to exceed baseline.

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-plus-resource statement — 'Rename and/or re-parent (move) an existing mailbox' — that clearly differentiates this from its siblings create_mailbox, delete_mailbox, and list_mailboxes. The two delivery paths further specify the operation's scope without ambiguity.

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?

It gives strong conditional guidance: which path executes depending on whether new_name vs new_parent is set, when IMAP credentials are needed, and the validation requirement that at least one parameter be provided. It enumerates the two refusal conditions and their trigger criteria. It stops short of explicitly naming alternative tools or when-not-to-use scenarios, but the path selection logic is thorough enough that an agent can route correctly.

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