Modify Gmail Message Labels

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description is not contradicting them. The description adds value by explaining the side effects of specific label choices (removing INBOX archives, adding TRASH deletes), which is meaningful behavioral context beyond the raw annotation. However, it does not mention that changes are immediate, whether label removal can permanently delete messages, or any permissions/user-consent implications. With annotations present, the description's additional behavioral detail earns a 3 rather than lower.

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 concise and front-loaded with the core action. The two example sentences are useful and non-redundant. It could be slightly improved by adding a sentence on label ID format, but the current length is appropriate and every sentence serves a purpose.

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 single-message label modification tool, the description is fairly complete: it states the action, gives the two most important use cases, and annotations cover the destructive nature. The output schema exists (though not shown) which may cover return values. It could have mentioned the relationship to batch_modify_gmail_message_labels and that custom label IDs are allowed, but the essentials are present.

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?

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description's examples imply the meaning of add_label_ids and remove_label_ids but do not add technical details like label ID format (e.g., 'INBOX', 'TRASH', custom ID). Since the schema already documents all parameters, the description does not need to compensate for gaps; it just doesn't add much beyond the examples.

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 states a specific action ('Adds or removes labels from a Gmail message') and immediately provides two concrete operational examples (archiving via removing INBOX, deleting via adding TRASH). This clearly distinguishes the tool from siblings like manage_gmail_label (which manages label definitions) and batch_modify_gmail_message_labels (which operates on multiple messages).

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 explicit usage context for common operations (archive and delete), which helps the agent understand when to use this tool. However, it does not explicitly mention when to prefer batch_modify_gmail_message_labels over this single-message tool, nor does it state any exclusions for when not to use it. The practical examples imply usage well but leave the single-vs-batch distinction implicit.

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