create-calendar-event-attachment-upload-session

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds substantial non-obvious behavior: it returns a pre-authenticated uploadUrl that the caller must PUT bytes to itself, in ranges up to 4MB, and the transfer is resumable if the connection drops. It does not restate the destructive/confirm semantics already carried by the schema's confirm parameter and annotations, so it stops short of 5.

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 TIP block is tightly front-loaded and high value, but the first paragraph is a verbatim chunk of Graph documentation that ends in a dangling fragment ('The following are the steps to attach a file to an Outlook item using an upload session: See attach large files... for an example.') with no actual steps. That sentence does not earn its place and dilutes the otherwise efficient structure.

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?

With no output schema, the description correctly compensates by describing the return value (a pre-authenticated uploadUrl) and the subsequent PUT usage, plus the size band that gates use. The remaining gap is the dangling step-list reference, which leaves the enumeration promised in the text unfulfilled.

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 80%, so the baseline is 3; the description goes beyond it by supplying a concrete body example ({ AttachmentItem: { attachmentType: 'file', name: 'report.pdf', size: 5000000 } }) and the 4MB PUT range, which is not encoded in the schema. The eventId and confirm semantics are left to the schema, which documents them well.

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 states a specific verb and resource (create an upload session to attach a file to a specified Outlook item, which may be a message or event) and explicitly names the sibling tool to use instead for small files. An agent can distinguish this from add-calendar-event-attachment or create-mail-attachment-upload-session without opening any schema.

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 an explicit size threshold ('between 3 MB and 150 MB') and names the condition that selects the alternative ('smaller than 3 MB, do a POST on the attachments navigation property' / 'use add-calendar-event-attachment'). The two-step follow-up workflow (call this, then PUT to the returned uploadUrl) is also spelled out.

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