Outlook Assistant

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the admin delegation prerequisite, the server opt-in OUTLOOK_SHARED_MAILBOX (work/school only), and the graceful degradation when it is absent (folder must be well-known name or ID).

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: purpose first, then return shape, then folder semantics, then prerequisites and the opt-in caveat. Every sentence carries information, though the description is long enough that a couple of clauses 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?

No output schema exists, yet the description specifies the return shape (id/subject/from/receivedDateTime/preview, same as search-emails list mode) plus pagination via count. Combined with auth prerequisites and opt-in behavior, nothing an agent needs 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 coverage is 100%, so baseline is 3, but the description adds real meaning: the accepted forms of `folder` (well-known, custom/localized, nested path, raw folderId), folderId precedence over folder, count default/max, and the OUTLOOK_SHARED_MAILBOX constraint on custom names. It largely mirrors rather than extends the schema on a few fields, keeping it at 4.

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

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

Opens with a specific verb+resource and scope: 'List emails or folders in a shared mailbox the signed-in user can access (read-only).' It also names the sibling it is not (search-emails for search/filters), so an agent can distinguish it 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?

Explicitly routes the agent: 'For search and filters over a shared mailbox, use search-emails with sharedMailbox set,' and explains when to use listFolders ('to find custom subfolders before reading them'). It also states the prerequisite that the mailbox must be delegated in Exchange (admin-configured).

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 (not read-only, idempotent, non-destructive), so the bar is lower. The description adds real context beyond them: categories must pre-exist in the mailbox's master list, shared mailbox use requires Mail.ReadWrite.Shared + delegate access and the OUTLOOK_SHARED_MAILBOX opt-in, and it confirms per-message return output. Loses a point for not clarifying error/partial-failure behavior on batch operations.

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 well-organized; the core purpose leads, followed by action semantics, then prerequisites. Each sentence carries information, though the category-creation prerequisites (manage-category before shared mailbox caveats) are slightly repetitive and 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?

For a 6-param mutation tool with no output schema, the description covers action semantics, batch vs single, prerequisites, permissions, and return format. It is nearly complete, with only edge-case behavior (e.g., what happens on invalid category names) left unspecified.

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. The description goes beyond the schema by explaining that `categories` are matched by display name and must already exist in the target mailbox, that `sharedMailbox`/`email` are aliases, and that batch yields one request per message — meaningful semantics not captured in the enum/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?

Opens with a specific verb and resource ('Tag or untag email messages with master categories') and immediately scopes it to the master list created via `manage-category`, cleanly separating it from that sibling. An agent can tell this applies categories to messages rather than managing the category list itself.

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 distinguishes the three `action` modes (set replaces, add appends, remove removes only named), explains single vs batch via `messageId`/`messageIds`, and states when to use `sharedMailbox`/`email`. It also routes the agent to `manage-category` for creating categories and warns that it won't work for shared mailboxes.

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?

With annotations already declaring openWorldHint and destructiveHint=false, the description still adds real behavioral context: list is read-only, download writes a file under a new unique name with path restrictions and auto-creation, and attachment IDs are message-scoped and fail under /me without sharedMailbox. It does not, however, disclose rate limits or failure behavior for download when a name collides beyond the 'unique name' note.

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 well organized, front-loading the action semantics and routing constraints before parenthetical defaults. It is longer than average because it covers three actions, and the 'Use outputVerbosity' sentence references a parameter absent from the schema, which slightly muddies an otherwise tight structure.

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

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

With no output schema, the description compensates by naming the list fields returned (id, name, contentType, size, isInline) and the download return value (saved file path), plus the inline-content behavior for view. Everything needed to invoke each action correctly is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter dependency semantics the schema does not: messageId required for all actions, attachmentId required only for view/download, and sharedMailbox/email needing to mirror the mailbox the messageId came from. It also names outputVerbosity, which is not present in the input schema at all.

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 ('Inspect or retrieve email attachments') and then enumerates the three distinct operations the single tool supports, each with its own return shape. An agent can distinguish list vs view vs download 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?

