list_labelsLists all labels, system and user-created, with their IDs for a specified Gmail account to verify label existence before applying it to messages.
List the labels of an account, system and user-created, with their ids. Call this before label_message if you are unsure a label exists.
| Name | Required | Description | Default |
|---|---|---|---|
| account | Yes | Configured account: the email address, or the alias given at setup. |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat them. It adds context about what categories of labels are returned and how results relate to label_message. It does not describe pagination or exact response shape, but those are minor for a simple label listing.
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?
Two sentences, with the primary action and scope in the first and usage guidance in the second. No filler, no repetition of schema content, and the information is effectively front-loaded.
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 one-parameter read-only listing with rich annotations, the description gives the required scope, the output contents (labels and ids), and when to call it relative to label_message. The absence of an output schema is compensated by explicitly stating that ids are included.
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 coverage is 100%, with the single account parameter already described as an email address or alias. The description only restates the account scoping ('of an account') and adds no new syntactic or format guidance. Baseline 3 is appropriate when the schema does the heavy lifting.
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?
States a specific verb ('List'), the resource ('labels of an account'), and the useful detail that both system and user-created labels are included with ids. The mention of 'Call this before label_message' also distinguishes it from the only sibling that operates on labels.
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?
Explicitly instructs when to call: before label_message when unsure a label exists. It points at the alternative label_message by name, giving clear routing guidance. It doesn't enumerate other alternatives, but none are needed for a pure list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.