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

Annotations flag a non-read-only, open-world operation but say nothing about the external email side effect. The description adds that invitations are emailed to attendees through Outlook, which is exactly the kind of consequence an agent must warn the user about. The confirm-after-approval safety gate is a useful restatement, though it partially duplicates the schema's own confirm 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?

Three short sentences, zero waste, and the most important behavioral fact (invitations get emailed when attendees exist) is front-loaded right after the purpose. Every sentence carries information an agent needs.

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

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

For a 14-parameter creation tool, the description covers the essential decision (attendees → confirm required) and an output schema exists so return values need no explanation. It is adequately complete, though it says nothing about defaults for account_id/calendar_id or idempotency behavior implied by idempotentHint=false.

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 100%, with all 14 parameters including enums and nested attendee fields documented in the schema itself. The description's only parameter-related content is the attendees/confirm dependency, which the schema already encodes. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Add an event to your calendar.' An agent immediately knows this creates a calendar entry, and the create-vs-update distinction against calendar_update_event follows from the verb. However, no sibling tool is named, so the differentiation is implicit rather than stated.

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

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

It gives clear conditional context: with attendees, an Outlook invitation is emailed and confirm=true becomes required; without attendees, it is a private appointment needing no confirmation. That is real workflow guidance. It stops short of stating when to prefer calendar_update_event or calendar_find_availability, so there is no explicit alternative routing.

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=true, idempotentHint=true and destructiveHint=false, so the safe-read profile is covered. The description adds genuinely useful behavioral context beyond that: it only sees the caller's own calendar in personal accounts, and slot suggestions are constrained to working hours. It does not mention the 62-day range cap or return shape, but the output schema covers results.

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 well-formed sentence with the core action (show busy time, suggest free slots) front-loaded, followed by the scoping caveat. No waste, though it is dense enough that it could be split for 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?

With rich annotations, a full output schema, and 100% schema coverage, the description only needs to add what structured fields cannot: the personal-account visibility limit and the working-hours assumption. It does that, so an agent has enough to call it correctly, though the range cap is left to 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 description coverage is 100%, so all eight parameters are already documented in the schema, establishing the baseline of 3. The description adds only limited extra meaning, mainly re-explaining slot_minutes and the working-hours constraint, which the schema already conveys.

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: it shows busy time in your own calendar and suggests free slots of a given length. The scope note ("this covers your calendar only") clarifies what it queries, though it never names a sibling tool like calendar_create_event to route against.

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

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

Usage is implied rather than stated: an agent can infer it should call this before scheduling a meeting, and the personal-account limitation tells it not to expect others' availability. There is no explicit when-to-use/when-not guidance or named alternative 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 the safety profile (readOnly=false, destructive=false, non-idempotent, openWorld). The description's added behavioral context is the confirm-after-approval gate, but that same instruction is already spelled out in the confirm parameter description, so it repeats structured data. It adds little about side effects, e.g. that forwarding sends an external email that cannot be recalled.

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

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

Two short sentences, purpose front-loaded and the confirm requirement second. Every sentence carries information and there is no redundancy or filler.

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

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

With a full output schema and 100% parameter coverage, the description does not need to explain returns or field formats. It adequately covers purpose and the approval gate, but omits the external side effect of forwarding to recipients, which is only hinted at by the openWorld annotation.

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 100%, so the schema fully documents all five parameters. The description only loosely references 'people the user names' and 'optional note,' which map to 'to' and 'comment' without adding format, limits, or syntax beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Forward a meeting invitation to people the user names, with an optional note.' This is clear and actionable, but it never distinguishes itself from the sibling email_forward or other calendar tools; the calendar-vs-email distinction is left to the reader.

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 one usage constraint ('Requires confirm=true after the user approves'), which is a meaningful prerequisite. However, it offers no when-to-use/when-not guidance relative to alternatives like email_forward or calendar_respond, so selection guidance is only implied.

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 declare the generic profile (not read-only, not idempotent, open-world, non-destructive). The description adds genuinely useful behavioral detail beyond that: the response is emailed to the organiser by default, and that external side effect is gated behind confirm=true. It stops short of noting reversibility or that a sent email cannot be recalled.

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 dense, front-loaded sentences that carry the action set, the proposed-time restriction, and the confirm gate with no filler 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?

