open_in_mail

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

Adds valuable behavioral context beyond annotations: whole_thread=True opens each message in its own window rather than a threaded view, and 'Changes nothing.' consistently reinforces the readOnlyHint=true annotation. No contradiction with annotations.

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 compact and front-loaded: purpose first, then usage conditions, then parameter nuance and an alternative. Every sentence earns its place without redundancy.

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 simple read-only UI tool with an output schema and strong annotations, the description covers trigger conditions, parameter intent, side effects, and alternatives. It is complete enough for an agent to select and invoke 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 so thoroughly for whole_thread, explaining the 'own window' behavior and caution against overuse. message_id is implied by the tool purpose but not explicitly detailed; still, the meaning is clear enough.

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 opens with a specific verb + resource: 'Open a message in Apple Mail on screen.' It also distinguishes from siblings by explaining that chat clients strip message:// links, making this the reliable path, and by referencing get_thread for reading in chat.

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?

Provides explicit when-to-use conditions ('when the user asks to open, show or pull up a message'), explicit when-not-to-use guidance for whole_thread, and a direct alternative ('use get_thread' to read a conversation in chat). This is clear, actionable differentiation.

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