It states the default (action=`list`), explains that binary types cannot be viewed and must be downloaded, and gives the exact condition to use the sharedMailbox parameter ('if messageId came from a shared/delegated mailbox'). Alternatives and when-not conditions are 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 only say readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description goes well beyond by disclosing token persistence to ~/.outlook-assistant-tokens.json, survival across restarts, the ~90-day refresh-token window, the local auth server port, and the interactive code+URL handoff. It also clarifies the sequence needed to finish device-code sign-in. (Note: the openWorldHint=false annotation sits awkwardly with the described Microsoft Graph sign-in flow, but the description itself is consistent with the mutation/idempotency hints.)

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?

It is long but organized action-by-action and front-loaded with the purpose plus the most important routing instruction ('call it first'). Most sentences carry unique operational detail, though the density is high enough that an agent must parse a multi-clause paragraph rather than scan.

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 correctly carries the return-value burden: status returns auth state, about returns version/audience/scopes/diagnostics, authenticate returns a code plus URL. Failure handling (client ID not configured) and setup prerequisites (npm run auth-server) are also covered, leaving no obvious gap for a four-action auth tool.

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 real meaning the schema does not: the default action is status, device-code is the default method, force re-authenticates 'over an existing valid session', and clientId is persisted to ~/.outlook-assistant-config.json with OUTLOOK_CLIENT_ID taking precedence. It also explains the device-code-complete sequencing, which the schema leaves as a bare enum 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 states a specific verb and resource ('Manage authentication with the Microsoft Graph API') and enumerates every action (status, authenticate, device-code-complete, about) with what each returns or initiates. An agent can distinguish this from all 21 email/calendar/contact siblings at a glance, since none of them handle credentials or sessions.

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

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

It gives explicit routing: 'call it first to check before other tools' for action=status, device-code vs browser selection ('works headlessly' vs 'run npm run auth-server first'), when to use force:true, and when to ask the user for a client ID. It also names the fallback condition (OUTLOOK_CLIENT_ID not configured) that triggers the clientId parameter.

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?

Goes well beyond the annotations (readOnly=false, destructive=true): discloses that attendees receive invitations on save, the OUTLOOK_ALLOWED_RECIPIENTS gating, timezone resolution rules, session-limit enforcement, and that 0 refuses every create. This is exactly the destructive/side-effect context an agent needs.

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

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

Front-loaded with purpose and return value in the first sentence, then progressively adds side effects, alternatives, and limits. It is long and somewhat parenthetical, but nearly every clause carries decision-relevant information, so little is wasted.

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

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

No output schema exists, yet the description names the returned fields (id, webLink, conditional online-meeting URL), covers the destructive side effects, the safe dryRun path, and the limit/timezone configuration. Completeness is high for a 6-parameter mutating tool.

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 baseline is 3, but the description adds real value the schema lacks: how timezone interacts with the start/end ISO strings ('omit the Z suffix to send local time') and the semantics of dryRun's preview output. It does not restate subject/body beyond what the schema already documents.

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

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