For a mutation tool with an output schema available, the description covers the essentials an agent needs to act correctly, especially the subtle confirm requirement for the default email path. Return values needn't be described since the output schema exists.

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 100%, so the schema already documents all 8 parameters including action enum, confirm, send_response, and the tentative/decline-only constraint on proposed times. The description largely restates these constraints rather than adding new semantics, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific set of verbs (accept, tentatively accept, decline) against a specific resource (a meeting invitation), plus the optional proposed-time variation. This is clearly distinguishable in spirit from calendar_create_event/calendar_update_event, though no sibling is named to make the boundary explicit.

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

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

Guidance is embedded and actionable: proposing a new time is only valid with tentative or decline, and confirm=true is required when the response is emailed (the default). It gives clear conditions for use but never explicitly contrasts with competing siblings like calendar_update_event.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=true), and the description adds a side effect the annotations cannot express: attendee notification emails, gated by confirm=true. That is exactly the extra context the annotations omit. It still does not state permission requirements or atomicity if a partial change fails.

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, zero filler, and the mutation surface is front-loaded before the confirm-gate caveat. Nothing here is repeated boilerplate.

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?

An output schema exists, so explaining return values is unnecessary, and the description correctly spends its words on the confirm/notification behavior an agent must know before calling. It is nearly complete, missing only failure-mode context (e.g. what happens if confirm is false while attendees exist).

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 100%, with every field (start/end RFC 3339 format, time_zone IANA name, attendees_add/set/remove, reminder_minutes bounds) documented inline. The description only restates the field families at a high level and adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (change) and resource (event) and enumerates the mutable field families: time, title, location, description, reminder, attendees. This clearly distinguishes it from the sibling calendar_create_event without needing to open either schema.

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

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

Gives an explicit conditional rule: if the event has attendees (or you add some), Outlook emails them and confirm=true is required. That is genuine when-to-do-what guidance. It stops short of routing the agent away from alternatives (e.g. calendar_respond for RSVPs), but no misleading or missing context.

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 and destructiveHint=false but say nothing about synchronicity, so the description's disclosure that the copy runs in the background and returns an operation_id is genuinely additive. It still omits whether copying overwrites an existing name or what permissions are required, and does not reinforce the non-idempotent 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?

Two tight sentences with zero filler; the core action is front-loaded and the async follow-up is placed immediately after it.

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?

Because an output schema exists, the return values need no elaboration, and the description usefully clarifies that the immediate result is an operation_id rather than a finished copy. It stops short of noting the destination_id/destination_path trade-off, but that gap is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all five parameters including the item_id/new_name/destination_id/destination_path distinctions are already documented. The description adds only the high-level notion of a destination folder, which the schema covers in more detail — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb (Copy) plus resource (OneDrive file or folder) and target (another folder), so the agent can distinguish it from generic siblings like m365_update or drive_upload. It does not explicitly contrast with the nearest sibling m365_move, which handles relocation rather than duplication.

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 tells the agent what to do after invoking (poll m365_get with resource='operation'), which is useful staging guidance, but it never states when to choose copy over move or upload. Usage is implied by the tool name rather than stated.

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 cover the safety profile (not readOnly, not idempotent, not destructive, openWorld), so the bar is lower. The description adds genuinely useful behavior: that a view/edit link is usable by anyone who holds it, and that confirm=true is mandatory and must follow user approval — an approval-gate workflow the annotations do not 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?

