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?

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 indicate destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds significant behavioral detail: the 400 error on truncated base64, the size threshold, and the required @odata.type in the body. It does not contradict annotations and provides extra context about failure modes.

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 relatively concise but has a truncated sentence: 'An attachment can be one of the following types: All these types of attachment resources are derived from the attachment resource.' This is incomplete and adds noise. However, the key tip is well-structured and front-loaded, earning points for overall efficiency.

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 it's a mutation tool with destructiveHint and no output schema, the description covers the critical context: size limits, body format, and alternative tool. It doesn't describe return values, but that's not expected without an output schema. It is complete enough for an agent to execute correctly, with minor gaps like not explaining other parameters (confirm, includeHeaders).

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 goes beyond the schema by specifying that the body must include @odata.type with a concrete example. This is critical because the schema only lists generic fields like name and size, not the required structure. The description compensates for the schema's lack of required format, making the body parameter semantics clear.

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 'create a new Attachment' with a specific verb and resource. It distinguishes itself from the sibling create-mail-attachment-upload-session by explicitly stating it is for attachments under 3MB, making it unambiguous which tool to use for small attachments.

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 explicit usage criteria: 'The only path for attachments under 3MB' and instructs to use create-mail-attachment-upload-session for 3MB and above. It also warns about truncation failure with a specific error, providing clear when-to-use and when-not-to-use 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 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?

The description discloses that it creates a personal calendar and provides a body example and color list, but does not describe side effects, confirmation requirements (only in schema), or permission needs. The annotations (destructiveHint) are not contradicted, but the description adds little beyond 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 short and front-loaded, stating the main action first and a helpful tip with a body example. It is efficient with no fluff, though the informal 'TIP' style is slightly non-standard.

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 gives enough for basic use (name and color) but does not clarify the full scope of the body object, read-only restrictions, or the openWorldHint behavior. Given the complex schema, it leaves some ambiguity for advanced 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?

