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

Annotations already flag the operation as destructive and not read-only. The description adds valuable context by explaining that the organizer is notified by default unless sendResponse is set to false, and it provides an example of the optional body. This goes beyond the annotations and clarifies the side effect of notifying the organizer.

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 description is concise: two sentences and a tip. The purpose is front-loaded, and the tip provides a compact, actionable clarification. No unnecessary words, and the structure flows logically from purpose to usage detail.

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 tool with five parameters and a nested object, the description covers the primary action and key behavior (organizer notification). The schema handles the remaining parameters, including the confirm gate. It does not mention the confirm parameter, but that is documented in the schema, so the description is mostly complete. It could be slightly richer about destructive implications, but the annotations compensate.

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 high (80%), but the description enhances parameter understanding by showing an example of the body parameter with sendResponse and comment, and explicitly explains that sendResponse: false suppresses organizer notification. This adds meaning beyond the schema's default value and property types.

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 clearly states the action: 'Accept the specified event in a user calendar.' It also specifies it accepts a 'meeting invitation' in the tip, which distinguishes it from sibling tools like decline-calendar-event or cancel-calendar-event. This is a specific verb+resource with enough context to understand its scope.

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 does not provide any guidance on when to use this tool versus its many sibling calendar-event actions (e.g., tentatively-accept-calendar-event, decline-calendar-event). It only explains the optional sendResponse behavior, but no selection criteria or alternatives are mentioned, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare that this is a non-read-only, open-world, destructive-capable mutation. The description adds important behavioral context beyond annotations: the 3 MB size cap and the organizer's ability to later update the event so attendees receive the attachment. It does not discuss the confirm gate or auth/permission nuances, but the schema covers confirm.

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 description is short and front-loads the core action and size limit. The size cap is repeated in the TIP section, which is slightly redundant but still useful because that section also contains the exact body format.

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 nested-body mutation with no output schema, the description covers the key operational details: size limit, body shape, and the large-attachment alternative. It omits return behavior and confirmation-gate behavior, but the confirm parameter is well documented in the schema.

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 high at 80%, so most parameters are already documented. The description adds critical meaning not present in the schema: the body must include @odata.type set to #microsoft.graph.fileAttachment and contentBytes as base64, which is essential for correct invocation.

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: add an attachment to an existing calendar event. It also explicitly distinguishes the small-attachment path from the upload-session sibling for attachments of 3 MB and above.

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 a clear usage condition: under 3 MB use this tool, and at 3 MB or above use create-calendar-event-attachment-upload-session. This directly routes the agent to the correct sibling without needing to infer limits from the schema.

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

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

The annotations declare readOnlyHint=false and destructiveHint=true, indicating this is a mutating operation. The description does not add behavioral context beyond that, such as confirming that rows are appended to the end of the table, that it does not modify existing rows, or any side effects like overwriting data if the table changes. With no additional context, an agent knows it is destructive but not the precise behavior, which is a notable gap.

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 description is succinct, using a single line for the core action and a well-formatted tip that provides the essential body example. It is front-loaded with the primary purpose, and every element earns its place: the action, the body template, and the column-count constraint. There is no verbose or redundant content.

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?

Given the tool's moderate complexity (nested body, 4 required parameters) and no output schema, the description adequately covers the key usage: how to structure the values array and the column constraint. However, it does not mention what happens after execution (e.g., returns the added rows) or the confirm gate behavior (though confirm is documented in the schema). This is acceptable for a simple tool, but a mention of the append operation's effect would have made it more complete.

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?

The schema covers most parameters (86% coverage), but the description adds crucial semantics for the 'body' parameter by showing the exact structure: an array of arrays where each inner array is a row. It also clarifies the constraint that values must match the number of columns. This goes beyond the schema's terse description of 'values' and helps the agent construct a correct payload.

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: 'Add Excel table rows.' This clearly distinguishes it from sibling tools like list-excel-table-rows, update-excel-table-row, and delete-excel-table-row. The added tip reinforces the action by showing an example of the body payload, so an agent can immediately grasp the tool's purpose.

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 does not explicitly state when to use this tool versus alternatives such as update-excel-table-row or delete-excel-table-row. The purpose is implied by the name, but there is no explicit 'use this when you need to append rows' or 'use this instead of update for new rows.' This leaves some ambiguity for an agent choosing among the Excel table row operations.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description goes beyond them by disclosing a concrete failure mode (truncated contentBytes yields 400 UnableToDeserializePostBody) and the verbatim-base64 requirement, which is real operational guidance. It stops short of discussing message-size effects or permissions, so not a 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 actionable content is well front-loaded in the TIP, but the middle sentences ('An attachment can be one of the following types: All these types...') are truncated doc boilerplate that promises a list it never delivers and wastes the reader's attention.

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 5-param, nested-body mutation with no output schema, the description covers the essentials: correct payload shape, size threshold routing, and the primary error condition. It leaves response behavior to the includeHeaders/excludeResponse schema fields, which is reasonable. Slightly incomplete on whether an existing attachment with the same name is replaced.

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%, but the schema's `body` object does not even declare `@odata.type`, so the description supplies genuinely missing semantics with a concrete payload example ('{"@odata.type": "#microsoft.graph.fileAttachment", "name": ..., "contentBytes": ...}'). It also constrains contentBytes to complete, non-truncated base64. It does not explain confirm/includeHeaders/excludeResponse, but those are documented in the schema.

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?

Opens with a concrete verb+resource ('create a new Attachment') and the TIP makes the actual operation unambiguous: it attaches a base64 file to a mail message. The dangling sentence ('An attachment can be one of the following types:' with no list) is vestigial boilerplate that adds noise but not confusion about the purpose. It also implicitly distinguishes itself from create-mail-attachment-upload-session by the size rule.

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?

Gives an explicit, testable routing rule: under 3MB use this tool, at 3MB and above use create-mail-attachment-upload-session, which 'rejects anything smaller.' That is exactly the when-to-use / when-not-to-use / alternative pattern an agent needs, and it names the sibling directly.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial behavior: the event is moved to Deleted Items, it can cancel occurrences of recurring meetings, it sends a cancellation message, and attendees get an HTTP 400 error. These are behavioral traits not covered by annotations. While the description doesn't explicitly mention the confirm gate parameter, that is documented in the schema. It adds significant context 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?