Three tight sentences with the core purpose and modes front-loaded, then the mandatory confirm gate, then the return shape. Nothing is padded and no sentence restates the title.

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 12 parameters fully documented in the schema and an output schema present, the description need not explain return values, and it correctly avoids that. It covers purpose, mode choice, and the approval gate; the only minor gap is that it doesn't flag the OneDrive-root exclusion noted in the item_id schema or account scoping, though the schema handles those.

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 100%, so every one of the 12 parameters, including enums for mode, role, and link_type, is already documented in the schema. The description restates mode and confirm but adds no syntax or format detail beyond the structured fields, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb (share) and resource (OneDrive file or folder) and distinguishes the two operating modes, link vs invite, telling the agent exactly what capability this tool exposes. It is clearly separable from siblings like drive_copy, drive_upload, and m365_update.

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 states the mode selection rule ('by link' vs 'by inviting named people') and the mandatory confirm=true step after user approval, which is real when-to-use guidance. It does not, however, say when to prefer this over sibling tools such as m365_update for permissions, nor any explicit negative conditions.

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, idempotentHint=false, and destructiveHint=false. Beyond that, the description adds real context: reads occur from the local disk, only within allowed folders, hidden/secret files are refused, and the OneDrive item is returned. It doesn't cover permissions or rate limits, but it meaningfully augments the annotation profile.

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

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

Three tight sentences, front-loaded with the core action and mode split, then the disk-access constraint, then the return value. No filler; every clause carries information.

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 an output schema present, the description needn't detail return values, though it helpfully notes one is returned. For a non-idempotent write tool with seven parameters, it covers the local-path restrictions and mode selection well, but omits any note on auth/account scoping or what a replace-mode failure looks like.

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 100%, so the baseline is 3, but the description adds semantic grouping the schema lacks: it ties parent_id/parent_path to the 'new file' mode and item_id to the 'replace contents' mode, clarifying mutual exclusivity that the flat schema does not express.

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 (upload) and resource (a local file to OneDrive), and explicitly separates the two operating modes via the parameters that select them (parent_id/parent_path for new files vs item_id for replacement). An agent can distinguish this from drive_copy or drive_share without opening a schema.

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

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

The description clearly routes the agent to the correct mode by naming the parameters for each (new file vs replace). It does not, however, mention when not to use it or point to an alternative sibling (e.g., drive_copy for server-side copies), leaving some usage inference to the agent.

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 and destructiveHint=false, so the write-but-non-destructive profile is partly covered. The description adds real value beyond them: 'Sends nothing' clarifies no mail is dispatched, and 'Returns the draft ID' signals the response shape. It stops short of noting the draft is idempotent-or-not or attachment/auth constraints.

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

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

Three short, front-loaded sentences with zero filler. Each sentence carries distinct information: purpose, non-sending behavior, and the follow-up send path.

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 9 params fully documented in schema and an output schema present, the description does not need to explain fields or return values. It covers purpose, the send-nothing guarantee, and the handoff to email_send, which is sufficient for correct invocation; only minor edge contexts (account_id omission, attachment path rules) are left to 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 description coverage is 100% across all 9 parameters, so the schema already documents to/cc/bcc/body/subject/account_id/importance/attachments/body_format fully. The description adds no parameter-level detail beyond that, so the 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?

States a specific verb+resource ('Create an unsent email draft') and immediately clarifies it sends nothing, distinguishing it from email_send. An agent can tell it apart from email_send and email_reply without opening any schema.

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

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

Names the alternative and the follow-up path explicitly ('then send later with email_send(mode="draft")'), which tells the agent this is the compose-and-review step. It gives clear use context but does not spell out when not to use it (e.g. sending directly).

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

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

Annotations declare destructiveHint=true, but the description adds critical nuance they do not carry: the deletion is irreversible ('Deleted messages cannot be restored with these tools'), subfolders survive the operation, and the action is chunked ('up to max_messages per call'), meaning a single call may not fully empty a large folder. These are exactly the traits that change how an agent sequences the call.

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

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

Three sentences, zero filler, front-loaded with the action and scope, followed by the destructive caveats. Every clause carries distinct information.

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 an output schema present, return values need not be described. The description covers the safety profile, the confirm workflow, the batching limit, and the irreversibility, which is everything an agent needs before invoking a destructive bulk 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 100%, so the baseline is 3, but the description adds interpretation: 'up to max_messages per call' signals the parameter is a batch cap rather than a total, and the confirm sentence explains the approval gating the schema only states mechanically.

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 ('Delete all messages in one mail folder') with illustrative scope ('such as Junk Email or Deleted Items') and a key boundary ('Subfolders are kept'). An agent can distinguish this folder-level bulk purge from single-message deletion siblings 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?

