Set an email's read status (read or unread) and starred status (star or unstar) by ID, so agents can update mailbox flags without fetching full message content.
标记邮件：read=True 已读 / False 未读；starred=True 加星 / False 去星。至少传一个。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| read | No | ||
| starred | No |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v0.1.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden for a mutation tool. It discloses the "at least one flag" constraint but says nothing about permissions required, idempotency/reversibility of the flag change, whether unmentioned flags are left untouched, or whether side effects (notifications, sync) occur.
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 short clauses plus a constraint sentence, flag semantics front-loaded, zero filler. Every element earns its place and the constraint is stated last, which is the natural reading order for the reader.
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 not be described. For a 3-parameter mutation tool with no annotations, though, the description omits the identity/scope of `id` (single message vs batch) and any safety context, leaving the definition only partially sufficient to call correctly.
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. It does explain the boolean semantics of `read` and `starred` (True/False meaning) plus the at-least-one rule — real added value beyond the bare titles. But the required `id` parameter is left unexplained: no indication whether it is a single message ID, a comma-separated list, or an ID format, leaving a critical gap.
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 uses a specific verb+resource ("标记邮件" / mark email) and immediately enumerates the two flag dimensions it can change (read/unread, starred/unstarred), which is far more concrete than the bare tool name. It does not name any sibling for comparison, but none of the siblings (move_email, delete_email, get_email) overlap with this purpose, so ambiguity is low.
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?
"至少传一个" gives a real usage constraint (at least one of read/starred must be supplied), which is genuinely needed since the schema marks only `id` as required and both flags default to null. However, there is no guidance on when to prefer marking over move_email/delete_email workflows, nor on whether repeated calls are safe or what happens if both flags are omitted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.