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

The description adds meaningful behavioral context beyond the destructiveHint annotation: email is sent as the user, external mail goes over SMTP under the instance's domain, replies return to the user's inbox, and there is a cost implication. It does not mention irreversibility or failure behavior, but the annotation already signals side effects and the description enriches that sufficiently.

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 three compact sentences with the primary action front-loaded. Every sentence adds distinct information: core action, recipient behavior, prerequisite/configuration requirement. No filler or redundant schema repetition.

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 send tool with three required parameters and an output schema absent, the description covers the action, recipient distinctions, cost implications, identity context, reply behavior, and configuration prerequisite. It is complete enough for an agent to select and invoke it correctly without additional clarification.

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?

The schema already documents all three parameters, so this is a good baseline. The description adds extra semantic detail beyond the schema, especially for 'to', explaining that usernames are free and full addresses are charged and leave via SMTP. It also reinforces contacts_find resolution, which the schema mentions.

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 and resource: 'Write to somebody, as you.' It distinguishes sending mail from reading/searching mail by clarifying the two recipient forms (internal username vs external email over SMTP) and is clearly differentiated from mail_inbox, mail_info, and mail_search.

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?

It gives explicit usage context: internal usernames are free, external addresses are charged, and recipients should be resolved with contacts_find first. It also states a required condition ('MAIL_DOMAIN configured on the instance') for external sending, which helps decide when to use the tool and what prerequisites exist.

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