star_emailsMarks up to 100 email messages as starred in a connected account, helping organize important mail for quick retrieval.
Star messages.
| Name | Required | Description | Default |
|---|---|---|---|
| accountId | No | Account to operate on. Optional when exactly one account is connected. | |
| messageIds | Yes | Messages to change, up to 100 IDs |
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes |
Changes observed during successful MCP inspections.
v0.19.0Input schema / properties / accountId / anyOfPrevious value: -[
- {
- "minLength": 1,
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "maxLength": 512,
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / messageIds / descriptionPrevious value: -"Messages to change, up to 100 distinct IDs"New value: +"Messages to change, up to 100 IDs"Input schema / properties / messageIds / items / maxLengthAdded value: +512Input schema / properties / messageIds / maxItemsAdded value: +100v0.16.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — it does not state that starring is reversible, that it applies to all listed IDs, or what happens to already-starred messages.
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 words, fully front-loaded, with zero waste — but the brevity is under-specification rather than disciplined conciseness. There is room for one short sentence of usage context without bloat.
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?
With a fully described 2-parameter schema, complete annotations, and an output schema, most of what an agent needs is in structured fields, so the tool is still callable. The description nonetheless omits the bulk nature of the operation and any routing guidance versus the many sibling mutation tools.
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 100%; both `accountId` (optional when one account is connected) and `messageIds` (up to 100 IDs) are fully documented in the schema. The description contributes no additional parameter meaning, so the baseline 3 applies.
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?
"Star messages" names a specific verb and resource, so the base purpose is inferable, but it does not clarify that it is a bulk operation (up to 100 IDs) nor distinguish it from siblings like `add_labels` or `unstar_emails`. It also says "messages" rather than emails, leaving minor ambiguity against a large sibling set.
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?
No when-to-use or when-not-to-use guidance is given, and no alternative (e.g. `unstar_emails` for the inverse, `add_labels` for tag-based organization) is named. The agent must infer selection from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.