send-email

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

With no annotations, the description fully discloses that this sends real email immediately, cannot be unsent, and requires explicit user confirmation. It also details transport behavior (applescript vs smtp) and environment config requirements.

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?

Front-loaded with usage conditions, then return value, then safety. Every sentence is informative and necessary. No repetition or fluff.

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?

Given 8 parameters, 3 required, existence of output schema, and presence of many sibling tools, the description covers all key aspects: when to use, alternatives, safety, transport details, return value. It is sufficiently complete.

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 63%. The description adds context beyond the schema for transport (explains smtp vs applescript and env config) and attachments (file paths vs inline objects). However, not all parameters receive additional explanation; some are left to the schema.

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 clearly states 'send a single email now' and distinguishes from sibling tools like create-draft, reply-to-message, send-serial-email. It specifies verb (send), resource (email), and scope (single, immediate).

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 provides 'Use when' and 'Do not use when' conditions with named alternatives (create-draft, reply-to-message, forward-message, send-serial-email). This fully guides the agent on when to invoke this tool versus others.

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