outlook_remove_event_attachment

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this is a destructive write. The description adds that exactly one attachment is removed and where to source its ID, but says nothing about irreversibility, permissions, or the effect on the event beyond annotations.

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?

A single front-loaded sentence with the key provenance detail in parentheses; every clause earns its place and nothing is wasted.

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 simple two-parameter destructive mutation with no output schema, the description covers what is removed and where IDs come from. It could add a note on irreversibility or what happens if the attachment ID is stale, but annotations already flag the destructive nature.

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 compensate, and it does meaningfully for attachment_id by pointing to outlook_get_event's `attachments` field. event_id is only named, not explained (format, calendar scope), leaving a minor gap.

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 and resource ('Remove one attachment from an event'), which unambiguously identifies a mutation on an event's attachment. It does not explicitly contrast with the counterpart sibling outlook_attach_to_event or with update_event replacement, so sibling differentiation is only implicit.

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 parenthetical gives useful context on where the IDs come from (outlook_get_event's `attachments`), but there is no explicit when-to-use/when-not guidance or named alternative (e.g., removing all attachments requires a different path). Usage is implied by the name and description.

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