gmail_apply_label

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful context: it states the tool auto-creates labels (creating it first if needed), that system labels get rejected, and that it returns the label id applied. These add behavioral detail beyond the annotations, though the rejection specifics could be seen partly implied by the idempotentHint.

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 two sentences totaling roughly 50 words, all substantive. The first sentence declares purpose and auto-creation; the second explains exclusions and return value. Zero filler, front-loaded with the core action, and every clause earns its place.

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?

Given the tool's moderate complexity (4 params, output schema present, idempotent annotations provided), the description compactly covers the essential behavioral contract: what it does, what it rejects, auto-creation behavior, and return value. The output schema handles return structure, and the description covers the restrictions an agent needs to avoid misuse.

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 description coverage is 0%, so the description must compensate for the 4 parameters. It clarifies label_name semantics (must be a user-created label, auto-created if needed) and mentions the return value. However, it doesn't explicitly address message_id format or the create_if_missing parameter behavior in detail, though the description's 'creating it first if needed' implies create_if_missing semantics. With an output schema present and this level of guidance for a moderately simple tool, a 4 is appropriate.

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 clearly states the action ('Attach a custom label to a message') with a specific verb+resource combination. It distinguishes itself from siblings by explicitly noting the scope (custom labels only, not system labels) and the auto-creation behavior, which sets it apart from other gmail tools in the sibling list.

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 explicitly states when NOT to use this tool: system labels are rejected, so it cannot trash, spam, or archive. This is a clear exclusion criterion that prevents misuse, and it implicitly tells the agent which alternatives (sibling tools) to consider for system-label operations.

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