States a specific verb and resource ('Create a new calendar event on the signed-in user's default calendar'), names the return payload, and implicitly contrasts with siblings like manage-event and list-events. An agent can distinguish this from every sibling 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 routes to alternatives: use manage-event action=update to modify, action=cancel/delete to remove. It also prescribes the dryRun:true preview workflow before committing, and warns that dryRun avoids wasting the session create limit.

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?

Goes well beyond the annotations: delete moves to Recoverable Items (restorable for a limited time), send counts against the send-email session limit with 0 refusing all sends, update/send/delete refuse non-draft ids, and reply/forward drafts are deleted if a recipient is outside the allowlist. This is exactly the kind of consequence detail annotations cannot carry.

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 lifecycle and destructive scope in the first clause, then walks actions compactly. Dense and information-rich with little waste, though the long allowlist sentence is somewhat sprawling and 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?

For an 11-parameter, 7-action tool with no output schema, the description covers action semantics, id requirements, dry-run/mail-tips flags, allowlist enforcement, and even return shape (draft vs status). Nothing needed to invoke 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 coverage is 100%, so baseline is 3, but the description adds real meaning: dryRun previews only on create and is refused elsewhere, checkRecipients runs mail-tips first, comment cannot combine with body, and the recipient allowlist scope across actions. Minor overlap with schema text but net additive.

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 resource (draft lifecycle) and enumerates all seven actions with their individual effects, so the agent knows exactly what the tool does. It clearly separates itself from siblings like send-email and update-email by framing the tool as draft-centric with send/delete as lifecycle endpoints.

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 per-action conditions: create for new drafts, update for patching by id, send/delete require an unsent draft id, reply/reply-all/forward build from a message id. It does not explicitly route the agent to sibling send-email/update-email when no draft exists, so the boundary with those tools is implied 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 declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, and the description adds substantial context beyond them: files are only written inside temp/~/Downloads/~/Documents/OUTLOOK_EXPORT_DIR, dot-prefixed names and symlinks/hardlinks are never replaced, directories are created if missing, batch caps at 100, and sharedMailbox requires delegate access plus OUTLOOK_SHARED_MAILBOX opt-in or the call is refused.

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 dense paragraph, but it is front-loaded with the default target and each clause is scoped by `target=` markers, so it scans predictably. No filler sentences, though the length is near the upper bound 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?

For a 17-parameter, zero-required tool with no output schema, the description covers every target's required inputs, defaults, limits, path safety rules, and the shared-mailbox prerequisite. Nothing needed to invoke 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 coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema states only piecemeal: format validity varies by target, includeAttachments defaults differ between single and batch, and savePath directory-vs-file resolution rules (path ending in `/` is created and given a unique name).

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 (export) and resource (emails to files) and enumerates the four distinct target modes with what each produces. An agent can tell immediately that this writes email content to disk, distinct from read-email or search-emails.

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

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

Gives clear per-target usage: which parameters apply to message vs messages vs conversation vs mime, and that emailIds and searchQuery/query are alternatives for batch. It even notes `query` is a convenience alias for callers used to search-emails. It never explicitly says when to prefer this over read-email for simple viewing, so it stops short of full sibling 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/idempotentHint/non-destructive, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: the M365-only limitation and empty-list return on personal accounts, plus the enumerated return fields and verbosity control.

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 dense sentences, front-loaded with what the tool does and what it returns before the filter details. Slightly packed with backticked tokens, but each clause carries information and nothing is redundant 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?

With no output schema, the description compensates by enumerating the returned fields (displayName, emailAddress, building, floor, capacity, bookingType) and the edge case of personal accounts. Behavior and return shape are adequately covered for a zero-required-param read tool.

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 descriptions already state the same semantics ('Search query (room name, email)', 'Minimum capacity required'). The description restates query-matches-name/email and capacity-as-minimum, adding little beyond what the schema carries, 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?

States a specific verb ('Discover bookable meeting rooms'), names the underlying Graph rooms endpoint, and distinguishes itself from siblings by naming `create-event` as the downstream consumer. An agent can tell exactly what this returns and how it differs from people/event search tools.

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

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

Gives clear filter semantics and an explicit when-not condition: 'Returns empty list on personal accounts (the rooms endpoint is M365-only).' It doesn't name a fallback tool for non-M365 users, but the usage context is otherwise 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?

Annotations already flag destructiveHint=true, but the description adds substantial context the annotations cannot convey: delete wipes subfolders too, skips Deleted Items, and has no restore path; dryRun previews losses; protected folders are undeletable; sharedMailbox requires delegate access plus Mail.Read.Shared/Mail.ReadWrite.Shared and the OUTLOOK_SHARED_MAILBOX server opt-in, otherwise the call is refused.

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 tool's core behavior, then a compact action-by-action walkthrough; every sentence carries operational information. It is a dense single paragraph rather than a scannable structure, which slightly hurts readability for a 17-parameter multi-action tool.

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 five-action, 17-parameter tool with no output schema, the description covers addressing semantics, per-action defaults, the dryRun safety workflow, protected-folder constraints, and shared-mailbox prerequisites. Nothing an agent needs to call any action 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 coverage is 100%, so the baseline is 3, but the description goes further by documenting folder addressing rules the schema does not: name vs slash-separated path (case-insensitive) vs ID, bare-name resolution order (unique top-level first, then nested), and ambiguity returning candidates. Defaults for list/stats and sharedMailbox aliasing are also clarified.

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

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

Opens with a specific verb+resource ('Manage mail folders') and then enumerates each of the five actions with its concrete effect (list returns the tree with paths/ids, create makes a name under a parent, move relocates emailIds, stats returns counts, delete removes a folder and its contents). An agent can tell this apart from siblings like manage-rules or access-shared-mailbox 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?

Gives explicit when-to-use detail per action, states the default (action=list), and includes when-not guidance (protected folders can't be deleted, pass dryRun first before destructive deletes). It does not, however, route the agent away from sibling tools that also touch mail organization (manage-rules, manage-category), so the alternative-selection layer is only intra-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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: it uses the existing Mail.Read scope with no extra permissions, and it enumerates the per-recipient tip categories returned. It doesn't mention rate limits or latency, which keeps it from a 5.

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

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

The description is information-dense but front-loads the core purpose and endpoint, then usage, then parameters. It is longer than typical but nearly every clause earns its place; the enumerated tip types are slightly list-heavy.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does so thoroughly by enumerating the tip categories. Combined with permission scope, usage guidance, and parameter behavior, an agent has everything needed 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 description coverage is 100%, so both parameters (recipients, tipTypes) are already documented in the schema. The description restates that recipients accepts a comma-separated string or array and that tipTypes defaults to all, but adds no syntax or behavioral 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 action (pre-send recipient validation), the resource (mail tips), and the underlying Graph endpoint POST /me/getMailTips. It distinguishes itself from send-email and draft by positioning itself as a pre-flight check, so an agent can tell it apart from siblings 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?

Explicitly says to use it ahead of send-email or draft action=create to catch OOO replies or external-recipient warnings, and notes that those tools can invoke it automatically via checkRecipients: true. This is a clear when-to-use with named alternatives and the condition that selects 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?

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial extra behavior: the default 'now' lower bound, the sort-order inversion when searching backwards, page-size limits, and the authoritative-UTC-plus-local-rendering time format.

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 purpose, scope, and default behavior, then layers filter and timezone details. Dense and mostly waste-free, though the timezone rendering sentence is longer 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, the description fully covers the returned fields (subject, location, start/end, body preview, id) and their format, so an agent knows what to expect without one.

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 each parameter is already documented. The description nonetheless adds interaction semantics the schema lacks: that supplying any filter replaces the default lower bound, that filters are AND-ed, and how each affects ordering.

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 (list calendar events) scoped to the signed-in user and explicitly read-only, which cleanly separates it from write-oriented siblings like create-event and manage-event.

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?

Clearly explains the default behavior (upcoming events from now) and when the optional filters change that default, including the AND-ed combination and sort-order effects. It does not name or contrast against sibling tools, so it stops short of full when/when-not/alternatives 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?

The description corroborates the idempotentHint annotation ('idempotent — safe to retry') and adds real value beyond structured fields by disclosing PATCH-style merge semantics and the dryRun preview behavior ('nothing is changed'). It also states the return value ('Returns the updated settings object on set actions'). It does not address the destructiveHint annotation directly (i.e., that set actions overwrite existing working hours/auto-reply configuration), 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?

Front-loaded with the core read/update framing, then grouped by action, so every sentence maps to a decision the agent must make. It is somewhat dense and re-enumerates enum values already present in the schema, which is redundant length rather than dead weight.

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 13-parameter, zero-required, multi-action tool with no output schema, the description supplies the missing glue: action semantics, parameter-to-action mapping, formats (ISO 8601, HH:MM), and the return value. Complete enough to invoke correctly; only permission/scoping caveats are absent.

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

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

Schema coverage is 100%, so the schema already documents every parameter, making 3 the baseline. The description adds cross-parameter meaning the schema cannot express: which parameters belong to which action, that startDateTime/endDateTime select scheduled mode, that externalReplyMessage is optional, and that dryRun is rejected for non-set-auto-replies actions.

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 opening clause states a specific verb pair and resource ('Read or update mailbox-level settings') and then enumerates the three actions (get, set-auto-replies, set-working-hours), which no sibling tool covers. An agent can distinguish it from manage-rules, manage-focused-inbox, and access-shared-mailbox without opening any schema.

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

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

It gives clear per-action context: action defaults to get, section filters the read, set-auto-replies configures out-of-office, set-working-hours updates the schedule. It also explains the dryRun preview path for set-auto-replies. It does not state when NOT to use this tool or name a preferred alternative for overlapping tasks, so it stops short of a 5.

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

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

Annotations already flag destructiveHint=true, but the description adds genuinely non-obvious behavior: delete does NOT untag messages, leaving orphaned labels until manual cleanup. It also flags the deprecated 'set' alias, which the annotation set cannot convey. It doesn't mention idempotency or permission requirements.

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

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

A single dense paragraph that front-loads the resource, then walks actions in a predictable order, closing with the destructive caveat and the sibling redirect. No sentence is redundant.

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

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

With no output schema, the description carries the return-shape burden and does so for list (id/displayName/color), but is silent on what create/update/delete return. It compensates well on the destructive-delete semantics, so the 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 the baseline is 3, but the description maps parameters to actions ('displayName required' for create, 'color optional', 'id' for update/delete) and repeats the preset0=Red/preset7=Blue decoding, adding conditional-requirement context the flat schema does not surface.

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 resource (the user's master category list) and enumerates all four operations with their exact effects. The parenthetical 'the colour-coded labels available across mail/calendar/contacts' disambiguates the resource, and the closing pointer to apply-category separates this tool from the tagging sibling.

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?

Each action is paired with its trigger condition ('action=list (default)', 'action=create adds', 'action=delete removes'), and it explicitly routes tagging/untagging to apply-category. It lacks a stated 'when not to use' or prerequisite/permission guidance, but the action-level routing is 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?

Goes well beyond the annotations: delete skips Deleted Items so it is irreversible, dryRun is only honored on delete (other actions refuse it and change nothing), update patches only the fields passed, and pagination defaults differ per action (50 list / 25 search). The annotations only carry destructiveHint=true and readOnlyHint=false; the description supplies the operational consequences.

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 scope and the destructive warning, then walks actions in a consistent pattern with no filler sentences. It is dense but slightly long, with pagination and verbosity details that are partly duplicated by the schema descriptions.

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 17-parameter, action-dispatch CRUD tool with no output schema, the description covers every action, defaults, side effects, safety workflow, and sibling routing. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: `outputVerbosity` values control returned field count, `skip` should echo the previous page's suggested value, `id` scoping across get/update/delete, and update's patch-only semantics. It largely restates defaults already in the schema, which caps it below 5.

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

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

States a specific verb (full CRUD) plus the exact resource (signed-in user's personal Outlook contacts) and enumerates every action with its effect. It also distinguishes itself from the sibling `search-people` by scope (personal store only), so an agent can pick between them 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?

Gives explicit per-action routing (list/search/get/create/update/delete), names the required inputs for each, and states the alternative for ranked cross-source search (`search-people`). It also prescribes a workflow: pass `dryRun: true` before a permanent delete to confirm the target contact.

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 non-idempotent, but the description adds substantially: dryRun previews emails and PATCH body, delete has no guaranteed recovery, deleting an organised meeting still emails attendees a cancellation, and sendResponse: false declines silently. This goes well beyond 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?

Well front-loaded with the dryRun behaviour first, then actions in order, ending with the no-accept note. Some density from the long parenthetical field lists, but every sentence adds actionable information and nothing is redundant.

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

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

For a destructive, non-idempotent mutation tool with no output schema, the description covers the behavioural risks (irreversibility, unintended emails), the preview mechanism, action semantics, and the accept workaround. An agent has enough to invoke correctly and avoid surprises.

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 schema documents each parameter including the complex attendees replacement semantics. The description adds meaning beyond the schema by grouping parameters by action, noting 'only fields you pass change', and clarifying cancel/delete email behaviour tied to comment. Small gap: reminderMinutesBeforeStart, isOnlineMeeting, and the full field list aren't individually explained in prose, but the action-fields mapping 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 specifies a clear verb and resource and distinguishes the four actions: update (edits fields via PATCH), decline (declines invitation), cancel (cancels an event you organised and emails attendees), and delete (removes the event). It also names sibling create-event by positioning itself as operating on an existing event.

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 on when to use cancel versus delete ('use cancel with a comment to control that message'), that accept is unavailable and should be done in the Outlook UI, and the role of dryRun as a preview. This is the strongest kind of when-to-use/when-not-to 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 flag destructiveHint=true, readOnlyHint=false and idempotentHint=false, and the description adds substance on top: delete removes the override, set creates or updates, and accounts lacking Focused Inbox silently return an empty list rather than erroring. That last caveat is genuine context an annotation cannot 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?

Front-loaded with the resource definition, then three tight action clauses, then the account caveat. No sentence is redundant and the ordering matches how an agent would reason about the call.

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

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

With no output schema, the description usefully names the returned fields for list (id/sender/classifyAs), covers defaults for every optional parameter, and discloses the empty-list edge case. An agent has everything needed to pick an action and 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 description coverage is 100% and the schema already documents defaults, enums and which action each parameter belongs to, so the baseline is 3. The description restates those mappings and clarifies that emailAddress is the keying field, but adds no syntax or format 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?

States a specific verb+resource ('Manage Focused Inbox sender overrides') and immediately defines the resource as explicit per-sender rules that override the ML classifier, which cleanly separates it from generic siblings like manage-rules. The three action values are enumerated with their effects.

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

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

Gives clear per-action conditions (list=default, set=create/update for emailAddress, delete=remove) plus a real prerequisite: the account must have Focused Inbox enabled. It stops short of explicitly routing the agent away from manage-rules or mailbox-settings when a user actually wants general rule configuration.

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?

Adds substantial context beyond the annotations: delete is the destructive path, dryRun previews create/update, rules execute server-side regardless of client, the recipient allowlist applies to forwardTo/redirectTo, changes count against a session limit governed by OUTLOOK_MAX_MANAGE_RULES_PER_SESSION (falling back to OUTLOOK_MAX_EMAILS_PER_SESSION) with 0 refusing changes, and there is no permanentDelete action.

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 dense paragraph that front-loads the destructive warning and dryRun semantics before the action breakdown. Nearly every clause carries information, though the action list and parameter-group enumeration 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?

For a 37-parameter, multi-action tool with no output schema, the description covers action semantics, defaults, side effects, allowlist constraints, and session limits, and briefly indicates the list return shape (id/name/sequence). An agent has what it needs to choose an action and 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 description coverage is 100%, so the baseline is 3, but the description adds value by grouping parameters (12 condition params, 9 action params, except* exceptions) and noting folder syntax (name, nested path like Triage/Delete, well-known name, or ID). Most field-level detail, however, is already in the schema.

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

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

States a specific resource (server-side inbox rules) and enumerates the exact action set: list, create, update, reorder, delete. An agent can distinguish this from siblings like manage-category or manage-focused-inbox 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?

Gives per-action conditions and defaults (action=list default, dryRun only valid for create/update and refused elsewhere, ruleId vs ruleName for update/delete/reorder). It does not explicitly route to sibling tools, but the action-level guidance is concrete 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?

Well beyond the annotations: it discloses default truncation at 2,000 characters vs 40,000 with outputVerbosity: full, that truncated bodies end with a remediation note, the exact failure mode (404 ErrorInvalidMailboxItemId) for mailbox-scoped ids, and that shared-mailbox access requires delegate access, Mail.Read.Shared, and the OUTLOOK_SHARED_MAILBOX opt-in.

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 dense paragraph, but it is front-loaded with the core behavior (read by id, what is returned, truncation limits) before moving to the mode flags and the critical sharedMailbox warning. Some phrasing duplicates the schema's sharedMailbox text, which costs a little 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?

For a 9-parameter, mode-heavy tool with no output schema, the description covers what comes back, how much, how it is truncated, how the header modes alter the payload, and the single highest-risk failure mode. An agent has everything needed 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 100%, so baseline is 3, but the description adds cross-parameter semantics the schema does not: raw/importantOnly/groupByType are explicitly scoped to headersMode, and includeHeaders is described as the non-headers-mode variant. The outputVerbosity character budgets and the sharedMailbox 404 consequence go beyond the field-level descriptions.

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

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

States a specific verb and resource ('Read a single email by id') and immediately scopes it as read-only, which distinguishes it from siblings like search-emails, send-email, and update-email. The return payload is enumerated concretely (subject, from/to/cc, date, body as Markdown).

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

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

Gives clear mode-selection guidance (headersMode, includeHeaders, outputVerbosity) and a hard routing rule: if the id came from search-emails or access-shared-mailbox with sharedMailbox set, the same sharedMailbox MUST be passed here. It does not explicitly state when NOT to use this tool (e.g. for multiple messages), so it stops short of full when/when-not/alternatives coverage.

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 read-only, idempotent, non-destructive, openWorld, so the bar is lower, yet the description still adds real behavior: automatic OData fallback on personal accounts, `deltaToken` being authoritative/rejected cross-mailbox, shared-mailbox opt-in refusal, and scan truncation. It stops short of describing pagination cursor absence and rate limits in the description itself, though those appear 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?

The mode summary is front-loaded and each clause is terse shorthand rather than prose, but the single dense paragraph repeats substantial ground already covered by the 23 schema descriptions, making it heavier 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?

For a 23-parameter multi-mode tool with no output schema, the description covers mode selection, per-mode caveats, fallback behavior, error/opt-in conditions, and the return shape (id/subject/from/receivedDateTime/preview plus outputVerbosity). Nothing essential to correct invocation 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?

With 100% schema coverage the baseline is 3, and the schema already documents each parameter thoroughly; the description adds connective meaning by framing parameters as mode selectors and flagging the `kqlQuery` deprecation and the relevance-not-recency caveat for `searchExpression`. That is genuine added value beyond the schema 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?

Opens with a specific verb set and resource: 'Search, list, delta-sync or thread-group emails (read-only); parameters set the mode.' An agent immediately understands this is a multi-mode read tool and that the parameters select the mode, which cleanly separates it from read-email and 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?

Gives an explicit mode-selection map (no params = recent listing; filters = OData search; searchExpression = raw $search; deltaMode = sync; groupByConversation = threads) and names alternatives where it matters, e.g. preferring structured filters or `query` over `searchExpression` on personal Outlook.com accounts.

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 (read-only, idempotent, open-world, non-destructive), so the bar is lower, yet the description still adds real value: relevance-ranked ordering, the three data sources searched, and the five fields returned. That return-shape disclosure matters especially since there is no output 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?

Three sentences with zero filler, ordered purpose → returns → alternative routing, so the most decision-relevant information leads. Each sentence carries a distinct load.

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 two-parameter, flat, read-only search with complete schema coverage and full annotations, the description supplies the only missing pieces: the result shape (compensating for the absent output schema) and the sibling boundary. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 100%, so both `query` and `count` (with its default/max bounds) are already fully documented in the schema. The description adds only the framing that `query` covers name, email, or company, which duplicates rather than extends the schema's own wording. Baseline 3 is correct.

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 ('relevance-ranked search') plus the exact resource scope (personal contacts, organisation directory, recent communications) and the backing API. The named return fields let an agent confirm this is a people-lookup tool distinct from search-emails or list-events 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 concrete triggering intents ('who is X?', 'who do I email about Y?') and explicitly routes the personal-contact-store-only case to a named sibling with its exact action argument. Nothing about when-to-use is left 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 declare destructiveHint=true and openWorldHint=true, but the description adds substantial behavioral context: the session-limit env vars, recipient allowlist enforcement, the refuse-before-Graph-request behavior, the acknowledgeWarnings gate, and the caveat that Outlook.com accounts return no tips and no warnings is not proof of delivery.

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 and front-loaded, with the destructive warning and primary purpose stated first, then safety controls, then the draft alternative. It is on the longer side with several env-var names, but nearly every sentence carries actionable 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?

No output schema exists, but the description states it returns a confirmation. Combined with the safety-control, refusal, and limit semantics, an agent has everything needed to invoke this 10-parameter mutation 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter logic the schema lacks: the interaction between checkRecipients and acknowledgeWarnings, that acknowledgeWarnings has no effect without checkRecipients, and that comma-separated strings or arrays are both accepted.

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 ('compose and send an email immediately') plus the return behavior ('Returns a confirmation') and explicitly flags the destructive nature. It clearly differentiates from the sibling 'draft' tool by naming it as the alternative for review-before-send.

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 alternatives and the conditions that select them: dryRun for preview, checkRecipients for mail-tip gating, and 'For a review-before-send workflow, use draft'. It also states when-not (warnings refuse the send until acknowledgeWarnings) and the allowlist/session-limit refusal 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?

Goes well beyond the annotations: it explains why idempotency holds (safe to retry), that batch updates issue one PATCH per message rather than a Graph $batch, that unparseable or date-only times are refused before any change occurs, and it spells out auth/delegate prerequisites and the server opt-in setting. This is exactly the behavioral context annotations alone cannot 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 front-loaded with the core guarantee ('update state without modifying content') and every subsequent sentence carries distinct, load-bearing detail. It is dense but somewhat long; a few clauses could be tightened, but nothing is filler.

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

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

For a 7-parameter mutation tool with no output schema, it covers all the decision-relevant surface: per-action requirements, batch semantics, timezone edge cases, permission/opt-in prerequisites, and even the return shape ('a status per message'). An agent can invoke this correctly without further inference.

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?

Although schema coverage is 100%, the description adds semantics the schema does not: the timezone resolution rule for zoned vs unzoned ISO strings, the 09:00 default start (capped at the due time) when only `dueDateTime` is given, the `email` alias for `sharedMailbox`, and the single-vs-batch behavior of `id`/`ids`. These are genuine additions, not restatements.

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 opening clause names the exact operation and its boundary: 'Update message state without modifying content', which cleanly separates it from siblings like read-email, send-email, and draft. It then enumerates the concrete state transitions (read/unread, flag/unflag/complete), so an agent knows precisely what this tool touches.

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 maps each action to its purpose and states conditions: mark-read/mark-unread need a single `id`, flag/unflag/complete accept `id` or `ids`, and `sharedMailbox` is only for delegated mailboxes needing Mail.ReadWrite.Shared plus the OUTLOOK_SHARED_MAILBOX opt-in. It does not explicitly route the agent to a sibling (e.g. read-email for content), so usage context is clear but not fully comparative.

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