The schema already covers parameters extensively (75% coverage). The description adds a concrete body example and lists valid color values, but these are largely redundant with the schema's enum and descriptions, adding marginal value.

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' and the resource 'a new calendar', with a specific body example. It is unambiguous and distinct from sibling tools like create-calendar-event or list-calendars.

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 states the tool's purpose but does not provide guidance on when to use it vs alternatives, nor conditions or exclusions. It lacks context such as prerequisites, when to prefer other calendar tools, or when not to use this tool.

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/openWorldHint=true. The description adds non-obvious behavioral context: Graph resolves DST against start.timeZone so UTC drifts for recurring events, and the requirement to look up recipient addresses rather than guess. It still does not say that invites are dispatched to attendees or note the confirm gate (the latter only appears 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 the core action and payload shape, then layered guidance. Almost every sentence carries actionable detail; the '💡 TIP: CRITICAL:' double-marker is mild redundancy but the content itself is not wasteful.

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 complex nested payload, the description supplies the timezone semantics, payload shape, and attendee-address lookup that an agent needs to call it correctly. Remaining gaps (side effects like invite delivery, permission requirements) are notable but secondary.

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 75% schema coverage the baseline is 3, and the description goes beyond by explicitly warning against flat startDateTime/startTimeZone fields and giving a concrete zone example. It does not cover confirm/includeHeaders/excludeResponse, but adds meaningful shape guidance the schema alone doesn't emphasize.

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') and emphasizes nested object shape, distinguishing it from flat-field siblings like update-calendar-event. An agent can identify the operation and the required payload shape without opening 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?

Explicit guidance: use UTC for one-off events, the organizer's zone for recurring events, avoid guessing emails, validate zones with list-supported-time-zones or get-mailbox-settings. It names specific sibling helpers and the condition that routes to them.

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 contradicts the annotations: annotations mark destructiveHint=true, yet the description says 'Create' which is a non-destructive operation. No additional behavioral context is provided beyond what the annotations already state (readOnlyHint=false, destructiveHint=true). The description does not mention side effects, reversibility, or confirmation requirements, and the contradiction makes it misleading. Flagging as annotation 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?

The first sentence clearly states the purpose, followed by a tip with emoji that contains the body format, parent discovery, and return ID usage. It is moderately long but every sentence carries useful information. The tip could be more integrated, but the structure is front-loaded and 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?

For a nested-object schema with five parameters, the description covers the essential usage: how to format the body, how to obtain the parent ID, and how to use the returned folder's ID with other tools. It omits mention of the confirm gate (present in schema) but that is already documented in the parameter description. Overall, the agent has enough to invoke the 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 description adds valuable semantics beyond the schema: it gives an explicit body example '{ displayName: 'Sub-folder name' }' and tells the agent to use 'list-contact-folders' to discover the parent ID. This compensates for the schema's generic descriptions and provides practical guidance for the required parameters (body and contactFolderId).

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 explicitly states the verb 'Create' and the resource 'contactFolder' as a child of a specified folder or the user's default folder. It distinguishes itself from the sibling 'create-contact-folder' by emphasizing 'child' and 'sub-folder', making its scope unambiguous. The purpose is clear and specific.

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 usage instruction: 'Use list-contact-folders to discover the parent id.' It also covers two scenarios (under specified folder or default folder). However, it does not explicitly contrast with the root-folder creation tool 'create-contact-folder', relying on implication rather than stating when not to use this tool. This is a minor gap but the provided guidance is 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description adds little beyond that. It mentions the return value (created contactFolder with id), but it does not disclose side effects, permission requirements, or behavior related to the confirm parameter. Moreover, it introduces a potentially misleading capability (child creation) without clarifying the actual behavior, which is a transparency 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 only two sentences plus a tip, but the first sentence is redundant and confusing because it repeats a claim later contradicted by the tip. The tip is concise and useful, but the overall structure would benefit from removing the conflicting opening and stating the intended scope upfront.

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 provides the return value (created contactFolder with id) and a simple example, which is helpful given there is no output schema. However, it fails to clarify the exact creation scope (default vs. child) and does not explain other required parameters beyond displayName. The ambiguity about child folder creation leaves a significant gap in an agent's ability 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 75% description coverage and already documents most parameters, so the baseline is 3. The description adds a concrete body example ({ displayName: 'Family' }) which is helpful, but it does not explain how to specify a parent folder (e.g., via parentFolderId) and instead redirects that use case to a sibling. This adds some value but not comprehensive parameter 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?

States the verb and resource clearly ('create a new contactFolder'), but the scope is ambiguous: the first sentence claims it can create under the default folder or as a child of a specified folder, while the tip says to use create-contact-child-folder for sub-folder creation. This internal contradiction weakens the clarity of what the tool actually does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the sibling create-contact-child-folder for sub-folder creation, which is good guidance. However, the opening sentence contradicts this by implying this tool can also create child folders, so the when-to-use guidance is muddy. The tip partially clarifies, but the conflict reduces confidence.

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 adds context about behavior by specifying it creates contacts in specific folders and points out the need for a folder id. Annotations already indicate a write operation (readOnlyHint=false, destructiveHint=true), so the description complements them with scope. It does not mention confirmation gate or error handling, but those are covered in the schema's confirm parameter.

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, with the core purpose in the first sentence and a separate tip block for additional guidance. It is front-loaded with the primary action and uses a clear, scannable structure with an emoji. Minimal waste, though the tip could be slightly more compact.

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 is complex with nested body objects and response-handling parameters (includeHeaders, excludeResponse), yet the description does not mention what the response contains (e.g., the created contact object). It covers main usage but omits failure conditions and output details. The schema covers parameters, but the description could be more complete about the response.

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 gives an example body structure but largely duplicates the schema's detailed property descriptions. It adds the hint to use the 'id' field for contactFolderId, which is also in the schema. Given high schema coverage (80%), the description does not significantly enhance parameter understanding, so a baseline 3 is appropriate.

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: 'Add a contact to the root Contacts folder or to the contacts endpoint of another contact folder.' It also names the sibling create-outlook-contact and distinguishes this tool from it, making the purpose unmistakable.

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?

Explicit guidance is given on when to use this tool: 'The existing create-outlook-contact (POST /me/contacts) writes to the default folder only; use this when organizing contacts into named folders.' It also instructs to get the folder id via list-contact-folders, providing a complete usage path.

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 declare readOnlyHint=false, so the write nature is already known. The description adds genuine behavioral context beyond that: the draft is persisted to the Drafts folder and is NOT sent, which materially affects how an agent sequences this call. Given annotations already carry the safety profile, this is solid added value without contradicting anything.

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 tightly packed sentences: purpose and location first, then settable fields, then the critical save-vs-send disambiguation. No filler or redundancy; every sentence earns its place. Could perhaps front-load the 'not sent' clarification even earlier, but the structure is 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?

For a draft-creation tool with annotations covering the write/destructive profile, the description captures the essential behavior: it saves a draft, names the settable fields, and disambiguates from sending. Optional fields like attachments and bcc are absent but are documented in the schema body nested properties. The confirm-gate parameter is self-documented in the schema, so no gap there. An agent can call this correctly with the given information.

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% (moderately high), so the schema documents most parameters. The description names the key message fields (subject, body, toRecipients, ccRecipients, importance) which maps to nested schema properties and adds modest orientation for an agent. It does not add format or syntax details beyond the schema, so a 3 baseline is appropriate.

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 uses a specific verb+resource+scope: 'Create a draft Outlook email message in the signed-in user's Drafts folder.' It names the settable fields (subject, body, toRecipients, ccRecipients, importance) and explicitly contrasts itself with send-mail by stating the draft is saved, not sent. An agent can immediately tell what this tool does and how it differs from send-mail/send-draft-message.

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 clear when-to-use context: it states the draft is not sent and points to send-mail as the alternative for direct sending ('use send-mail to send a message directly, or send the draft afterwards'). However, among the large sibling set there are create-forward-draft, create-reply-draft, and create-reply-all-draft, which are not explicitly excluded; the phrase 'draft Outlook email message' only indirectly implies a fresh draft. Some exclusion guidance for those variants would push this to 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 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 declare readOnlyHint false, destructiveHint true, and openWorldHint true, which already inform the agent about mutation and flexibility. The description adds the valuable clarification 'does not send' — a behavioral guarantee beyond the annotations. It does not contradict any 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 brief but redundant: the first sentence and the tip both repeat 'Create a forward draft.' The tip could be merged into a single sentence without losing meaning. It is not poorly structured, but it wastes a little space with 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?

The schema provides detailed parameter descriptions, including the requirement for messageId. However, the description does not mention that a forward requires an original message or that the body field structures the forward content. For a tool with nested objects and 5 parameters, the description relies heavily on the schema, which is mostly sufficient but lacks high-level context about the 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 description coverage is 80%, so the schema already documents most parameters (messageId, confirm, etc.). The description adds no parameter-specific guidance. Per the rubric, with high schema coverage the baseline is 3, and there is no additional value here.

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 a specific action ('Create a forward draft') and immediately clarifies the critical distinction that it does not send. This differentiates it from siblings like send-mail, forward-mail-message, and create-reply-draft. The reader instantly knows what the tool does and why it 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?

Provides a clear usage context: 'Useful when user wants to review before sending.' This tells the agent when to prefer this tool over a direct send. It does not explicitly name alternatives, but the hint implies the alternative (sending immediately) and the condition is unambiguous.

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 convey that this is a write operation (readOnlyHint false, destructiveHint true). The description adds the important nuance that isHidden must be set at creation time if desired, which is behavioral guidance beyond the schema's mere statement of the property. It does not contradict annotations, and the confirm parameter is documented in the schema, so it doesn't need repetition.

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 concise sentences plus a tip, with the core purpose front-loaded. No redundant content, and the tip is directly actionable. It earns its place without bloat.

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 operation with a rich schema (5 params, 2 required, nested body), the description provides the essential context: what it does, how to get the parent ID, and the hidden-folder caveat. It does not describe the return value, but there is no output schema, so that is not required. The confirm parameter is covered in the schema, so the description is sufficient.

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 (80%), so the baseline is 3. The description's mention of isHidden and the tip about using list tools to find the parent ID largely mirror what is already in the schema for body.isHidden and mailFolderId. It reinforces but does not add new semantic detail 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?

The description clearly states the tool's purpose: 'create a new child mailFolder' and 'Creates a subfolder inside an existing mail folder.' This distinguishes it from sibling tool create-mail-folder (which likely handles top-level folders) and directly points to the list tools for locating the parent folder. The verb and resource are specific, and the scope 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 description gives a clear tip on how to find the parent folder ID using list-mail-folders or list-mail-child-folders, which is essential for correct invocation. However, it does not explicitly state when not to use this tool (e.g., for top-level folders) nor mention the alternative create-mail-folder. It implies the use case via 'child' and 'subfolder' but lacks explicit 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, indicating a write operation. The description adds valuable context beyond this: it specifies that folders are created at the root (top-level) and that isHidden can only be set at creation time. It does not mention side effects or error scenarios, but given the annotation coverage, a 4 is appropriate.

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 plus a concise tip line. The main purpose is front-loaded, the hidden-folder condition is immediately relevant, and the tip efficiently lists alternatives and prerequisites. No redundant words or unnecessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple create operation, the combination of description and schema provides enough information: the description states the operation and location, and the schema details all body properties (including displayName and isHidden). However, the description does not explicitly state that displayName is typically required (it's not marked required in the schema), nor does it mention potential error cases. Given that the agent can infer from the schema, but the omission of a required-field note is a gap, a 3 is appropriate.

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% (body lacks a direct description, while confirm, includeHeaders, and excludeResponse have descriptions). The description adds the isHidden nuance (that it must be set on creation), but it does not clarify which body properties are essential (e.g., displayName). The schema itself describes the subproperties, so the description provides some value but does not fully compensate for the missing body 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?

The description states a specific action ('create a new mail folder'), the resource ('mail folder'), and the location scope ('in the root folder of the user's mailbox'). It clearly distinguishes from the sibling 'create-mail-child-folder' by noting it creates only top-level folders, making the purpose 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 explicitly tells when to use this tool (for top-level folders) and provides alternatives: 'Use create-mail-child-folder to create a subfolder inside an existing folder' and 'Use list-mail-folders to find existing folder IDs.' It also gives a conditional instruction ('If you intend a new folder to be hidden, you must set the isHidden property to true on creation'). This is clear when/when-not 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 (destructiveHint=true, readOnlyHint=false) already establish this is a mutating operation, and the description does not contradict them. Beyond annotations, it enumerates the eight supported actions (moveToFolder, copyToFolder, forwardTo, forwardAsAttachmentTo, delete, markAsRead, markImportance, stopProcessingRules), giving the agent concrete knowledge of what the tool can do.

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 core purpose is front-loaded in the first sentence, followed by a compact tip and example. It is not verbose and every element (example, action list) earns its place, though the action list could arguably live in the 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?

For a tool with a deeply nested body object, the description covers the actions fully and gives a representative conditions example. It does not enumerate all possible conditions, but the schema already documents those, so the description adequately complements the structured data.

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 a baseline of 3 applies, but the description adds genuine value by providing a complete inline example payload (displayName, sequence, isEnabled, conditions.fromAddresses, actions.moveToFolder) that clarifies the nested structure beyond what the schema alone communicates.

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+resource ('Create a messageRule object') and explains the rule's behavior (Outlook carries out actions on inbox messages matching conditions). This clearly differentiates it from siblings like create-mail-folder, update-mail-rule, and list-mail-rules.

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 section gives actionable guidance: use the Inbox folder ID from list-mail-folders, and it shows a representative body payload. It doesn't explicitly state when not to use this tool or name update-mail-rule as the alternative for modifying existing rules, but it does point the agent to the correct folder-ID source.

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 readOnlyHint=false, signaling a write operation. The description adds value by disclosing the conflictBehavior options ('rename', 'replace', 'fail'), which reveals how name conflicts are handled—including the possibility of replacing an existing item. No contradiction with 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 sentences plus a tip, with no filler. The core action is front-loaded, and the tip delivers the most important parameter constraints and conflict behavior immediately.

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 creation tool with a large nested body schema and no output schema, the description covers the required body fields and conflict handling. It omits return value expectations and permission requirements, but annotations and schema provide sufficient baseline context for a competent agent.

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?

Even though schema coverage is high (83%), the description adds critical parameter semantics by specifying that the body must include name (string) and folder ({}) fields. It also introduces @microsoft.graph.conflictBehavior, which is not present in the schema, making this guidance 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 clearly states the action ('Create a OneDrive folder') and clarifies the target ('inside the specified drive item'). This distinguishes it from sibling operations like upload-file-content or delete-onedrive-file, which target files rather than folders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (when creating a folder in a drive), but it does not explicitly name alternatives, provide when-not-to-use guidance, or contrast with siblings like move-rename-onedrive-item. The context is clear but exclusions are absent.

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 cover the safety profile (readOnlyHint=false, destructiveHint=true) and the description's "create" claim is consistent with them — no contradiction. The description adds the uniqueness constraint and required body shape as useful behavioral context, but contributes little beyond the annotations beyond that.

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 purpose is front-loaded and the whole text is short, but the TIP line redundantly restates "Creates a new OneNote notebook" before delivering the body and uniqueness details. The redundancy costs it a higher score.

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 large nested schema and no output schema, the description is sufficient to invoke the tool correctly (creates a notebook with a displayName), but it omits response expectations, error behavior on name collision, and the confirm-gate semantics that appear 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 75%, so the schema already documents most parameters including body.displayName. The description adds a helpful shorthand (Body: { displayName: 'Notebook Name' }) that clarifies the single required field, but doesn't go beyond what the schema provides for the rest.

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?

"Create a new OneNote notebook" names a specific verb and resource, making it distinguishable from siblings like create-onenote-page and create-onenote-section. However, the TIP line repeats the same purpose verbatim rather than refining the scope, so it earns points for clarity but not full distinctiveness.

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 a practical usage note — the name must be unique across the user's notebooks — which helps the agent avoid a failed call. But it never routes to alternatives (e.g., create-onenote-section for working inside a notebook) nor states when not to use the tool, leaving selection to inference.

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 signal this is a write operation (readOnlyHint=false) and potentially destructive (destructiveHint=true). The description adds valuable behavioral detail by warning that the body must be a full HTML document and that partial HTML or plain text 'fails silently or creates malformed pages.' This goes beyond the annotations and is critical 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 somewhat wordy and repeats 'default notebook' multiple times, making it less concise than it could be. It does have a logical structure: main purpose, section targeting, notebook limitations, then a tip. But some sentences could be tightened without losing meaning.

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?

There is no output schema, so the description should explain what the response contains (e.g., page details, URLs). It does not. It also omits mention of the confirm parameter, which might be required given the destructiveHint annotation. For a complex operation with nested objects and a write/possible-destructive flag, the description is insufficiently 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?

Schema coverage is 75%, so most parameters are already described. The description adds meaningful context by detailing the sectionName query parameter (which is not present in the schema) and emphasizing that the body must be a full HTML document. However, the sectionName parameter isn't exposed in the schema, which could confuse agents about how to set it. The HTML tip is genuinely useful beyond the schema's 'content' field 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?

The description clearly states the action ('Create a new OneNote page') and the resource ('in the default section of the default notebook'). It also mentions the sectionName parameter and the limitation to the default notebook, which helps distinguish it from related tools. However, it does not explicitly contrast with the sibling 'create-onenote-section-page', leaving some ambiguity for an agent to choose between them.

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 explicit guidance on when to use this tool: only for the current user's default notebook, and how to target different sections via the sectionName parameter. It also hints that other notebooks require a different approach ('you can create pages in a specified section'). However, it does not name the alternative tool or enumerate when-not-to-use scenarios, so it's not fully comprehensive.

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 the description's 'Create' is consistent. It adds no extra behavioral context beyond the annotation—no mention of side effects, confirmation requirements, or error conditions. The body example is more about parameters than behavior, so the description adds minimal value beyond what annotations convey.

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 but redundant: the first sentence already states the purpose, and the tip repeats it ('Creates a new section in a notebook'). The body example is useful, but the tip adds no new information. The structure is acceptable but not tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple create operation with a standard destructive annotation and 80% schema coverage, the description covers the essential intent and parameters. It omits details like return value or confirmation behavior, but these are captured in the schema and annotations, so the description is adequately 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?

Schema coverage is 80%, so baseline is 3. The description adds a concrete example for the required body parameter (displayName) and implies the notebookId is required via 'specified notebook'. This helps the agent construct valid calls, going slightly beyond what the schema provides.

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 ('Create'), a specific resource ('onenoteSection'), and the scope ('in the specified notebook'). It clearly distinguishes from sibling tools like create-onenote-section-page and create-onenote-notebook. The added body example reinforces the action.

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 no guidance on when to use this tool vs. alternatives. It does not mention any conditions, exclusions, or relationship to sibling tools. With over 200 sibling tools, this is a significant omission.

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 the mutation aspect is known. The description adds a valuable behavioral detail: partial HTML fails silently, which is beyond what annotations provide. However, no other behavioral context (e.g., idempotency, rate limits) is disclosed.

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 with the primary purpose front-loaded and the critical tip as a secondary note. Efficient and well-structured, though the tip emoji is slightly informal but does not harm clarity.

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 most important caveat (full HTML requirement) and the purpose. Given the schema provides required parameters and confirm gate details, the description is minimally sufficient, but it does not explain the relationship between the body object schema and the HTML requirement, leaving ambiguity for a tool with nested object complexity.

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 describes the body parameter as an object with page properties, but the description's tip insists body must be a full HTML document—a critical but potentially contradictory clarification. This adds value beyond the schema's 80% coverage, yet the mismatch between schema type and description content may confuse agents.

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 'Create a new page in the specified section', identifying the verb, resource, and location. It distinguishes from sibling create-onenote-page by the section qualifier, though it does not explicitly name the alternative.

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 no guidance on when to use this tool versus sibling tools like create-onenote-page. The only usage hint is the HTML format tip, which addresses parameter formatting rather than tool selection.

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 indicate readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the bar is lowered. The description adds no extra behavioral context, such as whether creation overwrites existing contacts or requires specific permissions, but it doesn't contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. It's appropriately concise for stating the core action, though it sacrifices useful usage detail for brevity.

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 fails to explain how the tool targets a folder beyond root—there's no folder ID parameter in the schema—and doesn't clarify the distinction from create-contact-in-folder. This ambiguity means an agent may not know how to set the intended folder.

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 schema itself provides detailed field descriptions (e.g., displayName, emailAddresses). The tool description adds no parameter semantics, but given the coverage, this is adequate and doesn't require compensation.

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 ('Add a contact') and resource (contact), and specifies two target locations (root Contacts folder or another contact folder). It's clear but doesn't explicitly differentiate from sibling tools like create-contact-in-folder, so it falls short of a 5.

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 is given on when to use this tool versus create-contact-in-folder or how to select between the root folder and another folder. There's no mention of prerequisites or the confirm gate behavior.

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 carry readOnlyHint=false and destructiveHint=true, and the description adds no behavioral context of its own — it doesn't clarify the mutating effect, non-idempotency, or how creation interacts with the confirm gate documented in the schema. It neither contradicts the annotations nor supplements them with any disclosure.

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 a single short sentence with no wasted words, satisfying conciseness and front-loading. However, the brevity simply omits content rather than compressing useful information, making it under-specified rather than efficiently comprehensive.

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 destructive, complex create operation with a deeply nested body (tasks, assignments, checklist, dueDateTime) and no output schema, yet the description is one sentence. It omits the relationship to a plan, the confirmation requirement, and any guidance on constructing the body, leaving an agent under-equipped for a mutation with real 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?

Schema coverage is 75%, and the schema itself documents parameters well (name, planId, orderHint). But the description contributes zero parameter information and doesn't even note that planId is needed to place the bucket in a plan. What little the description adds is a restatement of the body object present in the schema, providing no value beyond 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 names a specific action (create) and resource (plannerBucket object), so the verb+resource is present and clear. However, it is essentially a restatement of the tool name and does nothing to distinguish create-planner-bucket from close siblings like create-planner-task, update-planner-bucket, or list-plan-buckets. It is clear but barely more informative than the title.

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 mention of when not to use it, and no prerequisites stated. The schema reveals that planId is required to associate the bucket with a plan, but the description never communicates this needed context, so an agent gets no help choosing or preparing a valid call.

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 provide readOnlyHint=false and destructiveHint=true, which already signal this is a mutating/write operation. The description 'Create a new plannerTask' is consistent with these annotations and adds no contradiction, but it also contributes nothing beyond the annotations—no mention of side effects, required context like plan/bucket existence, confirmation behavior, or return values. Given that annotations carry the safety profile, the bare minimum is met, but the description adds no behavioral 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?

The description is a single short sentence and is appropriately front-loaded. However, it is under-specified rather than economically concise—it conveys the bare minimum and could benefit from a qualifying phrase about what the tool actually does with the body payload. It scores a 3 for being adequately short but not adding useful 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?

This is a complex creation tool with a deeply nested body schema, yet the description gives no indication of what fields are necessary to create a valid task (e.g., that body is required, whether planId or bucketId is needed). With no output schema and no description-level guidance, an agent would have to infer all requirements from the JSON schema alone. For a write operation of this complexity, the description should do far more to orient the caller.

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%, placing it near the high-coverage baseline of 3. The schema itself is extremely rich—the body parameter contains detailed descriptions for priority (with the 0-10 interpretation), dueDateTime (ISO 8601 format), percentComplete, and various read-only flags. The description adds nothing about parameters beyond what the schema already documents, which is acceptable at this coverage level but not exemplary.

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+resource combination: 'Create a new plannerTask.' This does identify the action (creating a planner task) and differentiates it from siblings like list-planner-tasks or delete-planner-bucket. However, it's minimal—'plannerTask' is a slightly awkward compound term and the description adds nothing beyond the name itself, offering no detail about what a planner task is or what fields are involved.

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. Siblings include create-todo-task, create-planner-bucket, create-planner-task-message, and update-planner-task, but the description gives no context on how to choose among them. A tool as generic as 'Create a new plannerTask' would benefit from at least a note on prerequisites (e.g., a plan or bucket must exist first).

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?

The description adds valuable behavioral details beyond the annotations: specifying both comment and body returns a 400 error, supplying Message.body replaces the whole draft body (excluding quoted history), and signatures are added by Outlook client not via Graph. It also explains the MIME encoding requirement. These details complement the annotations (destructiveHint: true) without 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?

The description is somewhat long but well-organized: a clear opening statement, bullet points for JSON and MIME formats, and a tip at the end. It front-loads the core purpose and uses structure to separate concerns. Some redundancy exists (e.g., repeating the 400 error), but overall it is appropriately sized for the tool's 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?

Given the nested object schema and the absence of an output schema, the description covers the essential information an agent needs: format options, key constraints, recipient behavior, and the body replacement caveat. It does not detail MIME header specifics, but that is likely peripheral for draft creation. The description is sufficient for correct invocation 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 enhances understanding: it clarifies the relationship between Comment and Message.body, the constraint on specifying both, and the use of replyTo vs from recipients. It also explains the messageId parameter's expected format. This goes beyond the schema's bare property 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 specific action: 'Create a draft to reply to the sender and all recipients of a message.' It distinguishes this from related tools like create-reply-draft (which replies only to sender) and create-forward-draft, and mentions two formats (JSON/MIME). The verb and resource are explicit, and the scope (reply-all) 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 description provides substantial guidance: when to use JSON vs MIME, the constraint not to specify both comment and body, and the rule about using replyTo recipients per RFC 2822. It also mentions the alternative of doing a single-action reply-all. However, it does not explicitly name sibling tools like create-reply-draft for comparison, so the when-to-use distinction is implied rather than 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?

The description goes well beyond the annotations (readOnlyHint: false, destructiveHint: true) by detailing key behaviors: the 400 error when both comment and body are supplied, the note that supplying body replaces the entire draft body so quoted history is lost, the MIME base64 requirement, and that signatures are only added by the Outlook client, not via Graph. These are valuable, non-obvious details that help an agent predict behavior accurately.

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 relatively long but well-structured with bullet points and clear formatting. It leads with the primary purpose, then details each format, and provides a tip and note. Despite its length, every sentence conveys necessary information; it is appropriately detailed for a complex tool with two distinct input formats.

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 two complex input formats, nested schemas, and error-prone conditions, the description is extremely complete. It covers format selection, header requirements, attachments, error cases, update workflow, and the alternative single-operation reply. No output schema is needed, and the description leaves no obvious gaps 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?

While schema coverage is high (80%), the description adds meaningful semantics for the body parameter (explaining the Comment vs Message distinction and the error condition) and for messageId (instructing to pass it as 'messageId' not 'id'). It also clarifies that attachments and S/MIME properties go into the MIME content. This adds value beyond the schema's basic property 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 purpose: 'Create a draft to reply to the sender of a message in either JSON or MIME format.' It specifies the verb, resource, and formats, and distinguishes itself from siblings like create-forward-draft and create-reply-all-draft by its focus on replying to the sender only. The mention of 'Alternatively, reply to a message in a single operation' further clarifies 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 implies when to use this tool: when you want to create a draft rather than send immediately ('Send the draft message in a subsequent operation'), and it mentions the alternative of replying in a single operation. However, it does not explicitly name any sibling tools (e.g., create-reply-all-draft, reply-mail-message) or provide clear exclusions, so the guidance is implied but not 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 readOnlyHint=false, openWorldHint=true, and destructiveHint=true, so the mutation/side-effect profile is covered structurally. The description adds one genuine behavioral nuance (Graph resolves DST against the supplied zone), but does not disclose that attendees cause invitations/notifications to be sent, and the confirm gate behavior is only documented in the schema, not the description.

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 core action, then layers time-zone guidance and a recipient-lookup tip. Mostly efficient and free of padding, though the trailing TIP block is slightly disjointed from the time-zone paragraph.

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 complex nested schema, no output schema, and mutation semantics, the description covers the main gotchas an agent needs (nested time objects, time-zone selection, attendee email resolution). It is nearly complete, missing only a note that invites are dispatched 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 already 80%, yet the description adds value beyond it: it explains calendarId is the target calendar's ID, warns against the flat startDateTime/startTimeZone form in favor of nested {dateTime, timeZone} objects, and advises how to pick the time zone. This meaningfully clarifies the trickiest nested 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?

States a specific verb+resource ('Create a calendar event') and scopes it ('on a specific calendar'), and clarifies the required calendarId. This implicitly separates it from the sibling create-calendar-event, but it never names an alternative tool outright, so it stops short of full sibling differentiation.

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?

Offers real conditional guidance for time-zone choice (UTC for one-off events vs organizer's zone for recurring ones) and directs the agent to get-mailbox-settings/list-supported-time-zones and list-users for lookups. However, it gives no guidance on when to choose this tool over the closely related create-calendar-event variant, so usage is only implied rather than routed.

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 only provide hints (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description carries the disclosure burden. It adds valuable behavioral context: the notificationUrl must validate with token echo, expiration maximums vary by resource (1 hour for calls, 24h for messages, 3 days for mail), and enabling includeResourceData requires encryptionCertificate + encryptionCertificateId. The creation side-effect aligns with destructiveHint=true, so there is no contradiction. The description enriches rather than repeats the 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 first paragraph is verbose boilerplate copied from Microsoft docs, including hyperlinks an agent cannot follow ('see Set up notifications...'). The TIP block is dense but efficient, front-loading required fields before optional ones. There is redundancy — the body requirements are repeated in prose and again structured in the schema. It earns its structural clarity but could trim the doc-link prose.

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 operation (nested body object, 4 top-level parameters, no output schema), the description is fairly complete: it covers required body fields, optional rich-notification setup, and the permission precondition. Gaps are minor — it relies on non-clickable external references for details like lifecycleNotificationUrl behavior (Teams) and exact maximum lifetime tables, deferring that to the schema. Overall sufficient for an agent to form a valid request.

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%, borderline high, so the schema already documents most fields well. But the description adds genuine value beyond the schema: permission requirements tied to specific scopes, concrete resource path examples, and concrete expiration maximums that the schema only vaguely references as 'Subscription lifetime.' This helps the agent construct a valid body without external lookups.

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+resource statement: 'Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph.' This distinguishes it from the sibling set (update-subscription, delete-subscription, list-subscriptions, get-subscription) — this is the create operation. Nothing tautological; it clearly establishes the tool's function as registering a webhook for change notifications.

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 block gives strong when-to-use guidance: required body fields, concrete resource path examples ('/me/mailFolders/inbox/messages', '/users/{id}/events'), and a permission model ('No dedicated scope — caller must have a read permission for the target resource, e.g. Mail.Read, Calendars.Read'). It explains the validation requirement for notificationUrl. However, it never explicitly contrasts with the sibling subscription tools or states when NOT to use it — usage is implied rather than explicitly differentiated.

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, aligning with the description's 'Create' action, so there is no contradiction. However, the description doesn't disclose additional behavioral aspects beyond what the annotations already convey. It does add an example of the body structure, but that pertains to parameters rather than behavior. Since the annotation already indicates a destructive write, the description doesn't add significant behavioral context.

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 somewhat verbose and has redundancy. The main description and the tip share similar information (both explain linking a resource and provide body examples). It could be tightened without losing meaning. The core purpose is clear, but the extra example and tip repeat content, reducing conciseness.

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 operation with a required body and path parameters, the description provides enough context: it explains what the tool does, gives an example body, and clarifies the association scenario. The required parameters are documented in the schema, and the description doesn't overlook any critical usage detail. The lack of an output schema is typical for create operations, so no additional return-value explanation is needed.

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%, meaning most parameters are described in the schema. The description adds a concrete example of the body object with fields like webUrl, applicationName, displayName, and externalId, giving a template that helps an agent construct the body. This enriches the schema descriptions and helps clarify expected values, especially for the nested body parameter.

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 explicitly states the tool's purpose: 'Create a linkedResource object to associate a specified task with an item in a partner application.' It uses a specific verb (create), a specific resource (linkedResource), and clarifies the association intent. This clearly distinguishes it from siblings like list-todo-linked-resources and delete-todo-linked-resource.

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 contextual use cases, e.g., 'you can associate a task with an email item in Outlook that spurred the task,' and notes you can create a linkedResource during task creation. It also gives guidance on when to use it ('Use to link tasks to emails, files, or web pages for context'). It doesn't explicitly state when not to use it, but the siblings are obvious alternatives that are not relevant here.

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, readOnlyHint=false, and openWorldHint=true, covering the core safety profile. The description adds no contradictory statements and provides some useful context (e.g., the source of todoTaskListId and optional fields). However, it does not disclose any additional behavioral traits like confirmation requirements (though the confirm parameter is in the schema) or side effects beyond creation. Since the description does not contradict annotations and adds a small amount of context, a mid-range score is appropriate.

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 long, with the primary purpose stated first and the tip as a compact, useful addition. The '💡 TIP' is informal but efficient, and there is no unnecessary verbosity. It is appropriately front-loaded 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 tool with a complex nested body and a required list ID, the description provides a minimal body example, lists optional fields, and directs the agent to the sibling tool for the ID. It does not mention the confirm parameter or output structure, but annotations and schema cover those aspects. Given the richness of the schema, the description is sufficient for correct invocation, though it could briefly note the confirmation gate.

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%, which is high, so the baseline is 3. The description echoes some schema details (e.g., 'Body: { title: ... }' and optional fields) but does not add meaning beyond what the schema already provides. The only slight addition is highlighting the most relevant optional fields for a quick start, but it is largely redundant.

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 new task object') and the resource ('task object in a specified todoTaskList'). It also frames it as a Microsoft To Do operation, distinguishing it from sibling tools like list-todo-tasks or create-todo-task-list. The verb+resource combination 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 gives a clear prerequisite: 'Requires todoTaskListId from list-todo-task-lists', which tells the agent where to obtain the required ID. It also furnishes a body example and lists optional fields, giving practical usage context. It does not explicitly state when to avoid this tool (e.g., for updates/deletes), but the create nature is self-evident from the name and description.

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

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

The description discloses the response structure (returns id, displayName, isOwner, isShared, wellknownListName) and the built-in list limitation. It does not mention the confirm gate or error behavior, but the schema covers the confirm parameter. It adds value beyond the annotations (readOnlyHint=false, destructiveHint=true) 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 compact and efficiently packed. It front-loads the purpose, then provides a clarifying tip with an example and notes limitations. Every sentence adds value, with no unnecessary filler. The structure is clear 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 creation tool with no output schema, the description adequately covers purpose, minimal input example, response fields, a key limitation, and a usage pairing. It gives an agent enough to call the tool correctly without needing to inspect the full schema. The only omission is a mention of the confirm gate, but that is 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?

The description gives a concrete example body { displayName: 'My new list' }, clarifying that only displayName is typically needed, and explains what the returned object includes. This adds significant meaning beyond the schema's property descriptions, which are generic. It helps an agent understand what input is essential and what output to expect.

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 'Creates a new Microsoft To Do task list' and explains what a task list is (named buckets in the sidebar). It distinguishes from siblings like create-todo-task by clarifying it creates the list itself, not tasks within it. The description also specifies the resource and the action precisely.

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 explicit usage context: it tells the agent to pair with create-todo-task to populate the list, and it notes that built-in lists ('Tasks', 'Flagged emails') already exist and cannot be re-created, which is a key prerequisite. This effectively directs the agent to when to use this tool and when not 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?

Annotations already indicate a non-read-only, potentially destructive operation. The description adds crucial behavioral context: it returns a pre-authenticated uploadUrl and the server does not perform the PUT, meaning the caller is responsible for the actual upload. This goes beyond the annotations and is essential 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 concise and front-loaded with the core purpose. The tip and path example are brief and directly useful, with no wasted words. Although it could be trimmed, every sentence adds necessary operational 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?

Given the complexity of a two-step upload process and no output schema, the description adequately explains the return value (uploadUrl) and the caller's responsibility to PUT. It also covers the path for new files and optional body. It could mention potential errors or required headers for the PUT, but the core usage is clear.

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 83% schema description coverage, most parameters are already documented in the schema. The description adds value by showing an example body with conflictBehavior and explicitly stating the body is optional. This aids in constructing correct parameters without repeating 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 starts with a clear verb and resource: 'Create an upload session.' It also differentiates from the Outlook attachment session by noting it is for large files with no size limit and no minimum, making it distinct from the sibling tool. The path example further specifies usage for new files.

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 contrasts with the Outlook attachment session ('unlike the Outlook attachment session'), providing a scoping condition. It also gives a concrete path for new files and notes the caller must PUT bytes, which is critical usage guidance. However, it does not explicitly state when not to use this tool beyond implying the alternative for smaller files.

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 the description's job is to add context. It does by stating that 'The event remains in the calendar as declined unless the user deletes it,' which clarifies the persistence behavior. It also mentions the tip with an example body, conveying sendResponse and comment semantics, though it stops short of describing all recovery options or side effects.

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 short paragraphs, with the core action front-loaded and a separate tip that offers a concrete example. It avoids unnecessary fluff but does repeat 'Declines a meeting invitation' in the tip, which is minor redundancy. The structure is clear and scannable for an agent.

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 (5 params, nested objects) and no output schema, the description covers the essential usage: what it does, how to propose a new time, and the persistence behavior. It lacks an explicit statement about the response format, but that is not critical because the schema does not define one. It also points to further documentation for proposals. Overall, enough context 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?

Schema coverage is 80%, so most parameters have descriptions. The description adds value by explicitly mentioning the proposedNewTime parameter and providing a concrete example body ('sendResponse: true, comment: ...'), which clarifies how to use the body object. It also reinforces the eventId usage, but the schema already explains that. Overall it augments the schema without redundancy.

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: 'Decline invitation to the specified event in a user calendar.' It uses a specific verb and resource, making the purpose unambiguous. It also distinguishes itself from sibling operations like accept or cancel by focusing on declining, and the proposedNewTime option adds nuance.

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 the tool is used when the user wants to decline a meeting invitation, and it explains the optional proposedNewTime scenario. However, it does not explicitly contrast it with alternatives such as accept-calendar-event, tentatively-accept, or cancel, leaving the choice to inference. There is no clear 'when not to use' 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?

Beyond the annotations (destructiveHint=true), the description adds critical behavioral details: it deletes all events in the calendar, the default calendar is protected, and the action is irreversible. This gives the agent a complete picture of side effects and consequences, going beyond what structured metadata provides.

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?

Extremely concise: a single sentence stating the action and constraint, followed by a brief tip with two key consequences. No filler, and the most important information is front-loaded. Every word 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?

For a destructive tool, the description covers the essential: what it does, the cascade effect, the default calendar restriction, and irreversibility. It does not explicitly mention the confirmation gate or response behavior, but those are already covered in the schema and annotations. Given the moderate complexity and high annotation coverage, this is quite 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 input schema fully documents all parameters (calendarId, confirm, If-Match, etc.) with descriptions, so the baseline is 3. The description does not add parameter-specific semantics beyond hinting that calendarId must refer to a non-default calendar. Since schema coverage is 100%, the description does not need to compensate, and it adds minimal extra value here.

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 (delete), the resource (calendar), and a key constraint (other than the default calendar). It also mentions that it deletes all events, which adds specificity and distinguishes it from other calendar-related tools like update-calendar or delete-calendar-event.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.