The description is informative but somewhat verbose, with a detailed first paragraph and a separate tip. However, it is well-structured: the purpose is front-loaded, then details, then a quick-reference tip. Every sentence adds value, though there is slight repetition of the cancellation purpose between the first paragraph and the tip. Not overly long for the complexity.

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 complex tool with organizer-only semantics, recurring event support, and error behavior, the description covers all key aspects: what it does, the move to Deleted Items, the custom message, the difference from delete, and the attendee error. No output schema exists, so explaining return values is not required. An agent has sufficient information to decide when and how to call this tool 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 description coverage is 80%, so most parameters are documented. The description only adds a mention of the Comment field in the tip, which is already in the schema. It doesn't provide additional meaning for parameters like eventId or confirm beyond what the schema offers. The baseline for high coverage is 3, and the description doesn't elevate it.

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 clearly states the action: the organizer of a meeting can cancel an event and send a cancellation message. It specifies the resource (calendar event) and the action (cancel), and distinguishes it from delete-calendar-event and decline-calendar-event by noting the organizer-only restriction and the ability to send a custom message. This fully differentiates it from siblings without needing to inspect schemas.

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 explicitly says when to use this tool instead of delete-calendar-event (when attendees should see 'Canceled') and directs attendees to use decline-calendar-event instead. It also explains the error condition for attendees, giving clear guidance on when not to use the tool. No inference is required.

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

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

Annotations already declare destructiveHint: true, so the description doesn't need to restate that. It adds valuable behavior details about what each applyTo value does (wipes values vs resets formatting vs both), which goes beyond the annotation. It does not contradict annotations and provides useful context for resetting worksheet sections.

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 description is two sentences, front-loads the core purpose ('Clear an Excel range'), and then provides a concise, high-value tip. There is no fluff; every sentence earns its place. The structure is efficient and scannable.

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 destructive clear operation, the description covers the key behavior (what gets cleared), the options, and a typical use case. The schema handles the remaining parameters (path segments, confirm, etc.). No critical information is missing for an agent to call this tool 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?

The schema has 88% coverage and already documents most parameters. The description significantly enriches the body.applyTo parameter by explaining the allowed values and their exact effects, which the schema only lists as a string. This adds meaningful semantics beyond the schema baseline.

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 clearly states the action ('Clear an Excel range') with a specific resource and intent. It also explains the three modes (Contents, Formats, All) and their effects, which distinguishes it from sibling tools like update-excel-range or format-excel-range. The purpose is unambiguous.

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 tip gives concrete usage context: 'Use this to reset a worksheet section before a fresh write rather than overwriting cell-by-cell.' This explains when to apply the tool, but it does not explicitly name alternative tools or state when not to use it. Still, the guidance is clear and actionable.

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

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

The description's semantics ('copy', 'duplicating', 'preserving an immutable snapshot') directly conflict with annotations' destructiveHint=true. Even though the description usefully discloses async execution and the 202/Location monitor response, the rubric requires a score of 1 when the description contradicts an annotation.

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 description is front-loaded with the operation, then gives a compact body example, response note, and use cases. It is efficient and scannable, though the three-item use-case list is slightly more expansive than strictly necessary.

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, mentioning '202 Accepted with a Location header pointing at a monitor URL' is helpful, but the async workflow is incomplete: it never says to poll the monitor URL, explains failure behavior, or covers body options such as childrenOnly and includeAllVersionHistory. Adequate, but with clear gaps.

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 83%, so the schema does most of the parameter documentation work. The description adds value beyond it with a concrete body example ('parentReference: { driveId: '...', id: '...' }, name?: 'New Name.xlsx'') and by connecting the 'new location and/or name' idea to the body fields.

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 opens with 'Copy a drive item' and elaborates 'Asynchronously copy a file or folder to a new location and/or name.' This gives a specific verb, resource, and scope, and it is naturally distinct from sibling move, delete, and share operations.

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 gives concrete when-to-use guidance: 'Ideal for duplicating templates..., bulk file provisioning, or preserving an immutable snapshot.' It clearly sets context but does not explicitly state when not to use the tool or name alternatives, so it falls short of a full 5.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=true, so the safety profile is known. The description adds behavioral context by specifying that it returns a newly created message with a new id, and it clarifies the destination folder format. It does not contradict the annotations, and it provides sufficient detail about the operation's effect and output.

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 description is concise and well-structured: the first sentence states the core purpose, the tip line expands on the body and return value, and the final sentence routes the user to the sibling tool. No redundant words, front-loaded with key info, and every sentence earns its place.

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?

Given the tool's moderate complexity (5 parameters, nested object) and no output schema, the description covers the essential usage: body structure, return value, and alternative. It does not dwell on confirm/includeHeaders/excludeResponse, but those are self-explanatory and documented in the schema. Minor gaps like permission requirements or error cases are not critical for an agent to invoke it 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?

The schema covers 80% of parameters with descriptions. The description adds meaningful semantics to the DestinationId parameter by providing concrete examples like 'inbox, archive, junkemail' and clarifying it accepts a well-known name or ID. This goes beyond the schema's generic string type and helps an agent format the request correctly.

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 clearly states the action: 'Copy a message to a folder within the user's mailbox.' It identifies the resource (message), the operation (copy), and the destination (folder). It also explicitly differentiates from the sibling tool by stating 'For moving instead of copying, use move-mail-message,' which disambiguates it from similar operations.

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 tells when to use this tool versus alternatives: it copies a message, and for moving, it points to move-mail-message. This explicit guidance helps the agent choose correctly. It also explains the body structure and return value, providing operational context within the same description.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is supplied. The description adds nothing beyond that: it does not explain what happens on duplicate names, whether the calendar belongs to the signed-in mailbox, what the confirm gate means in practice, or what the call returns.

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 opening sentence is front-loaded and clear, but the TIP's "Creates a new personal calendar" restates the first sentence, and the eleven-value color list duplicates the schema enum verbatim. Roughly half the text 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?

For a mutation tool with a deeply nested body object, no output schema, and annotations only, the description is thin: it omits return shape, error/duplicate behavior, and any permission or scope context. Only the minimal happy-path payload is covered.

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 high (75%), so the baseline is 3. The example body { name, color } implicitly signals that name and color are the practical fields for creation, which is useful given the enormous read-only body schema, but it never states that other body fields (id, events, canEdit, hexColor) are ignored, and the color list simply repeats the schema enum.

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 first sentence gives a specific verb and resource ("Create a new calendar"), and the TIP narrows it to a personal calendar, which is a real scope clarification. It does not distinguish itself from siblings such as list-calendars, update-calendar, or create-my-calendar-permission, and the phrase "for a user" is ambiguous since no user parameter exists.

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?

There is no guidance on when to use this versus update-calendar, list-calendars, or create-my-calendar-permission, nor any prerequisite advice such as checking for an existing calendar first. Usage is only implied by the verb.

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

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

Annotations already declare readOnly=false, destructive=true, and openWorld=true, so the safety profile is carried; the description still adds real behavioral knowledge beyond that — Graph resolves DST against start.timeZone so UTC drifts for recurring series, and online meetings plus recurrence are supported. It does not mention that attendees receive invitations or that a confirm gate may block the call, though the latter is documented in the schema.

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 purpose, then dense, non-redundant operational detail; nearly every sentence carries a real constraint. The emoji-tagged "CRITICAL" tip is slightly stylistically noisy and the two timezone sentences overlap somewhat, but the size is proportionate to a deeply nested schema.

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?

