gmail_delete_label

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond annotations by explicitly stating that messages are not deleted—'Messages keep their content but lose the label'—which clarifies the exact scope of the destructive operation. This is a meaningful disclosure of what gets destroyed and what does not.

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 extremely concise: one clear sentence explaining the operation's effect, followed by a minimal parameter note. Every sentence earns its place, and the key behavioral fact is front-loaded. There is no fluff or repetition of schema data.

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 simple one-parameter destructive tool with annotations covering safety and idempotency, the description covers all essential calling information: the action, the effect on messages, and the source of the label_id. The presence of an output schema means not describing return values is acceptable. Minor gaps like irreversibility or permission requirements are already implied by annotations and the simple operation.

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 schema offers only a title and type for label_id, with 0% description coverage. The description compensates by specifying that label_id should be 'Label id from gmail_list_labels,' giving the agent a concrete source for the parameter. For a single-parameter tool, this is sufficient added meaning beyond the schema.

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 verb ('Delete') and resource ('a label'), and immediately clarifies the non-destructive effect on messages: 'Messages keep their content but lose the label.' This clearly differentiates it from sibling tools like gmail_trash or gmail_modify_labels without needing to open their schemas.

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 no explicit guidance on when to use this tool versus alternatives. It tells the agent where to get the label_id ('from gmail_list_labels') but does not state conditions, exclusions, or trade-offs relative to sibling tools. Usage context is only weakly implied by the verb 'Delete'.

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