Provides an operational precondition ('Requires confirm=true after the user approves') that implies a human-in-the-loop approval flow, which is useful routing context. However, it never contrasts this tool with the message-level delete path or states when emptying a folder is preferable to deleting individual messages.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely useful behavioral context beyond them: the per-call cap of max_messages, the need to loop while remaining_unread > 0, and the routing hint to m365_update for single messages. It does not spell out permission requirements, but the operational loop semantics are the key disclosure an agent needs here.

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

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

Three short sentences, front-loaded with the core action and scope, followed by the iteration rule and the sibling routing. No filler or redundant restatement of the name.

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

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

With an output schema present, return values (including remaining_unread) need not be explained, and the description references the field that drives the loop. Together with the annotations covering mutation safety and idempotency, an agent has everything needed to invoke and re-invoke 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 100%, so folder_id, account_id, and max_messages are all fully documented in the schema. The description only echoes max_messages' role as a per-call cap without adding format or constraint detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (mark as read), resource (every unread message in one mail folder), and scope (bulk, folder-wide) in the first clause. It also explicitly distinguishes itself from m365_update for single-message operations, so an agent can differentiate without opening either schema.

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

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

Gives a clear iteration rule ('If remaining_unread is above zero, call again') and names the alternative for single-message edits (m365_update). It lacks explicit when-not-to-use guidance for the tool as a whole (e.g., preferring search-based filtering), but the batching contract is well communicated.

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 the write/non-idempotent/open-world profile, and the description adds genuinely non-structured behavior: an approval gate via confirm=true and an explicit prohibition on inferring recipients. Those are safety-relevant traits not derivable from the schema or annotations. It does not describe delivery outcome or 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?

Three short sentences, each carrying a distinct constraint (action, approval gate, recipient-source prohibition). The core action is front-loaded with no filler.

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

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

An output schema exists, so return values need no explanation. For an 8-parameter mutation tool, the description covers the action, the confirmation workflow, and the key safety constraint. An agent has everything needed 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?

Schema description coverage is 100%, so every parameter (cc, bcc, comment, email_id, account_id, attachments) is already documented. The description only reinforces the confirm semantics, which the schema also states, so it adds little beyond 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?

Specific verb (Forward) plus resource (an email) plus the qualifying detail that recipients are user-named and the note is optional. This cleanly separates it from email_send and email_reply, which an agent can distinguish without opening any schema.

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

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

Gives real usage conditions: confirm=true is required and only after user approval, and recipients must never be inferred from other context. That is a clear when-to-use and a hard when-not rule. It stops short of naming the sibling alternatives (email_send/email_reply) for the non-forward cases.

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, idempotentHint=false, openWorldHint=true, so the mutation profile is covered. The description adds genuinely new behavior beyond the schema: the confirm-after-user-approval gate and the return of the joined conversation, both of which affect how the agent sequences the call.

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

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

Three short sentences, front-loaded with the action and mode split, then the approval prerequisite, then the return. Every clause carries information and nothing is padded.

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 an output schema present, return values need not be explained, and annotations cover the safety profile; the description adds the approval gate that the schema alone only implies. Complete enough for correct invocation, though it omits any note about attachment limits or account selection that a caller might want surfaced.

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 100%, so every parameter including mode, confirm, and attachments is already documented in the schema. The description restates mode and confirm semantics without adding syntax, limits, or resolution behavior beyond what the schema provides; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (reply) and resource (an email), and splits the scope into the two mode values, so an agent can distinguish it from email_send or email_forward. It stops short of naming those siblings as alternatives, so differentiation is implicit rather than explicit.

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

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