No output schema exists, but a create tool doesn't require return-value documentation. The description covers the genuinely hard part — time and timezone semantics in nested objects — yet omits two facts that matter for correct invocation: which calendar is targeted (assumed default) and whether saving sends invites to attendees.

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 75%, and the description meaningfully adds to it by spelling out the nested shape start:{dateTime,timeZone} / end:{dateTime,timeZone} and explicitly forbidding the flat startDateTime/startTimeZone form an agent would plausibly invent. It adds nothing about confirm, includeHeaders, or excludeResponse, but those are already described in the schema.

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 ("Create (schedule) a new calendar event — a meeting or appointment — on the user's calendar"), making the operation unmistakable. However, it never distinguishes itself from close siblings such as create-specific-calendar-event, create-calendar, or update-calendar-event, so an agent must infer which creation tool 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?

Gives actionable conditional guidance: UTC for one-off events, the organizer's zone name for recurring events, and points to get-mailbox-settings and list-supported-time-zones for obtaining a valid zone. The embedded tip also steers the agent to look up recipient addresses rather than guess. What is missing is tool-level routing — when to pick this versus create-specific-calendar-event or update-calendar-event.

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

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.

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the returned folder has its own id usable with update/delete/list/create-contact-in-folder, and ids are mailbox-unique regardless of nesting depth.

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?

Purpose is front-loaded in the first sentence and the TIP block delivers practical extras. There's mild redundancy between 'as a child of a specified folder' and 'Creates a sub-folder under an existing contact folder', but overall it's efficient.

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?

It covers what gets created, how to find the parent, and what the returned id enables downstream — enough to call correctly even without an output schema. It omits mention of the confirm gate that the schema exposes for destructive operations, a minor gap.

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?

With 80% schema coverage the baseline is 3, and the description adds a concrete body example ('Body: { displayName: Sub-folder name }') plus guidance to obtain the parent id via list-contact-folders. It doesn't address confirm/includeHeaders/excludeResponse, but those are documented in the schema.

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 a new contactFolder as a child of a specified folder' — and distinguishes it from sibling create-contact-folder (top-level) and create-contact-in-folder (contacts inside a folder) by emphasizing the child/sub-folder relationship.

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 names list-contact-folders as the discovery tool for the parent id and explains the default-folder alternative, giving an agent clear routing. It doesn't explicitly state when NOT to use this versus create-contact-folder, which keeps it short of a 5.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the description's remaining job is to explain the consequences of that flag. It does state the return value (the created contactFolder with its id) and the request body shape, but never mentions the confirm gate that the schema says guards destructive operations, nor permission requirements.

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 description restates the same fact three times: default contacts folder, mailbox root, and the TIP's opening line. The routing hint and body example earn their place; the repetition does not.

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?

No output schema exists, and the description does cover the return value, which is good. But for a tool flagged destructive with openWorldHint, the absence of any note about the confirmation gate or the contradiction between 'any specified contact folder' and the sibling pointer leaves material ambiguity.

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 75%, so a baseline of 3 applies, but the description goes beyond it by showing a concrete body payload ({ displayName: 'Family' }) and noting the returned id. It omits parentFolderId even while discussing child-folder creation, leaving a gap on the one parameter that would drive that path.

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 (create a contactFolder) and scopes the default case to the user's default contacts folder. The sibling create-contact-child-folder is named explicitly, so an agent can distinguish the two without reading either 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?

The TIP gives explicit routing: use create-contact-child-folder for sub-folders, and a concrete body example for the default case. However, the opening line also claims you can create a folder as a child of any specified folder, which muddies the rule the TIP just established.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered; the description adds real context beyond that: the contact is created inside an existing folder, the folder is not created here, and the folder id must come from list-contact-folders. It does not mention the confirm gate or error/response behavior, but those live in the schema, so this is strong without being exhaustive.

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, then a clearly marked TIP block containing the useful detail; no filler sentences. Slight redundancy between the first sentence and the TIP's restatement of 'creates a contact inside a specific folder', but the size is justified by the complexity of the nested body.

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 mutation tool with a deeply nested body and no output schema, the description covers the action, the folder-scoping semantics, the sibling alternative, and the folder-id source. What remains unsaid (confirm gate behavior, response shape, failure modes) is documented in the schema, so an agent has enough to call it 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 high (~80%), so the schema carries most parameter documentation, but the description adds a compact body shape summary (givenName, surname, displayName, emailAddresses as {address, name}, businessPhones, jobTitle, companyName) and clarifies how to source contactFolderId. Minor value-add beyond structured fields, though 'mobilePhone' in the tip is not a listed schema property.

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 ('Add a contact') plus a precise scope ('to the root Contacts folder or to the contacts endpoint of another contact folder'), and explicitly distinguishes itself from create-outlook-contact. An agent can tell exactly which contact-creation tool this is without reading the 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?

Gives an explicit when-to-use rule ('use this when organizing contacts into named folders'), names the alternative (create-outlook-contact POST /me/contacts) and its limitation (default folder only), and tells the agent where to obtain the required folder id (list-contact-folders). All routing decisions are resolved in the description.

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

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

