create-reply-all-draft

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

The description adds valuable behavioral details beyond the annotations: specifying both comment and body returns a 400 error, supplying Message.body replaces the whole draft body (excluding quoted history), and signatures are added by Outlook client not via Graph. It also explains the MIME encoding requirement. These details complement the annotations (destructiveHint: true) without contradiction.

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 somewhat long but well-organized: a clear opening statement, bullet points for JSON and MIME formats, and a tip at the end. It front-loads the core purpose and uses structure to separate concerns. Some redundancy exists (e.g., repeating the 400 error), but overall it is appropriately sized for the tool's complexity.

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 nested object schema and the absence of an output schema, the description covers the essential information an agent needs: format options, key constraints, recipient behavior, and the body replacement caveat. It does not detail MIME header specifics, but that is likely peripheral for draft creation. The description is sufficient for correct invocation in most scenarios.

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 high (80%), but the description enhances understanding: it clarifies the relationship between Comment and Message.body, the constraint on specifying both, and the use of replyTo vs from recipients. It also explains the messageId parameter's expected format. This goes beyond the schema's bare property descriptions.

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 the specific action: 'Create a draft to reply to the sender and all recipients of a message.' It distinguishes this from related tools like create-reply-draft (which replies only to sender) and create-forward-draft, and mentions two formats (JSON/MIME). The verb and resource are explicit, and the scope (reply-all) is unambiguous.

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 substantial guidance: when to use JSON vs MIME, the constraint not to specify both comment and body, and the rule about using replyTo recipients per RFC 2822. It also mentions the alternative of doing a single-action reply-all. However, it does not explicitly name sibling tools like create-reply-draft for comparison, so the when-to-use distinction is implied rather than explicit.

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