Gives the condition that selects each mode ('sender' vs 'all') and a hard usage gate: 'Requires confirm=true after the user approves the reply.' It does not contrast this tool with email_forward or email_send, so the agent gets clear context but no explicit exclusions.

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 it is not read-only, not idempotent, open-world, and not destructive; the description adds real behavioral context by disclosing that destructive-effect rules act silently on future mail and therefore require confirm=true, plus that the rule is returned. It doesn't spell out the consequence of confirm=false (rejection vs. silent drop) or auth/permission requirements, so it stops short of a 5.

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

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

Three sentences, zero filler. The capability statement comes first, the safety gate second, and sibling routing last — well front-loaded and each 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?

For a 8-parameter nested mutation tool with an output schema already documenting return values, the description covers all four action modes, the confirm safety requirement, and delegation to sibling tools for read/delete. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameter docs already exist; the description still adds rationale the schema lacks, explaining why confirm is required (silent future-mail action) and that the call returns the rule. It does not, however, clarify action/parameter pairings (e.g., rule_id required for set_enabled/reorder), which the schema only partially implies.

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 and enumerates the four concrete modes (create, change, enable/disable, reorder), so the agent knows exactly which operations this tool covers. It also implicitly separates itself from read/delete siblings by naming them in the next sentence.

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 routing is given: read rules with m365_list or m365_get, delete with m365_delete. It also states a conditional gate ('Rules that forward, redirect or delete mail require confirm=true'), which is exactly the when/when-not guidance an agent needs before invoking.

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 the safety profile (readOnly=false, idempotent=false, openWorld=true), so the bar is lower, and the description still adds the critical non-annotation fact: 'Cannot be undone.' That, plus the confirmation gate, is meaningful behavioral context. It stops short of permission/account requirements or delivery failure behavior.

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

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

Three short sentences, no filler, with the action and mode split front-loaded and the irreversible/confinement constraints placed after. Every sentence carries a distinct rule.

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?

An output schema exists, so return values need not be explained, and the schema itself carries parameter detail. The description covers the irreversibility, the confirmation precondition, and recipient strictness, which are the highest-risk facts for this tool; deeper detail (account scoping, attachment limits) lives 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 description coverage is 100%, so the schema already documents all 13 parameters including mode, confirm, and draft_id. The description restates mode semantics and the confirm gate, adding only marginal framing ('a draft you created earlier') beyond what the schema says.

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 (send) and resource (email) and immediately splits the behavior into the two supported modes, mode='new' vs mode='draft'. This distinguishes it from sibling email_create_draft (which only stages) and from email_reply/email_forward.

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

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

Gives a hard precondition (confirm=true only after the user approves recipients and content) and an explicit prohibition ('Never infer recipients'), which is exactly the kind of when-to-use guidance an agent needs. It does not explicitly name the alternative tools (create_draft, reply, forward) for cases where sending is premature.

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 disclose the safety profile (not read-only, not idempotent, not destructive, open-world), so the description only needs to add context. It adds that the call returns the created item and that a matching sub-object is required, but says nothing about duplicate-name handling (the schema-level 'if_exists' default of 'fail' is significant for creation) or what happens on partial failure.

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

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

Three short sentences: capability first, the key structural rule second, exclusions third. No filler, no restatement of the title, and the highest-value routing information 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?

For a 7-parameter polymorphic creator with nested objects and an output schema, the description covers capability, dispatch rule, exclusions and return shape adequately. The only gap is behavioral detail on idempotency and name collisions, which the annotations and schema partially cover.

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 100% and each nested object is already labelled 'Required when resource=...', so the schema fully documents the polymorphic contract. The description's 'Supply the sub-object that matches resource' restates that relationship at a high level without adding format, default, or edge-case detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb ('Create') and enumerates the exact resource types it handles (mail folder, calendar, contact, contact folder, OneDrive folder), then explicitly routes four excluded operations to named siblings. An agent can distinguish this from email_create_draft, calendar_create_event and drive_upload without reading any schema.

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

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

Explicit when-not guidance is given for four adjacent operations, each paired with the sibling that should be used instead. It also gives the positive selection rule: supply the sub-object that matches 'resource'.

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, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: meeting deletions trigger attendee cancellations, OneDrive items go to the recycle bin, and the result reports recoverability. It stops short of noting auth/permission requirements or scope limits.

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

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