The key behavioral fact — the message is persisted as a draft and not delivered — is stated, which is more than the annotations convey. With destructiveHint=true declared on what is effectively a create operation, the description does not explain the confirm gate, required scopes, or what happens to the created object; it only partially covers the mutation profile.

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 tight sentences, front-loaded with the action and destination, with the not-sent caveat placed where it matters. No redundant restatement of the title beyond the opening clause.

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 mutation tool with no output schema, an agent is left unsure what comes back (draft ID?) needed to later send it, and the confirm-gate behavior is only in the schema. Adequate but with a real gap around follow-up actions.

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 75%, so the schema already carries most field meaning. The description enumerates subject, body, toRecipients, ccRecipients and importance but omits bccRecipients, attachments, and the confirm/includeHeaders/excludeResponse controls, and adds no syntax or formatting guidance beyond the schema.

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 ('Create a draft Outlook email message') plus the destination ('signed-in user's Drafts folder'), which distinguishes it from the send-* siblings. It does not explicitly differentiate from create-reply-draft or create-forward-draft, though the 'set subject, body, recipients' framing implies a from-scratch draft.

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?

Explicitly says the draft is saved and not sent, and routes to 'send-mail' for direct sending versus sending the draft afterwards. Clear use context, but it never names the actual sibling tools (send-draft-message, create-reply-draft, create-forward-draft) an agent would have to choose between.

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

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

The annotations declare destructiveHint: true, but the description describes a benign 'create preview' operation with no mention of destructive side effects. This directly contradicts the annotation. The description gives the impression of a safe, non-destructive action, which is misleading given the annotation. This is a serious inconsistency.

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 description is concise, front-loads the core action, and uses a tip to provide key details. It includes body structure and return values in a compact format, with no redundant text. Excellent 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?

The description covers the main functional aspects, use case, and return values, but fails to disclose the destructive nature indicated by annotations. Without that disclosure, the agent may make an incorrect safety assessment. While the schema and output information are adequate, the destructiveHint contradiction makes the description incomplete for safe usage.

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 high (83%), but the description adds value by specifying the body fields (page, zoom, viewer) and explaining the return values (getUrl and postUrl). It also clarifies the purpose of the body. While it doesn't detail driveId/driveItemId, those are already described in the schema. The additional viewer option (not in schema properties) is useful.

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 clear verb and resource ('Create a drive item preview') and explains the purpose: generates a short-lived embeddable preview URL for files. It differentiates from sharing tools by emphasizing previews for inline use in emails/chats. This is specific and unambiguous.

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 provides a concrete use case ('surfacing inline previews in summary emails or chat messages') and notes the URLs are short-lived and embeddable. It does not explicitly exclude alternatives like share links, but the context makes the intended scenario clear. Sufficient guidance for most agents, though not exhaustive.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so it's a write operation. The description adds valuable behavioral context: idempotency (creates only if not exists, otherwise returns existing), inheritance of permissions from ancestors, and that it does NOT trigger OneDrive notifications. This goes beyond the annotations without contradicting them.

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 description is moderately long but well-structured with a tip and clear sections. It front-loads the core purpose and then provides usage context. Minor redundancy (e.g., 'driveItem driveItem' typo) and some tangential info (inheritance) slightly reduce conciseness, but overall it earns its length.

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?

The description covers the primary use case and return value, but introduces potential confusion: schema includes recipients and sendNotification fields (email-related), yet the description claims this tool does NOT send email. It does not explain why those fields exist or how they interact, leaving an agent uncertain about when to use them. Also lacks error handling or auth requirements, which could be important for a destructive operation.

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 high (83%), but the description adds a compact body template with enums for type and scope, plus optional fields (password, expirationDateTime, retainInheritedPermissions). It also clarifies the return value (permission with link.webUrl), which is not in the schema. This extra semantic value lifts it above the baseline.

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 clearly states the tool creates a share link for a driveItem, explains the createLink action, and describes idempotent behavior (returns existing link if type exists). It distinguishes itself from share-drive-item by contrasting link-only vs explicit access, so an agent can immediately identify which tool to use.

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?

Provides explicit when-to-use guidance: create a link WITHOUT sending an email invitation, and explicitly contrasts with share-drive-item for when explicit access is needed. The tip section gives a concrete body example and notes it returns a webUrl, making usage clear.

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

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

Annotations indicate destructiveHint: true and readOnlyHint: false, so the tool is known to mutate data. The description adds no behavioral context beyond that—it doesn't disclose that it modifies the workbook, that confirmation may be required, or any side effects. It does not contradict annotations, but it also doesn't add value over them.

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 description is extremely short—one sentence—which is concise in length but not in usefulness. It omits essential context, making it under-specified rather than efficiently concise. Important information about usage and parameters is missing entirely.

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?

This is a complex operation requiring a workbook driveItem, worksheet, and a body describing chart details. Without any explanation of these requirements, the description is completely inadequate. It doesn't mention that the operation is destructive, that confirmation might be gated, or what the expected inputs are. An agent cannot call this tool correctly based on the description alone.

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 86%, but the tool description adds nothing about parameters. The body parameter's subproperties (type, seriesBy, sourceData) are undocumented in both the schema and the tool description. With high schema coverage, the baseline is 3, but the description fails to explain what kind of data to pass, especially for the body object, which is critical for chart creation.

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 'Creates a new chart,' which identifies the verb and resource clearly. However, it provides no context about what kind of chart, where it is created, or how it relates to the Excel workbook. It does not distinguish itself from other Excel tools in the sibling list, though no other chart-creation tool exists.

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?

There is no guidance on when to use this tool versus alternatives. The description says nothing about the required workbook/worksheet context or that it modifies an existing Excel file. No exclusions or alternative tool recommendations are provided.

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

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

Annotations already indicate it's a non-read-only, destructive-capable operation. The description adds an error condition (invalid address or overlap) and clarifies the address-to-worksheet mapping. It doesn't mention side effects like confirm-gate behavior (handled by schema note) or what the response contains, but it does add meaningful behavioral detail 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?

The description is two focused sentences plus a succinct tip. The core action is front-loaded, the error behavior is summarized, and the example is placed as a separate tip. No wasted words – every sentence earns its place.

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?

Given the tool's complexity (7 params, nested body, no output schema) and the schema's high coverage (86%), the description covers the essential use case, error conditions, and prerequisite relationship. It doesn't explain return values (no output schema) but is otherwise sufficient for an agent to call it 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?

The schema lacks descriptions for the body's address and hasHeaders properties, but the description compensates with an explicit example ('Body: { address: 'A1:H171', hasHeaders: true }') and explains that the address determines the worksheet. This adds practical meaning beyond the schema's type-only definition.

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 a new table') and clarifies the relationship to the worksheet via the address. It clearly differentiates from sibling table operations (list/get/update/delete rows) by focusing on creation. The tip reinforces the purpose: converting a range into a formal Excel table.

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 explicitly states when this tool is required: before using add/update/delete-excel-table-rows on a plain-cells sheet. This gives clear context and a prerequisite. It doesn't mention when not to use it, but the specificity of the prerequisite is strong guidance.

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

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

Annotations already mark this as destructive (destructiveHint: true) and openWorldHint: true. The description adds behavioral context beyond that: it explains the upsert behavior ('If an override already exists for that SMTP address, POST updates the existing override's name and classifyAs') and clarifies that classifyAs must be 'focused' or 'other'. No contradiction with annotations, and the added context is valuable for correct invocation.

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 description is reasonably concise and front-loaded with the main purpose. It includes a practical tip and important constraints (e.g., do not invent addresses). While it's slightly longer than necessary, each part adds value and the structure (description followed by tip) aids readability.

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?

Given the nested body schema, the upsert behavior, and the need for address resolution, the description is complete. It covers the body format, permissible classifyAs values, behavior on existing overrides, and how to obtain a valid sender address. There is no output schema, but the description doesn't need to explain return values; the essential operational details are all present.

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?

The schema covers 75% of parameters, and the description enriches meaning by providing a concrete body example ({ classifyAs: 'focused', senderEmailAddress: { name: 'Display Name', address: 'sender@example.com' } }) and stating that classifyAs must be one of two values. It also emphasizes resolving the sender's address reliably, which is a key semantic point beyond the schema's field 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?

The description clearly states the tool's action: 'Create an override for a sender identified by an SMTP address' and the effect ('Future messages from that SMTP address will be consistently classified'). It is specific about the resource (Focused Inbox override) and distinguishes it implicitly from sibling tools like update-focused-inbox-override and delete-focused-inbox-override by describing the create/upsert behavior.

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 provides clear context on when to use this tool: it creates an override and, if one already exists, it updates it (useful for renaming a sender). It also advises resolving the sender's address using list-users or reading a mail header, and explicitly says 'do not invent SMTP addresses'. However, it does not explicitly contrast with the sibling update-focused-inbox-override, so it lacks a direct 'when not to use this' exclusion.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds the important behavioral note that the draft is not sent. However, it doesn't mention where the draft lands, that it is a mutation requiring an existing message, or the confirm-gate behavior covered in the schema.

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?

Very short and front-loaded, with the key 'does not send' constraint early. Slightly hurt by repeating 'Create a forward draft' verbatim between the first sentence and the tip.

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 nested, mutation-style tool with 5 params and no output schema, the description is adequate but thin: it covers purpose and non-sending behavior, while the how-to-invoke details live entirely in the rich schema. It says nothing about the returned draft or error conditions.

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 80%, so the schema already documents messageId, confirm, includeHeaders, and excludeResponse. The description adds no parameter-level detail, so the baseline 3 for high coverage applies.

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 ('Create a forward draft') and adds the crucial scope qualifier 'does not send,' which separates it from the sending sibling forward-mail-message without naming it. Clear but no explicit sibling differentiation by name.

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?

'Useful when user wants to review before sending' gives a concrete use case and implicitly contrasts with forward-mail-message/send-draft-message. No exclusion conditions or named alternatives, which keeps it at 4 rather than 5.

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

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

The description discloses that the tool returns an upload URL and that the caller must perform sequential PUT operations, stating 'This server does not perform the PUT.' It also mentions the error for smaller files. The annotations (readOnlyHint=false, destructiveHint=true) are not contradicted; the description supplements them with the workflow and error scenario.

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 description is lengthy but organized with a clear explanation, example, and tip. It front-loads the purpose and usage, though it could be more concise by trimming redundant references. The structure is logical but could be tightened.

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?

The description covers the entire workflow: when to use, what to include in the body, that it returns an upload URL, and that the caller performs PUTs. Given there's no output schema, it adequately explains the expected output and next steps. Some details like exact PUT range headers are not covered but are standard for this pattern.

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?

The schema already provides detailed parameter descriptions (80% coverage), and the description adds a concrete example for the body parameter, showing the structure with AttachmentItem fields. It also clarifies that messageId should be passed as 'messageId' not 'id', reinforcing the schema guidance.

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 clearly states the tool's function: create an upload session for attaching files to Outlook items (message or event). It explicitly distinguishes from the sibling 'add-mail-attachment' via the 3-150 MB size range, which is a specific verb+resource+scope definition.

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 explicitly states when to use this tool (file size between 3 MB and 150 MB) and when not to (use POST on attachments for smaller files). It also notes the caller must perform PUTs, providing clear context and exclusions. The TIP reinforces the alternative 'add-mail-attachment' for under 3 MB.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is carried by structured data. The description adds one genuine behavioral fact not in the annotations — isHidden can only be set at creation time — but says nothing about permissions, failure modes, or side effects of the mutation.

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 plus a labeled tip, all front-loaded with the core action first. Every sentence carries information; the emoji tip marker is the only decorative element.

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 mutation tool with a large nested body schema and no output schema, the description covers the parent-folder lookup and the hidden flag but omits that displayName is required and which body fields are meaningful versus read-only noise in the schema. An agent could construct an invalid body from the description alone.

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 schema does most of the work, but the description adds real meaning: it explains where the parent folder ID comes from (list-mail-folders / list-mail-child-folders) and warns that isHidden is create-only. It does not mention displayName, which is required to actually create the folder.

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 a new child mailFolder") and the tip restates it operationally as "Creates a subfolder inside an existing mail folder." It is distinguishable from list-mail-child-folders and update-mail-folder, though it never names the closely related create-mail-folder sibling to contrast top-level vs. child creation.

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 a clear prerequisite workflow: use list-mail-folders or list-mail-child-folders to obtain the parent folder ID before calling. It also flags the isHidden-at-creation rule. It does not state when to prefer this over create-mail-folder or what to do if the folder already exists.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true. The description adds useful creation context, especially that isHidden must be set at creation, but it does not explain the confirmation gate or other mutation-side behavioral details beyond what the schema and annotations provide.

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 description is front-loaded with the core action, then adds one important creation constraint and a sibling-routing tip. Every sentence contributes directly to selecting or invoking the tool correctly.

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 mutation tool with annotations and a rich nested schema, the description is largely complete: it identifies the scope, hidden-folder behavior, and sibling alternatives. Minor gaps remain around the confirm gate and the displayName field, but the schema documents those fields.

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 75%, so the schema carries most parameter meaning. The description reinforces the isHidden creation-time requirement but does not clarify the top-level body fields, such as displayName, or the confirm/includeHeaders/excludeResponse 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?

The description states a specific verb and resource: create a new mail folder. It also scopes the operation to the root of the user's mailbox and explicitly distinguishes it from create-mail-child-folder for subfolders.

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 explicit routing guidance: use create-mail-child-folder for subfolders and list-mail-folders to find existing folder IDs. It also states the condition for hidden folders, so an agent knows both when to use this tool and how it differs from alternatives.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is known; the description adds real behavioral context that the rule acts automatically on future incoming messages once enabled. It does not warn that destructive actions (delete, permanentDelete) apply without further prompting, nor mention the confirm gate beyond what the schema already documents.

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?

Purpose is front-loaded in the first sentence, followed by a compact TIP block with the folder-ID source, an example payload, and an action list. Nothing is wasted, though the action list partially duplicates schema content.

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 nested-object mutation with no output schema, the description supplies the payload shape and the source of mailFolderId, which are the pieces the schema alone makes tedious to infer. It leaves return-value behavior and the sheer breadth of available condition types to the schema, which is an acceptable division of labor.

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 field-level baseline is met by the schema; the description goes further with a complete example body showing the exact nesting of displayName, sequence, isEnabled, conditions, and actions. The action enumeration largely repeats schema descriptions, keeping it from a 5.

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 a messageRule object) plus the mechanism: conditions trigger actions on incoming Inbox mail. This clearly separates it from the sibling tools update-mail-rule, list-mail-rules, and delete-mail-rule without ambiguity.

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 concrete usage context: use the Inbox folder ID obtained from list-mail-folders when the intent is an inbox rule, which is exactly the prerequisite an agent would otherwise miss. It does not state when-not to use it (e.g., editing an existing rule via update-mail-rule), which keeps it below a 5.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'create' aligns with them. Beyond annotations, the description adds useful behavioral context: it shares the primary calendar, specifies the body structure, and notes the return value (id for subsequent operations). It doesn't disclose potential side effects like overriding existing permissions, but the given context is sufficient given the annotation coverage.

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 description is well-structured: a concise purpose sentence followed by a tip that includes an example and related guidance. The tip is informative but could be slightly trimmed (e.g., the example contains placeholder names and addresses that could be abbreviated). Still, every sentence carries useful information, and the main purpose is front-loaded.

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?

The description covers the essential aspects for an agent: what it does, the exact body structure, the role values, and the return value. It also provides a practical hint to resolve recipient SMTP via list-users. Minor gaps include no mention of side effects on existing permissions or the confirm parameter, but these are covered by schema and annotations. Overall, it's adequate for correct invocation.

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 75%, so the schema already documents most parameters. The description adds value with a concrete example body including emailAddress, role enum values, and other fields. It also clarifies the role options ('read' | 'write' | 'delegateWithoutPrivateEventAccess' | 'delegateWithPrivateEventAccess'). This goes beyond the schema's generic enum by showing a realistic payload.

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 clearly states the action ('create a calendarPermission resource'), the resource type, and the purpose (specify identity and role for sharing/delegating a calendar). The tip further clarifies it's the user's primary calendar, which distinguishes it from other calendar-related creation tools like 'create-calendar'. The verb and resource are specific and unambiguous.

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 provides a clear use case: 'Shares the user's primary calendar with another user (or sets up a delegate)'. It also gives a prerequisite ('Use list-users to resolve the recipient SMTP') and ties the returned id to update/delete operations, implying when to use this vs alternatives. However, it doesn't explicitly state when not to use it or mention alternatives like creating permissions for other calendars, which would make it fully explicit.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds genuinely new behavior: the @microsoft.graph.conflictBehavior options with 'rename' documented as the default, which tells the agent what happens on name collisions. It stops short of describing prerequisites (permissions) or what is overwritten when 'replace' is used.

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 compact sentences, front-loaded with the action, followed by a single tip block covering body shape and conflict handling. No repetition of the name or filler.

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 create tool with a very large nested body schema and no output schema, the description covers the essential minimum (body requirements, conflict behavior). Missing pieces — the confirm gate (documented in schema) and precondition/permission notes — are minor.

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 83%, so the baseline is 3, but the description earns more: it states that body must include name and folder ({}) — both of which the schema marks optional/nullable — and introduces conflictBehavior, a field absent from the schema properties entirely. It does not explain where conflictBehavior is placed or how driveItemId is discovered.

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 ('Create a OneDrive folder') and clarifies scope: a new folder inside the specified drive item. It implicitly distinguishes creation from siblings like move-rename-onedrive-item and upload-file-content, though it never names an alternative tool.

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?

Usage is only implied by the operation itself; there is no explicit when-to-use guidance or comparison with siblings such as move-rename-onedrive-item or upload-file-content. The tip explains how to call it, not when to choose it.

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

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

The uniqueness requirement ('name must be unique across the user's notebooks') is genuine behavioral context not derivable from the annotations or schema. However, annotations mark this destructiveHint=true and openWorldHint=true, and the description never mentions the confirm gate or that calls may fail with confirmation_required — that detail lives only in the schema. It also says nothing about what permissions or account context are needed.

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 sentence restates the first sentence almost verbatim ('Create a new OneNote notebook.' vs 'Creates a new OneNote notebook.'), which is wasted space. The remaining content (body shape, uniqueness) is front-loaded and useful.

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 destructive, open-world mutation with a 4-parameter schema containing a deeply nested body object and no output schema, the description leaves too much unsaid: what happens on duplicate names, whether the confirm gate applies, and what the response contains are not addressed. Only the one required field is hinted at out of a large writable surface.

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 75%, so the baseline is 3. The concrete body example ({ displayName: 'Notebook Name' }) is genuinely helpful because the body schema is a huge nested notebook object where almost every other field is marked read-only — but the description does not say that the read-only fields should be omitted or ignored, so it only partially compensates.

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 ('Create a new OneNote notebook'), which is unambiguous against siblings like create-onenote-section or create-onenote-page. It does not explicitly differentiate itself from those siblings, but the resource noun does that work adequately.

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?

No guidance on when to use this versus create-onenote-section or create-onenote-page, no prerequisites (e.g. must the user be signed in, does it require a notebook listing first), and no exclusions. The only usage-adjacent statement is the uniqueness constraint on the name.

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

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

The HTML tip is genuinely valuable behavioral context beyond the annotations: it warns that partial HTML or plain text 'fails silently or creates malformed pages,' which prevents a real failure mode. Against that, the annotations flag destructiveHint=true and openWorldHint=true, yet the description never mentions the confirm gate, permission/scope requirements, or what side effects a create has on the default notebook.

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 HTML tip is front-loaded and high value, but the middle paragraph is repetitive, restating the default-notebook restriction twice, and devotes two sentences to a parameter the tool cannot accept. Trimming the redundant Graph API prose would sharpen it considerably.

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 mutating, open-world tool with no output schema, the definition should cover the return shape (it returns the created page object, per the body schema) and the confirm gate. The critical body-format requirement is covered well, but the missing confirm/permission guidance and the phantom sectionName parameter leave the agent with an incomplete operational picture.

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?

The description spends most of its parameter discussion on a 'sectionName query parameter' that does not exist in the input schema, which will lead agents to pass an invalid argument. The actually required parameter, body, is only addressed by the HTML tip, and the schema-documented confirm/includeHeaders/excludeResponse flags are not mentioned.

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 a new OneNote page') and narrows the scope to the default section of the default notebook, which an agent can act on. It does not name the distinguishing sibling create-onenote-section-page for the non-default case, so the sibling boundary is left 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?

It explains that this endpoint only targets the current user's default notebook, which is a useful usage constraint. However, the alternative for other sections is described only as a 'sectionName query parameter' and a vague 'you can create pages in a specified section' line, with no named alternative tool despite create-onenote-section-page being available.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, and the description adds nothing beyond restating that a section is created. It does not mention the confirmation gate, permission requirements, or that the operation is irreversible, all of which matter for a tool flagged destructive.

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, front-loaded sentences with the action stated first and the body shape second; nothing is padded. The TIP sentence partly restates the first sentence, which is minor redundancy but still earns its place by giving the payload shape.

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?

Annotations and a rich schema cover the safety profile and parameters, and no output schema means return values need no explanation. For a destructive create operation, though, the description omits confirmation-gate behavior, prerequisites, and error conditions that an agent would need to call it safely.

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, and the tip 'Body: { displayName: \'Section Name\' }' genuinely helps because the body schema is a sprawling Graph object full of read-only fields. However, the description says nothing about notebookId, confirm, or excludeResponse, so it does not fully compensate for the remaining coverage 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 ('Create a new onenoteSection') plus the parent scope ('in the specified notebook'), which separates it from create-onenote-notebook and create-onenote-section-page. It stops short of naming those siblings or stating the containment relationship explicitly, so an agent must infer the hierarchy.

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 phrase 'in the specified notebook' implies a notebook must already exist and be identified, which is the only usage signal given. There is no guidance on how to obtain the notebookId (e.g., via list-onenote-notebooks) and no when-not-to-use or alternative tool named.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description's job is to add traits they can't express. It does exactly that with the highest-value disclosure here: partial HTML fails silently, which is a non-obvious failure mode no structured field conveys. Missing are permission requirements or what an empty/partial result leaves behind, so it is strong but not complete.

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 sentences: the operation first, then the one tip that prevents a silent failure. No restated name, no filler, and the critical constraint is impossible to miss.

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 destructive, open-world mutation with a nested body object and no output schema, the description should say what comes back (created page ID?) and what permissions or ID prerequisites exist. The HTML constraint is well covered, but sibling disambiguation and return/id-recovery information are absent.

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 80%, so the baseline is 3, and the description adds meaning beyond it: it constrains the `body` parameter to a full HTML document and warns that non-conforming input fails silently. The `onenoteSectionId` naming caveat is already handled in the schema, and confirm/includeHeaders/excludeResponse are not addressed in the description.

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 — 'Create a new page in the specified section' — so an agent knows exactly what is produced. However, the sibling set contains both `create-onenote-page` and `create-onenote-section-page`, and the description does nothing to distinguish them or explain which one addresses which ID shape.

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?

There is no explicit when-to-use guidance and no exclusions; the reader must infer from the name that the section ID must already exist. It never routes the agent to `list-onenote-notebook-sections` to obtain an ID, nor names `create-onenote-page` as the alternative sibling.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description does not carry the full safety burden. It adds behavioral context such as uniqueness and case sensitivity, which are beyond annotations. However, it does not explain side effects, permission requirements, or the result of creation, leaving gaps that annotations only partially cover.

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 description is fairly concise and front-loads the main action. The tip section repeats the action but also provides essential parameter details (color mapping, uniqueness) that are not redundant. There is minor redundancy between the first sentence and the tip, but overall it is efficient and well-structured with a clear format.

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?

The tool has a nested body schema, no output schema, and annotations already indicate it is a write operation. The description explains required parameters and constraints, but does not mention authentication prerequisites, potential confirmation requirements (though the schema documents the confirm parameter), or what the response contains. It is adequate but not exhaustive for an agent that might need to handle responses or understand side effects.

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?

The description adds meaning beyond the input schema by mapping color preset values to human-readable names and emphasizing displayName uniqueness and case sensitivity. With schema coverage at 75%, the description compensates for the undocumented 'color' parameter and enriches understanding of 'body' fields, which is valuable.

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 action (create) with a clear resource (outlookCategory object) and scope (user's master list of categories). It is not a tautology and clearly distinguishes from sibling tools like list-outlook-categories by its verb. The addition of uniqueness and case-sensitivity constraints further clarifies the object's semantics.

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 usage by stating it creates a category, but it does not explicitly mention when to use this tool versus alternatives, nor does it provide exclusions or preconditions. The note about case sensitivity is a usage detail, but there is no guidance on when to prefer this over other category-related tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so safety is largely covered. Beyond restating "add a contact," the description adds nothing about side effects, permission requirements, or the confirmation gate that the schema exposes via the confirm parameter. It is not contradictory, just thin.

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 no filler or repetition. It is efficient, though its brevity leaves the definition under-informative for a create operation with a deep payload.

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 mutation tool with a large nested contact payload, no output schema, and three sibling contact-creation/update tools, the description does not supply enough context: nothing about the return value, error behavior, or how it differs from create-contact-in-folder. It relies almost entirely on the schema and annotations.

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 75% and the large nested body object documents its fields well, so baseline 3 applies. The description says nothing about the confirm, includeHeaders, or excludeResponse parameters or about which body fields are required versus read-only.

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 ("Add a contact") plus the target location (root Contacts folder or another folder's contacts endpoint), so the action is unambiguous. However, it offers no differentiation from the closely related siblings create-contact-in-folder and create-contact-child-folder, which an agent could easily confuse with this one.

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 phrase "root Contacts folder or ... another contact folder" implies when this tool is appropriate versus folder-scoped variants, but only implicitly. There is no explicit when-to-use, no mention of the alternative siblings, and no prerequisites such as authentication state.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this is a mutating, externally visible operation. However, the description adds no behavioral context beyond 'create' — it does not explain what gets created, required plan association, whether the returned bucket is populated with tasks, or permissions needed.

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 single sentence is front-loaded and waste-free. It is appropriately terse for a name-like operation, though its brevity contributes to under-specification rather than genuine concision.

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 destructive, open-world mutation with a complex nested body, no output schema, and a required planId relationship, a one-sentence description leaves major gaps. The agent lacks context about the required body, plan association, side effects, and return behavior.

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 75%, with the nested body fields mostly documented, so the schema carries substantial semantic weight. The description itself adds no parameter meaning, not even identifying the required body or planId relationship, but it does not need to repeat every schema detail.

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 a new plannerBucket object.' An agent can identify the operation as creating a Planner bucket, though it does not differentiate this from sibling tools such as create-planner-plan or update-planner-bucket.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention that the bucket must be associated with a plan via planId. The agent is left to infer everything from the name and schema.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the agent knows it is a state-changing operation. The description adds crucial context: group membership requirement, container immutability, and that it returns the new plan id. It does not explain why destructiveHint is true, but does not contradict it.

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-loads the action, then a compact tip with body example and key constraints. No wasted sentences; each adds actionable detail.

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 nested create operation with no output schema, the description covers how to structure the body, auth prerequisite, immutability, and return value. It omits the confirm gate but the schema handles it.

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 75%, so most parameters are documented. The description adds a concrete body example showing the minimal required container.url and title, plus the team/group id mapping, which goes beyond schema. It does not cover confirm/includeHeaders/excludeResponse, but those have 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?

States a specific verb 'Create' and resource 'plannerPlan object', and the body example clarifies what a plan consists of. This distinguishes it from update-planner-plan and get-planner-plan.

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?

Gives clear preconditions: signed-in user must be a member of the group, and the container cannot be changed later. It mentions an alternative follow-up action (create-channel-tab) to show the plan in a channel, but does not explicitly compare with update-planner-plan.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is partly covered elsewhere. The description adds nothing about the confirm gate (even though a `confirm` parameter exists), what gets created, or side effects; for a mutation tool with nested payloads this is a real gap, though not a contradiction.

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?

One short sentence with no waste, but the brevity is under-specification rather than efficiency: there is no front-loaded detail an agent could act on beyond the name.

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?

Given a required nested `body` object with many read-only fields, no output schema, and a confirm-gate parameter, the description is far too thin to guide a correct call. It supplies none of the operational context the structured fields don't already state.

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 75%, below the high-coverage baseline, and the description names no parameters at all. It never mentions that `body` is required or that planId/title are the meaningful fields, leaving the agent to reverse-engineer the large nested payload itself.

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 sentence names a verb and resource ('Create a new plannerTask'), so the action is identifiable, but it does no more than restate the tool name/title. It gives no clue how it differs from create-planner-plan, create-planner-bucket, or create-todo-task in the sibling list.

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?

There is no guidance on when to use this versus update-planner-task or create-todo-task, and no mention of prerequisites such as needing an existing planId or a bucket that belongs to that plan. The agent must infer everything from the schema.

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

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

Annotations already indicate readOnlyHint false and destructiveHint true, so the burden on the description is reduced. The description explains the effect (posts a message teammates will see) and adds deployment constraints (beta, delegated accounts, global cloud). However, it does not mention that this is considered destructive or that confirmation might be required (the confirm parameter is only in the schema). It adds some context but not fully 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?

The description is dense but every sentence earns its place: purpose, modernization context, body structure example, and critical constraints (beta, environment, no ETag). It is front-loaded with the core action and uses a tip for guidance. No fluff or repetition.

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?

Given there is no output schema, the description covers the input structure, provides an example, and lists constraints. It doesn't explain the return value, but for a create operation that is often standard. It omits mention of the confirm parameter, but the schema describes it. Overall, the description is sufficient for an agent to call it correctly in most scenarios.

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 high (80%), but the description adds a concrete body example: { content: 'plain text or sanitized HTML', mentions?: [...] } and clarifies that mentions are optional. It also warns that plannerTaskId must be passed under that name, not as 'id'. This goes beyond the schema descriptions and provides practical usage guidance.

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 opens with 'Create a new plannerTaskChatMessage on a plannerTask' – a specific verb and resource. It further distinguishes this from the legacy conversationThreadId comment, clarifying exactly what object is being created. The name itself is unambiguous, and the description reinforces the purpose without ambiguity.

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 tip clearly states this is the modern 'task chat' versus the legacy comment thread, and notes that Microsoft is retiring classic comments, so this is the supported path. It also indicates the body structure and mentions. It doesn't explicitly name alternative tools like list-planner-task-messages or delete-planner-task-message, but the context implies when to use it (for posting) vs. those. The beta and environment constraints are also noted, which help an agent decide suitability.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds critical behavior beyond them: the comment/body mutual exclusion returning HTTP 400, that Message.body replaces and discards the quoted history, that signatures are only added client-side, and the RFC 2822 replyTo routing rule. This is exactly the extra context an agent needs before mutating a draft.

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?

Purpose is front-loaded, then organized into JSON/MIME bullet branches, with the TIP consolidating HTML and body-replacement caveats. It is slightly long and repeats the 400-on-both-fields rule twice, but every section carries actionable content.

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 mutation tool with nested params and no output schema, the description covers format choice, encoding, attachment/S-MIME handling, and body-replacement caveats. It omits required Graph scopes and the shape of the returned draft, minor gaps for a tool whose schema already documents confirm and response flags.

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 80% (baseline 3), and the description adds real meaning on top: the comment-vs-body exclusivity, base64 header/content requirements for MIME, and the replyTo recipient semantics. It stops short of explaining confirm/includeHeaders/excludeResponse, which are left to their 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?

States a specific verb and resource ('Create a draft to reply to the sender and all recipients of a message') that immediately distinguishes it from create-reply-draft (reply only) and reply-all-mail-message (single-action send). The draft-vs-send scope is explicit.

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?

Gives explicit when-to-use conditions plus the alternative path: 'Send the draft message in a subsequent operation. Alternatively, reply-all to a message in a single action.' It also spells out the JSON vs MIME decision points, so the agent knows which format branch and which sibling to route to.

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

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

The annotations declare this destructive and open-world, so the description goes beyond the minimum needed by adding rules that matter: it says that specifying both comment and Message.body returns HTTP 400, that supplying Message.body replaces the whole draft body and drops the quoted history, and that signatures are added by the Outlook client rather than by Graph. These are behavioral constraints an agent could not learn from the schema or 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?

The description is front-loaded with the core action and then uses parallel bullets for the two formats and a clearly marked tip. There is some redundancy, though: the comment-plus-body 400 error appears in the opening bullets and again in the tip, and the MIME paragraph mixes bulk fields with a how-to. That is slightly more text than a strict reading needs.

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?

Given a nested-object schema with 5 parameters, 80% description coverage, and no output schema, the description still covers what the agent needs: the two request shapes, the encoding requirements, the mutual-exclusion pitfall, reply routing, where the draft goes next ('send the draft message in a subsequent operation'), and the alternative single-call tool. No critical gap is left for a destructive, open-world write operation.

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, but the description still adds real meaning: the mutual exclusion of comment and body, how to set contentType html (with the warning that body replaces the quoted history), and the replyTo-vs-from RFC 2822 routing rule. The MIME/base64 guidance for the request body is also useful because the schema does not capture it. The description does not explain confirm, includeHeaders, or excludeResponse, so it falls short of 5.

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 opens with a specific verb and resource ('Create a draft to reply to the sender of a message') and immediately bounds scope with 'in either JSON or MIME format'. Combined with the 'reply to the sender' phrasing, it clearly differentiates itself from siblings like create-reply-all-draft and create-forward-draft, and the replyTo paragraph in the body reinforces that.

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 lays out two modes with concrete conditions for each: JSON when you want to set Comment or Message.body, MIME when you need headers, attachments, or S/MIME. It also points to the alternative single-operation path ('Alternatively, reply to a message in a single operation'), which maps to reply-mail-message. It never names the sibling tools explicitly, so an agent still has to infer the mapping from the natural-language pointer — hence 4, not 5.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is known. The description adds genuine behavioral context beyond that: DST is resolved against the organizer's zone, UTC is simplest for one-offs, and nested time objects are required. It omits the side effect that attendees will receive invitations, which is the main 'destructive' consequence, keeping it from a 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?

Front-loaded with the core action and required calendarId, then progressively more specific time-zone and recipient guidance. Every sentence carries information; the emoji-flagged TIP block is slightly awkward but its content (don't guess emails) is high-value. No filler.

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 mutation tool with no output schema and a very large nested body schema, the description covers the calling-critical concerns: target calendar, time format, time zone selection, and recipient lookup. It could mention invitation side effects or confirm-gate behavior, but the confirm parameter is already documented in the schema, so nothing essential is missing.

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, but the description earns extra: it clarifies calendarId usage, mandates nested {dateTime, timeZone} objects, and explicitly warns against startDateTime/startTimeZone — a real-world pitfall not obvious from the schema. That adds meaning beyond the documented fields.

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+resource+scope: 'Create a calendar event on a specific calendar.' The word 'specific' plus the calendarId requirement cleanly separates it from the sibling create-calendar-event (default calendar). An agent can tell which creation tool to pick without opening schemas.

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?

Gives concrete when-to guidance: UTC for one-off events, organizer's own time zone for recurring events, and points to get-mailbox-settings / list-supported-time-zones for the zone value. Also warns against guessing recipient emails and routes to list-users. It does not explicitly name create-calendar-event as the alternative for the primary calendar, so it falls just short of a full routing statement.

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