outlook_attach_to_draft

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

Goes well beyond annotations: it discloses a path-resolution rule (paths resolve inside attachments_dir, bare filenames looked up there, paths outside refused), an automatic fallback behavior (>3MB switches to upload-session), and the return value (new attachment IDs). These are exactly the behavioral traits that make or break a correct call.

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?

Three short focused sentences; the core action and the >3MB threshold are front-loaded, then the path-resolution rule, then the return value. The parenthetical default (~/.outlook-mcp/attachments) is useful, not filler. Slight density but no waste.

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 2-param mutation with no annotations beyond the safety hints, the description covers what it does, how paths resolve, the large-file fallback, and what it returns. It leaves no meaningful gap an agent would need to call this correctly.

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 0%, so the description must carry the full burden. It clearly explains the semantics of attachment_paths (resolution relative to attachments_dir, default location, refusal of out-of-tree paths) and implies draft_id targets an existing draft. This fully compensates for the missing schema 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?

Specific verb (add) + resource (attachments) + scope constraint (existing draft), and it distinguishes itself from siblings like outlook_send_with_attachments and outlook_list_attachments. The mention of 'auto-switches to upload-session for files >3MB' further pins down exactly what this tool does.

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?

Clear implied context: it operates on an existing draft, and it points to outlook_remove_draft_attachment as the follow-up inverse action. It doesn't explicitly exclude anything (e.g. use outlook_create_draft vs this tool) but the draft-scoped framing is strong enough to route the agent correctly.

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