label_message

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), it adds context the annotations do not carry: the action is reversible, needs no confirmation, is capped at 100 items per call, and createMissing throws an error rather than silently skipping when false.

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?

Front-loaded with the action and scope, then label vocabulary, then behavioral caveats, then the args. The high-density shorthand ('Trash: trash_*; spam, sent and drafts: never') packs a lot into one clause without wasting words.

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?

An output schema exists so return values need no explanation. For a non-destructive, idempotent mutation, the description covers inputs, label taxonomy, limits, error cases, and scope — nothing an agent needs before calling 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 description coverage is 0%, so the description does all the work — and it covers all three parameters: messageId accepts a single ID or a list, labelIds accepts IDs or exact names (with system vs user label distinction and a pointer to list_labels), and createMissing's default and failure behavior are spelled out.

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?

Opening sentence states a specific verb and resource ('Add labels to a message (or to a list of messages)'), which immediately separates it from unlabel_message and the thread-scoped label_thread. An agent can pick the right tool from the first clause alone.

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 concrete use mappings (archive = unlabel INBOX, mark read = unlabel UNREAD, star = label STARRED) and states which content types are off-limits (spam, sent, drafts). It doesn't explicitly point to label_thread for thread-scoped labeling or name unlabel_message as the removal path; these are only implied by the mappings.

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