Mail Mark Message

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

The description adds no behavioral information beyond the annotations. While destructiveHint=false provides some safety context, the description does not disclose what 'mark' modifies, whether it changes read state, requires mail permissions, or has side effects. With an idempotentHint=false, this gap is more significant.

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 short, but it is under-specified boilerplate rather than genuinely concise. It contains no useful operational content, so the brevity does not contribute to agent comprehension.

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 mail mutation tool with two required parameters and many sibling mail tools, the description is severely incomplete. It does not clarify the marking operation, the meaning of is_read, or how it differs from related mail tools. The output schema exists but cannot compensate for the absence of core semantics.

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 needed to explain message_id and is_read, but it does not mention either parameter. The schema's property names are somewhat self-explanatory, but the description adds zero semantic value and fails to compensate for the missing parameter documentation.

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 only says it is a 'Delegated Apple domain tool' exposed through Apple-Tools-MCP, which restates the tool name without defining what the tool actually does. The action 'mark' is only inferable from the tool name and the is_read boolean parameter, not from the description itself.

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?

There is no guidance on when to use this tool versus alternatives like mail_move_message, mail_archive_thread, or mail_delete_message. No context, prerequisites, or exclusions are provided, leaving the agent to guess how this tool fits into the mail workflow.

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