modify_gmail_message_labels

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains special label behaviors (INBOX/TRASH) and states the return type, but it omits details about permissions, idempotence, or error conditions. It adds helpful context but is not exhaustive.

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 well-structured with a direct summary, practical examples, and an Args section. While the Args section overlaps with the schema, it is reasonably compact and the examples justify the extra length. No extraneous content.

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 moderately simple mutation tool, the description covers the core operation, special cases, and return value. It lacks discussion of permissions or contrast with the batch sibling, but given the tool's simplicity and the presence of an output schema, it is sufficiently complete for most agent use cases.

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 descriptions cover 50% of the parameters (add_label_ids and remove_label_ids), and the description's Args section adds brief context for the other two (user_google_email, message_id). However, the descriptions are minimal and don't explain where to obtain label IDs or how the parameters interact, so the added meaning is only slightly above the schema 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 'Adds or removes labels from a Gmail message,' which is a specific verb and resource, clearly distinguishing the tool from label management or batch operations. The examples further clarify the purpose.

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 provides concrete usage examples ('To archive an email, remove the INBOX label'), which imply when to use these parameter combinations. However, it does not explicitly contrast with sibling tools like batch_modify_gmail_message_labels or manage_gmail_label, so the guidance on when to choose this tool vs alternatives is only implicit.

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