outlook_send_with_attachments

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

Annotations confirm this is a write operation (readOnlyHint=false) but the description adds real value: it discloses the auto-switch to upload-session for files >3MB, the attachment directory sandbox rule, and the 'refused' behavior for out-of-directory paths. That is meaningful behavioral context a caller must know. It does not, however, cover permission/auth requirements or the fact that sending is irreversible.

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?

Front-loaded with the core action and the key behavioral twist in a single clause, then terse parameter notes. No filler, but the line break/parenthetical style is slightly fragmented rather than smoothly structured.

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 9-parameter mutation with no output schema and 0% schema coverage, the description handles the two trickiest parameters well but leaves the majority of required and optional fields (to, subject, body, cc, bcc, is_html) entirely unexplained. A caller gets the safety/behavior picture but incomplete parameter guidance.

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%, so the description must carry the parameter burden — it clarifies attachment_paths resolution and reply_to routing, which is genuinely helpful. However, 7 of 9 parameters (to, cc, bcc, subject, body, is_html, importance) receive no explanation at all, leaving half the surface undocumented.

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 (Send) plus resource (email) plus distinguishing qualifier (with file attachments), and even notes the internal escalation behavior for large files. It clearly differentiates from sibling outlook_send_message by naming the attachment requirement.

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 implies when to use it (you need file attachments) versus siblings, but it never explicitly says 'use outlook_send_message when there are no attachments'. The bare filename vs. path resolution rules provide some context, but no explicit when/when-not routing is stated.

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