Three tight sentences, front-loaded with the resource scope, then the confirm requirement, then the side effects. Every sentence carries distinct information with no padding.

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 multi-resource tool with full schema coverage, an output schema, and complete annotations, the description supplies the missing human-facing context (confirm precondition, cancellation side effect, recycle-bin behavior). Only auth/permission expectations are absent, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including confirm, id, and cancellation_message is already documented. The description restates the confirm gate and implies the recoverability outcome but adds no new parameter-level syntax or format detail, making the baseline 3 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?

States a specific verb (Delete) plus an explicit enumeration of the eight supported resource types, so the agent knows exactly what scope of items this applies to. It is clearly distinguishable from sibling mutation tools like m365_update or m365_move.

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

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

Gives a clear precondition ('Always requires confirm=true after the user approves') that governs invocation, and the resource enum tells the agent which target types are valid. It does not name alternatives or explicitly state when not to use it (e.g., prefer move/archive instead of delete), 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral precondition (requires an ID you already have) and cross-tool dependency (resource='operation' reflects a drive_copy job), which the structured fields do not 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?

Three sentences, zero padding, front-loaded with the core requirement (needs an ID). Each sentence routes to a different sibling or states a precondition, so every clause 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?

An output schema exists, so return-value detail is unnecessary, and the description plus 100%-covered schema plus safety annotations give an agent everything needed to select and 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?

Schema description coverage is 100%, so id/path/refresh/include_body/body_max_chars are all documented in the schema. The description only adds the mapping of resource='operation' to a drive_copy operation, a marginal gain over the enum schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Read one item') and enumerates the concrete resource types it covers (email with body, event with attendees, contact, folders, inbox rule, calendar, OneDrive item, copy operation status). This lets an agent distinguish it from m365_list, m365_search, and m365_get_content without opening a 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?

Explicitly names the alternatives and the condition for each: use m365_list/m365_search to find IDs, use m365_get_content to download files or attachments, and use this tool only when the ID is already known. No inference 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 mark readOnlyHint=false with destructiveHint=false, and the description explains why: it writes to the local disk, but only inside allowed folders, and that hidden/secret files are refused. It does not restate the write nature so much as bound it, which is genuinely additive. Overwrite semantics and the temp-link lifetime are left to the schema/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?

Three clauses and a routing sentence, with the core distinction (content vs. details) front-loaded and the mode breakdown following. No filler or repetition of the title.

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?

An output schema exists, so return format is covered elsewhere. The description supplies the write-location constraint, the mode map, and the sibling routing needed to call it correctly; nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented in the schema, including the mode enum's resource restrictions and the save_path folder constraint. The description reinforces the mode-to-resource mapping but adds no format or edge-case detail beyond it. Baseline 3 for full schema coverage.

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 concrete verb (get content), the resource classes (OneDrive file, email attachment, contact), and explicitly contrasts itself with the sibling m365_get ('Get the content of an item rather than its details'). An agent can distinguish it from m365_get without opening either schema.

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

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

Enumerates each mode and the resource it applies to ('mode=download', 'mode=download_url', 'mode=vcard'), and names the alternative tool plus the condition that selects it ('Use m365_get for item details'). Selection criteria are explicit rather than inferred.

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=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it returns 'compact items plus next_cursor for more', disclosing pagination and payload shape. It does not discuss caching semantics (left to the refresh param) or per-account behavior, but the added context is real.

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 sentences, front-loaded with the capability and scope, then routing, then return shape. No filler, no repetition of schema content.

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

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

For a 14-parameter listing tool with a rich schema and an output schema, the description covers selection, alternatives and pagination adequately; return values are delegated to the output schema as permitted. Minor gap: nothing about multi-account behavior (account_id) or cache staleness, though both are documented in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across 14 parameters, so the schema already documents resource enum values, filters, date windows, recursion and cursor reuse. The description only names the resource families and the tree option, adding no syntax or format detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource set: 'Browse items of one type in a known place', then enumerates the concrete resource types (emails in a mail folder, events in a time window, calendars, contacts, folders, rules, OneDrive files). It also names the two siblings it is not (m365_search, m365_get), so an agent can distinguish it without opening schemas.

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

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

