create_mail_reply_draft

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

The annotations give readOnlyHint=false, idempotentHint=false, and the description adds meaningful operational detail: 'Body is literal plain text; replyAll defaults to false', 'Returns a verified draft and Outlook link', and the caution to 'Never sends'. The retry guidance aligns with the non-idempotent behavior. No contradictions 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 three sentences with no filler. The first sentence fronts the core purpose and scoping, the second states two key parameters, and the third gives return value and retry strategy. Every sentence earns its place.

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 tool with no output schema, the description states the return (verified draft and Outlook link) and also gives a safety net for retry behavior. It clarifies the exact usage condition and that it never sends. The combination of parameters, behavior, and retry guidance provides what an agent needs to call it appropriately.

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 only 33% (only messageId has a description). The description compensates by adding literal plain text semantics for body and stating the replyAll default. The schema already clarifies that messageId is the exact ID from a mail tool, so the description fills the low-coverage gap for the other two parameters.

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 specifies the action: 'Save an unsent reply to an exact message in your own Outlook mailbox.' It is distinguished from any sending tool by explicitly stating 'Never sends' and from read-only tools by the create/save verb. The phrase 'Use only for a reply the student requested' adds further scope differentiation.

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?

The description provides explicit when-to-use ('Use only for a reply the student requested') and a clear constraint ('Never sends'). It also gives retry guidance ('inspect Drafts before any retry'), but does not explicitly name an alternative tool. The absence of a direct sibling tool makes this sufficiently actionable.

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