reply-all-mail-message

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

Annotations indicate destructiveHint=true and openWorldHint=true, but the description adds meaningful behavioral details: it mentions that specifying both comment and body results in HTTP 400, describes replyTo handling per RFC 2822, states that the message is saved in the Sent Items folder, and offers the draft alternative. It does not contradict annotations and provides beyond-annotation context about error conditions and delivery behavior.

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 structured with clear bullet points for JSON and MIME formats, and a tip at the end. It is moderately long but each section conveys necessary information about constraints and usage. The primary purpose is front-loaded, and the alternative draft approach is mentioned early. While it could be slightly trimmed, it remains well-organized and readable.

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 the complexity (two formats, many possible message properties, no output schema), the description covers essential invocation details: required parameters (messageId, body), format-specific requirements, error conditions, and the saving behavior. It does not describe the response structure, but since there is no output schema and the tool returns a message object (per typical Graph API), the lack of explicit return documentation is acceptable. The description is sufficient for correct use.

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 covers 80% of parameters with descriptions (e.g., messageId, confirm, includeHeaders). The description adds critical semantics for the 'body' object by clarifying the mutually exclusive constraint between 'Comment' and 'Message' (body) and the replyTo precedence rule. For MIME format, it specifies base64 encoding and header/content requirements, going beyond the schema's generic object definition. This helps the agent avoid common mistakes (e.g., sending both fields).

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 states a clear purpose: 'Reply to all recipients of a message using either JSON or MIME format.' This is specific (replies to all recipients, not just the sender), mentions two explicit format options, and distinguishes it from sibling tools like 'reply-mail-message' (which likely replies to a single recipient) through context. The name is also descriptive, but the description adds the format dimension and clarifies the scope (all recipients).

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 practical usage guidance by contrasting with creating a draft: 'Alternatively, create a draft to reply-all to a message and send it later.' This gives an alternative for deferred sending. It also differentiates between JSON and MIME usage scenarios, including when to use 'comment' vs 'body'. However, it does not explicitly state when to use this tool over sibling 'reply-mail-message' (single reply) or 'reply-all' vs 'reply' distinctions, relying on the tool name for that differentiation.

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