Gives an explicit selection condition ('Use this when you know where to look') and routes the agent to alternatives: m365_search for text lookup, m365_get when an ID is already known. Both when-to-use and when-not-to-use are covered.

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 non-readOnly, non-idempotent, non-destructive, openWorld. The description adds a genuinely useful behavioral fact not in the structured data: moved emails and contacts receive a NEW id that is returned and must be used for later calls. That identity-change side effect is exactly the kind of context an agent needs after a mutation.

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

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

Three tight sentences, front-loaded with the action and accepted resources, followed by the per-resource behavior and the id-change consequence. Zero filler.

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

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

With annotations carrying the safety profile and an output schema present, the description needn't explain return values, yet it helpfully flags the returned new id. Coverage is strong; only the absence of usage routing against siblings leaves a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and every parameter (id, new_name, resource, account_id, destination_id, destination_path) is already documented in the schema. The description's per-resource destination nuance ('archive' archives) adds only marginal value beyond that 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?

States a specific verb ('Move') and enumerates the exact resource types it accepts (email, mail folder, contact, OneDrive item), matching the schema enum. It stops short of distinguishing itself from the sibling m365_update, which an agent might otherwise confuse for relocating items.

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 implied usage guidance by explaining what happens per resource type (email to 'archive' archives it, a contact goes into a contact folder), but never states when to choose this over m365_update or drive_copy, nor any prerequisites such as required permissions.

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=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds return ordering ('newest first') and pagination info ('next_cursor'), which are useful behavioral details beyond the annotations. It does not mention rate limits or auth requirements, so not a 5.

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

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

Three tightly written sentences, front-loaded with purpose and followed immediately by routing exclusions and return behavior. Every sentence carries distinct, useful information.

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 rich annotations, 100% schema description coverage, and an output schema, the description covers everything an agent needs to select and invoke the tool correctly: purpose, alternatives, and the return shape including pagination. No critical gaps remain for the agent's decision.

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 100% and the schema documents all eight parameters with descriptions, defaults, and constraints. The description only implicitly references query and resources ('by free text', 'one type or several at once'), adding little beyond what the schema already provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Find') and enumerates the resource types (emails, events, contacts, OneDrive files), with the key qualifier 'by free text'. It explicitly distinguishes itself from siblings m365_list and m365_get, so an agent can route correctly 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?

Provides an explicit when-to-use condition ('when you do not know where they are') and two when-not-to-use conditions with named alternatives: 'Do not use it to browse a folder (m365_list) or open a known ID (m365_get).' This is about as clear as usage guidance gets.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds some context (the *_changes object must match the resource) but says nothing about permissions, how categories_add/remove/set interact, or partial-update semantics beyond what the schema states.

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?

Dense but front-loaded: the capability list, then the invocation rule, then the exclusions, then the return summary. Every clause carries distinct information.

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?

Covers the resource types, mutation surface, invocation pattern and sibling boundaries, which is enough to call it correctly. Minor gaps remain on authorization needs and field-conflict behavior, and the return-value sentence is largely redundant given an output schema exists.

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 100%, so the schema already documents every parameter including the per-resource conditional requirements. The description's contribution ('Supply the *_changes object that matches resource') only restates the resource-to-object linkage already encoded in the schema's 'Required when resource=...' descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Change properties) plus the resource set (email, mail folder, contact, OneDrive item) and enumerates the concrete mutations available (read/unread, flag, importance, categories, Focused/Other, rename, contact details). It also distinguishes itself from siblings by naming what it does NOT cover.

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

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

Gives explicit when-not rules with named alternatives: not for events (calendar_update_event), inbox rules (email_rule_manage), or file contents (drive_upload). It also tells the caller how to invoke it: supply the *_changes object matching the resource.

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