outlook_reply

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is known. The description adds nothing beyond that: it never says the reply is sent immediately and irreversibly, whether it postdates into the source thread, or whether reply_all has recipient-broadening risk — the one behavior that matters most for this tool.

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?

Two short sentences, no filler, with the core action front-loaded and the routing rule second. Nothing in it is redundant.

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?

A mutation tool with no output schema, 0% schema coverage, and only terse boolean annotations needs the description to explain side effects and required inputs. It omits whether the reply is sent or drafted, what permissions are needed, and how reply_all changes recipients.

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 0% across 4 parameters, so the description carries the full burden of explaining message_id, body, is_html, and reply_all. Its parenthetical '(or reply-all)' gestures at the reply_all flag but conveys no semantics for it or for the other three 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?

States a specific verb (reply) and resource (email message) and distinguishes the reply-all variant. It names one sibling, outlook_rsvp, but does not differentiate from the closer siblings outlook_forward or outlook_send_message, so an agent still has to reason about which send-path applies.

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 one explicit routing rule: use this for email, use outlook_rsvp for calendar invites. That covers the calendar/email boundary but leaves the far more likely confusion (reply vs forward vs send_message vs send_draft) unaddressed, so guidance is partial.

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