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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real value beyond them: it clarifies the operation is non-committal (no booking, no invitations) and that per-user schedules plus Graph-reported errors are returned. It does not mention permission requirements for reading other users' free/busy, which is the main remaining gap.

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

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

Three short sentences, front-loaded with the core action, then the negative boundary, then sibling routing. Every sentence carries distinct information with no repetition of the name or schema.

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

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

With no output schema, the description steps in to say what is returned (per-user schedules and Graph errors), and it rules out side effects. It stops short of noting practical constraints such as permission scope for other mailboxes or Graph limits on users/ranges, which would matter for a free/busy lookup.

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 three parameters (users, startDateTime, endDateTime) are already documented, including timezone handling. The description only restates 'supplied users and time range' and adds the 30-minute view granularity, which is output detail rather than parameter meaning. 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: 'Read free/busy schedules for the supplied users and time range', plus the granularity of the result ('30-minute availability view'). It is clearly distinguishable from m365_calendar_list (event details) and m365_calendar_create (booking), both of which it names.

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 negative boundary ('does not book a meeting or send invitations') and names the follow-up alternative with its condition: use m365_calendar_create after selecting a time, m365_calendar_list for event details. An agent knows exactly when to pick this tool versus its siblings.

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

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

The annotations already declare destructive=true, openWorldHint=true, and idempotentHint=false, so the safety profile is clear. The description adds useful behavioral context by stating the caller must organize the event and that attendees are notified, going beyond the annotations without contradicting them.

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

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

The description is a single focused sentence with the action and key constraints front-loaded. There is no redundant or filler text.

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

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

For a simple two-parameter cancellation tool with full schema coverage and annotations covering destructive behavior, the description provides enough context to invoke it correctly. The main remaining gap is lack of explicit differentiation from sibling calendar deletion/decline tools.

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 both parameters are documented in the input schema, so the description does not need to repeat parameter details. It adds only light context by implying that attendee notification relates to the optional comment, but the schema already carries the substantive parameter semantics.

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 and resource: cancel a calendar event. It also scopes the action to events the caller organizes and notes attendee notification, though it does not clearly distinguish cancel from sibling operations such as m365_calendar_delete or m365_calendar_decline.

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 by the phrase 'calendar event you organize,' which suggests the prerequisite and intended scenario. However, the description does not explicitly say when to prefer cancel over delete or decline, nor does it state what to do if the caller is not the organizer.

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

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

Annotations already declare readOnly=false, openWorld=true and idempotentHint=false; the description goes beyond them by explaining the concrete side effect (attendee emails are sent), the Teams dependency for isOnline, the non-idempotent duplicate-event risk, and the return payload. That is exactly the extra context annotations cannot express.

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?

Four tight sentences, each carrying distinct information: purpose, attendee branching, sibling routing, and failure recovery. The most decision-critical content (what it creates, what it sends) 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?

For a 9-parameter mutation tool with no output schema, the description still covers the return value ('event ID and available links'), the invitation side effect, the duplicate risk, and the alternatives. Nothing an agent needs in order to call this safely 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 the schema already documents all nine parameters, including the timezone conventions for start/end and the calendarId shared-access caveat. The description adds only light framing ('personal appointment', 'optionally as a Teams meeting') beyond what the schema states, 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?

States a specific verb and resource ('Create a new event ... in your default or selected mailbox calendar') and immediately names its distinguishing modifier ('optionally as a Teams meeting'). An agent can separate it from m365_calendar_update, m365_calendar_cancel and m365_calendar_list 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 explicit routing rules: 'Use m365_calendar_update to edit an event or m365_calendar_availability to check free/busy first', plus a recovery procedure ('check m365_calendar_list before resubmitting after an uncertain outcome'). It also states the branch condition that changes behavior (supply attendees vs. omit 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 declare destructive/non-idempotent/open-world, and the description adds behavior they do not cover: a response email is sent to the organizer by default, sendResponse=false suppresses it, and the call returns success plus eventId. The retry caution is consistent with idempotentHint=false and fills the exact gap a non-idempotent destructive call creates.

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?

Four short sentences, scope constraint front-loaded, then the default email behavior, then the sibling routing, then the return/retry guidance. Every sentence carries information an agent would otherwise have to infer.

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 still discloses the return shape (success and eventId) and how to verify state via m365_calendar_list. For a three-parameter destructive invitation tool, nothing needed to call it safely or to recover from an ambiguous result 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 all three parameters are already documented, including the sendResponse default and the comment's dependency on sendResponse=true. The description restates the default behavior and the eventId source without adding syntax, formats, or constraints beyond the schema, 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 (decline) and resource (received invitation) and immediately constrains scope to attendee-side invitations, explicitly not events the user organizes. It names the sibling m365_calendar_cancel as the organizer-path tool, so an agent can distinguish it from cancel/delete/update 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 explicit routing ("Use m365_calendar_cancel if you are the organizer") plus a retry protocol: check response status in m365_calendar_list before retrying an uncertain decline. Both the when-to-use-alternative and the recovery path are spelled out rather than 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 already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description adds real substance: cancellation notices are sent to attendees, it is not a silent delete, it only applies to events you organize, and it returns success plus eventId. The retry warning operationalizes the non-idempotent hint instead of leaving the agent to deduce it.

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

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

Three short sentences, front-loaded with the alias relationship, then alternatives, then return/retry behavior. Every clause carries distinct information with no restatement of the tool name or schema.

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

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

For a destructive, non-idempotent, alias-named tool with no output schema, the description supplies everything an agent needs: what it actually does, which sibling to prefer, what recipients experience, and what the response contains. No output schema is needed given the stated 'returns success and eventId'.

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% for both parameters, so the schema already explains eventId and comment. The description adds no syntax, format, or constraint detail about either, which is acceptable but not additive; 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 ('cancel an event you organize and send cancellation notices to attendees') and explicitly frames itself as a compatibility alias for m365_calendar_cancel. It immediately rules out the two nearest misreadings ('not a silent delete or an attendee decline'), so the agent can distinguish it from m365_calendar_cancel and m365_calendar_decline 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 explicit routing rules: prefer m365_calendar_cancel for new calls, use m365_calendar_decline for received invitations. It also covers the retry case ('check the calendar before retrying an uncertain cancellation'), so both selection and post-failure behavior are prescribed 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 read-only, idempotent, non-destructive, open-world behavior. The description adds useful behavioral context about returned content: notes are included, body format and length matter, and truncation status is explicit.

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 a single front-loaded sentence with no filler. The trailing phrase 'with body format, length and explicit truncation status' is slightly compressed and awkward, but not wasteful.

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

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

For a simple read-by-ID tool with full schema coverage and annotations covering safety traits, the description gives enough context: it reads one event, includes notes, and surfaces truncation. Missing return-shape detail is acceptable because no output schema exists but the core response traits are noted.

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 eventId, calendarId, and maxBodyChars in detail. The description only hints at body format/length/truncation and does not add parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Read one event including its notes.' The phrase 'one event' helps distinguish it from calendar list/week/today siblings, though no sibling is explicitly named.

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

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

Usage is only implied by 'Read one event'; there is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternative such as m365_calendar_list or m365_calendar_week.

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 non-destructive behavior, so the safety profile is covered. The description adds one genuinely non-obvious trait — recurring events are only expanded when both dates are supplied — but stops short of saying what the default range is or what occurs with partial date input, and says nothing about result volume or pagination despite a 'top' cap.

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 short sentence with the primary action front-loaded and zero padding. It is efficient, though the second clause is slightly compressed to the point of ambiguity about partial date input.

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?

Hmm—reconsidering: the tool is a list operation with no required parameters, no output schema, and no nested objects. The description leaves unclear what happens by default when no dates are given, which for a zero-required-param list tool is the most likely call pattern. Given the absence of an output schema and the breadth of calendar siblings, this is a meaningful omission.

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 four parameters are already documented, including the calendarId default-scope note and ISO 8601 formatting. The description adds no format or syntax 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 ('List calendar events'), so the operation is unambiguous. However it does not distinguish itself from siblings like m365_calendar_today, m365_calendar_week, m365_calendar_get, or m365_calendar_availability, leaving the agent to infer which listing variant to pick.

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

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

The phrase 'supply both dates to expand recurring events within a range' is a real usage rule for the date parameters. But there is no guidance on when to choose this over the today/week/get/availability siblings, and no statement about what happens when dates are omitted.

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 and destructiveHint=false, covering safety. The description adds the 'today' scope, which is beyond annotations, but does not disclose return format, timezone behavior, or other operational details. Minimal additional transparency provided.

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

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

The description is a single concise sentence with no wasted words. The action and scope are front-loaded, making it immediately understandable.

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

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

For a simple, zero-param, read-only tool with strong annotations, the description is adequate. It lacks details about output format or timezone, but given the low complexity, additional explanation is not strictly necessary. It still covers the core purpose.

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 zero parameters and an empty schema, there is nothing to explain. The baseline for 0 params is 4, and the description adequately communicates the tool's function without needing parameter details.

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

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

The description clearly states the action ('show') and resource ('calendar events') with a specific scope ('today'), distinguishing it from siblings like calendar_week and calendar_list. It is specific and unambiguous.

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

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

The description implies use when today's events are needed but provides no explicit guidance on when to use alternatives or exclusions. No sibling tools are mentioned, so the context is clear but not fully differentiated.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false, and openWorldHint=true; the description goes beyond them by disclosing attendee notification side effects, that body updates replace rather than append notes, and that online-meeting details must be preserved by reading first. These are non-obvious mutation behaviors an agent could not infer from annotations alone.

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?

Five short sentences, each carrying distinct information: patch semantics, side effects, body-replacement hazard, sibling routing, and return/retry behavior. The core contract is front-loaded in the first clause 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?

There is no output schema, and the description compensates by stating the return shape ('success and eventId'). Combined with annotations covering the safety profile and a 100%-covered input schema, an agent has everything needed to invoke this correctly and handle uncertain outcomes.

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 per-field replacement/clear semantics are already documented; the description reinforces the omit-preserves rule and elevates the body-replacement caveat about online-meeting details. It adds cohesion and a warning beyond the schema, though most field-level detail is duplicate.

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 ('Change supplied fields on an existing event') and immediately clarifies the patch semantics ('omitted fields stay unchanged'). It distinguishes itself from m365_calendar_create, m365_calendar_cancel, and m365_calendar_get by name, so an agent can route 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 names alternatives and the conditions selecting them: create for new events, cancel to cancel, get to read before a body update. It also gives a retry guardrail ('Check the event before repeating an update after an uncertain outcome'), which is exactly the when/when-not guidance the dimension asks for.

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 and destructiveHint=false, covering the safety profile. The description adds the grouping-by-day behavior and the week scope, which are useful beyond the annotations. No hidden mutation or side effects are implied, and no contradiction exists.

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

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

The description is a single, front-loaded sentence that communicates action, resource, scope, and output organization with no wasted words. It is appropriately sized for a zero-parameter 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 simple read-only calendar query with no parameters and no output schema, this description is complete. It tells the agent exactly what the tool returns and how it is organized, and the annotations cover safety considerations.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics because there are none, and the schema fully covers the empty parameter set.

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

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

The description states a specific action ('Show'), a clear resource ('calendar events'), and precise scope ('this week's ... grouped by day'). It is immediately distinguishable from sibling tools like m365_calendar_today (today) and m365_calendar_list (general listing).

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 implies this tool is for retrieving calendar events for the current week, grouped by day, which establishes when to use it. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for an agent to select it over the sibling today/list tools.

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

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

Annotations already declare the tool as read-only, non-destructive, idempotent, and open-world. The description adds behavioral context by specifying 'unique' (deduplication) and 'usage counts' (aggregation behavior), which go beyond the annotations. No contradictions are present.

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

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

A single, front-loaded sentence of 13 words. It states the action, target, and output. Every word is informative, 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 relatively simple read-only aggregation tool, the description fully covers purpose, scope, and output. The schema handles parameter details, and annotations cover safety. No output schema is present, but the description sufficiently indicates the return nature (category names with usage counts).

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%: both parameters have descriptions explaining their meaning. The tool description only reinforces the 'default or selected folder' concept already present in the schema, without adding new semantic details. Therefore, 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 uses a specific verb 'List' with a clear resource ('unique category names assigned to contacts') and scope ('default or selected folder'), plus an additional outcome ('with usage counts'). It distinguishes the tool from siblings like m365_contacts_list or m365_contacts_search by focusing on categories rather than contact details.

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 implies the use case: retrieving contact categories with their frequencies. It provides context that this is for category aggregation, not for general contact listing or searching. However, it doesn't explicitly mention alternatives or exceptions, but the context is clear enough.

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

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

Annotations already indicate this is a non-read-only, non-destructive, non-idempotent operation, and the description's 'Create' is consistent. The description adds no extra behavioral details (e.g., return value, duplication behavior, required permissions) beyond what annotations offer, but it does not contradict them either.

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

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

The description is a single, tightly packed sentence with no filler. It front-loads the core action and quickly lists the major data categories, making efficient use of space.

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 35 parameters, nested objects, and no output schema, the description is rather minimal. It does not state what the tool returns after creation, nor whether any fields are required or how folders are handled. However, the schema itself contains many per-field descriptions, and the summary captures the tool's scope, so it is adequate but not comprehensive.

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 49% (low), so the description should compensate. It provides a high-level summary of field categories (names, emails, phones, etc.), which helps orient the agent, but it does not explain nuances like convenience fields vs. complete-list behaviors or empty-array clearing semantics that appear in the schema. It adds moderate value without fully compensating for low 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?

The description uses a specific verb ('Create') and resource ('a contact'), and enumerates key field categories (names, emails, phones, categories, addresses, work/personal details), clearly distinguishing it from sibling tools like contacts_update, contacts_delete, and contacts_list.

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

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

The verb 'Create' implies use for new contacts, and sibling tools like contacts_update signal the alternative for existing contacts. However, the description does not explicitly state when to use this tool versus alternatives, nor any prerequisites or common patterns, so usage guidance is merely 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 include destructiveHint=true and idempotentHint=true, which already indicate a mutating, repeatable operation. The description adds valuable nuance that this is a soft delete (moving to Deleted Items) rather than a permanent removal, implying recoverability. It does not contradict annotations and provides meaningful behavioral context beyond the structured 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?

The description is a single, tightly written sentence that gets straight to the point. It contains no filler or redundant information, and every word contributes to understanding the operation. It is front-loaded with the action and destination.

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

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

For a simple delete/move operation with only 3 parameters and no output schema, the description is adequately complete. It explains the essential behavior (move to Deleted Items) and benefits from annotations covering destructiveness and idempotency. It could mention permission requirements or error behavior, but these are not critical for a straightforward 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 description coverage is 67%: folderId and parentFolderId have descriptions, but contactId is undocumented. The description itself does not explain any parameters. Since coverage is moderate and the key required parameter (contactId) lacks explanation, the description does not fully compensate. It adds nothing beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description 'Move a contact to Deleted Items' uses a specific verb ('Move') and identifies the resource ('contact') and the target state ('Deleted Items'). This clearly distinguishes it from permanent deletion or other contact operations like update or list, and avoids tautology.

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 implies the use case: when you want to remove a contact from the active contact list by moving it to Deleted Items. While it doesn't name alternatives, the sibling tools (e.g., m365_contacts_update, m365_contacts_create) make the purpose self-evident. No exclusions or edge cases are mentioned, but the context 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?

Annotations already indicate this is a write operation (readOnlyHint=false) and not idempotent (idempotentHint=false). The description adds the precondition that the parent folder must already exist, which is useful. However, it doesn't disclose other behaviors like potential side effects or error conditions.

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

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

The description is a single, concise sentence that is front-loaded with the action and resource. Every word contributes semantically 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?

For a simple create operation with two required parameters and no output schema, the description covers the core action but lacks usage guidelines, parameter details, and any behavior beyond the precondition. It is minimally adequate but leaves gaps in context.

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 0%, so the description must compensate for parameter meaning. It implicitly refers to parentFolderId via 'under an existing contact folder' but does not explain displayName or the expected format/values. The property names are somewhat self-explanatory but the description adds minimal value beyond them.

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

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

The description clearly states the action ('Create') and the specific resource ('a child contact folder under an existing contact folder'). It distinguishes this tool from siblings like m365_contacts_folder_update, m365_contacts_folder_delete, and m365_contacts_create, which handle different operations or resource types.

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

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

The phrase 'under an existing contact folder' implies a prerequisite and context (you need a parent folder), but there is no explicit guidance on when to use this over alternatives, nor any exclusions. Usage is mostly implied from the resource type.

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 idempotentHint=true, covering the safety profile. The description adds the hierarchy constraint (top-level vs direct-child) which is useful, but doesn't disclose consequences like permanence, whether folder must be empty, or behavior on failure. This is consistent with annotations and adds moderate value.

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

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

One sentence, no filler, front-loaded verb. Every word earns its place.

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

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

For a simple delete operation with 2 params and no output schema, the description plus annotations cover the core needs: what it deletes, the target scope, and destructive nature. Some gaps remain on how 'non-default' is defined and what happens on success/failure, but overall sufficient.

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

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

Schema provides descriptions for parentFolderId but not folderId (50% coverage). The description's phrase 'direct-child' gives context that parentFolderId is needed for children, reinforcing the schema description, but doesn't clarify folderId format or required semantics beyond its name. With 50% coverage, the description partially compensates.

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

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

The description uses the specific verb 'Delete' with the resource 'contact folder' and adds scope constraints ('non-default top-level or direct-child'), which clearly distinguishes it from sibling tools like contacts_delete (deletes a contact) and folder_update (mutates folder). It clearly states what the tool does.

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

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

The description identifies the exact conditions for use: non-default, top-level or direct-child folders. This implies not for default folders or deeper nesting, giving an implicit exclusion. However, it does not explicitly name alternative tools or say 'use folder_update for moving/deeper folders', so it is clear context but lacks explicit alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the meaningful behavioral nuance that the tool returns either top-level folders or only direct children (non-recursive) depending on parentFolderId. It does not cover pagination, default top limits, or error behavior, but the annotations lower the bar for safety disclosure.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently conveys the resource and the conditional two-mode behavior without wasted words.

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

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

The tool is low-complexity with read-only annotations, and the core behavior is clear. However, with 0% schema coverage and no output schema, the description should have explained the `top` parameter to be fully self-sufficient. It is adequate but has a clear 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 0%, and the description only implicitly explains parentFolderId as the folder whose children are listed. The `top` parameter is completely unexplained, leaving half the parameter surface undocumented. This fails to compensate for the missing schema descriptions.

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

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

The description uses a specific verb 'List' with the resource 'contact folders' and clearly distinguishes the two scopes: top-level folders or direct children of one folder. This differentiates it from sibling tools like m365_contacts_folder_create/update/delete and m365_contacts_list.

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

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

The description implies usage through its two modes (top-level vs direct children) but provides no explicit when-to-use guidance or alternatives. It does not state when to prefer this tool over other folder-related tools or when not to use it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description adds scope clarification (folder only, not contacts or categories) and states the return ('updated folder with success'), but never explains what makes this destructive or what happens to child folders during a move — a notable gap given destructiveHint=true.

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?

Four short sentences, front-loaded with the action and its scope exclusions, then the parameter recipe, then ID source, then return. No filler and nothing repeated unnecessarily.

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 says it returns the updated folder with success, and all four parameters are covered. The only missing piece is a consequence note for moves (child folders, contacts inside) to justify the destructive hint, which keeps it from a 5.

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 goes beyond the schema by stating that displayName and moveToParentFolderId may be supplied together or alone and by framing parentFolderId as the 'current' parent versus the destination. That combination rule is real added meaning not spelled out 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?

Specific verb pair (rename/move) plus resource (contact folder), and it explicitly scopes out contact/category mutation, which separates it from siblings like m365_contacts_update and m365_contacts_folder_create. An agent can identify the tool from the first clause alone.

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?

States the required combination ('supply displayName, moveToParentFolderId, or both'), explains the parentFolderId vs moveToParentFolderId distinction, and names m365_contacts_folders_list as the source of valid IDs. This is explicit when-to-use and prerequisite guidance with a named alternative.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context (optional folder, exact categories) but does not disclose return format, pagination, or default behavior beyond what schema already states. No contradiction with annotations.

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

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

A single concise sentence that is front-loaded with the main purpose. No redundant words or unnecessary detail; every word earns its place.

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

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

For a list tool with 6 optional parameters, the description is brief but adequate given rich schema descriptions. However, it omits details like return format, pagination, and how filtering parameters interact, which would be helpful without an output 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 83%, so the schema already explains most parameters. The description adds a high-level summary of folder and category filtering but does not detail relationships between category, categories, and categoryMatch. Value added over schema is marginal.

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

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

The description clearly states the tool lists contacts with optional folder scoping and exact category filtering, using a specific verb and resource. It distinguishes from read/search operations by focusing on 'list' behavior, but does not explicitly name alternatives like m365_contacts_search.

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

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

The description implies usage for listing contacts with folder/category filters, but provides no explicit guidance on when to use this tool versus alternatives such as m365_contacts_search or m365_contacts_read. No exclusions or 'instead of' instructions are given.

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, destructiveHint=false, and idempotentHint=true, covering safety. The description adds behavioral context by indicating 'relevance-ranked' ordering and the source of people (mailbox, directory, both), plus the limitation of not exposing private lists. This goes beyond the annotations without contradicting them.

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

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

The description is a single, well-structured sentence that conveys the core purpose, data sources, and an important exclusion. It is front-loaded with the primary function and contains no unnecessary words or repetition.

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

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

Given the moderate complexity (5 parameters, no output schema) and strong safety annotations, the description covers the key behavioral aspects: what it searches, how results are ranked, and what it excludes. It lacks explicit mention of the 'personType' filter or 'includeProfile' option, but those are described in the schema. It is sufficiently complete for an AI agent to understand the tool's scope and important caveats.

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

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

Schema description coverage is 80%, with most parameters explained in the schema. The description itself does not elaborate on parameters, but the 'relevance-ranked' and 'mailbox vs directory' framing adds some context to the 'source' parameter. Since the schema covers most semantics, the description provides marginal added value.

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

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

The description clearly states the tool's function: 'Find relevance-ranked people for recipient selection using mailbox signals, the organization directory, or both.' It specifies the verb 'Find', the resource 'people for recipient selection', and distinguishes itself from related tools like m365_contacts_list and m365_contacts_search by highlighting its focus on mailbox/directory signals and its explicit exclusion of private Outlook Contact Lists.

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

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

The description implies usage for recipient selection in mail scenarios and clarifies that it does not expose private Outlook Contact Lists, which warns against using it for that purpose. However, it does not explicitly name alternative tools for contact list access or provide direct when-to-use vs. sibling tool guidance. The context is clear but lacks explicit exclusions beyond the private list limitation.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real context: the full Graph record is returned and the folder context must match the one used to fetch the ID. It does not say what happens when the ID/folder combination is wrong (error vs empty), which keeps it below 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 tight sentences, front-loaded with the action and return value, followed by ID acquisition and ID-type exclusions. Nothing is redundant with the schema.

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

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

With no output schema, the description compensates by stating the tool returns the complete Graph contact record, and it covers the ID provenance and folder scoping needed to call it correctly. Only failure behavior for a bad ID or mismatched folder is left unstated.

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 tying folderId to the folder used to obtain the ID and by warning that contactId is not a directory or People API ID. It does not explain parentFolderId, which the schema alone carries.

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 saved Outlook contact by its contact ID') plus the return shape ('complete Graph contact record'). It also separates itself from m365_contacts_list, m365_contacts_search and m365_users_profile by naming the ID types that do not apply.

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: obtain the ID via m365_contacts_list or m365_contacts_search, and pass the same folder location. It also names an exclusion — directory user IDs and People API person IDs are not valid here, use m365_users_profile instead.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it searches within a folder and filters by categories, but doesn't mention pagination, response format, or any edge cases. With annotations doing most of the work, a 3 is appropriate.

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

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

The description is a single, compact sentence that front-loads the search criteria and optional filters. No wasted words.

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 schema covers 71% of parameters and annotations cover safety, the description is mostly complete. It lacks details on pagination or return structure, but no output schema exists, so a bit more behavioral description could be useful. Yet for a search tool with good schema coverage, this is sufficient.

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

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

Schema description coverage is 71%, so the schema covers most parameters. The description adds meaning for query, folderId, and categories, which are not fully described in the schema. However, it doesn't clarify the exact match behavior for query or how folderId and parentFolderId interact, leaving some gaps.

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

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

The description clearly states the tool searches contacts by name, email, or company, with optional folder scoping and category filtering. This specific verb-resource combination distinguishes it from sibling tools like m365_contacts_list or m365_contacts_read.

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

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

The description implies when to use this tool (searching contacts) versus listing or reading, and gives context for folder and category filtering. It doesn't explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to select it appropriately among siblings.

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

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

The description adds a key behavioral trait—using empty strings or arrays to clear values—which goes beyond the annotations. Annotations already cover destructive and idempotent hints, so this extra context is valuable and not contradictory.

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

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

A single, front-loaded sentence that states the action and the key clearing behavior without waste. Every word earns its place.

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

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

Given the tool's complexity (36 parameters, nested objects, no output schema), the description is minimal. It clarifies the clearing mechanism but leaves crucial update semantics unspecified (e.g., partial update vs. full replacement). The rich schema descriptions partially offset this, but overall the description is under-specified for such a complex mutation 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 only 47%, leaving over half of parameters without descriptions. The tool description provides a general clearing rule that helps understand array/string parameters, but it doesn't compensate for the many undocumented parameters. Some schema property descriptions already mention clear behavior, so the description's contribution is moderate.

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

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

The description clearly states the tool's function with specific verb 'Update or clear' and resource 'contact fields', distinguishing it from create/delete siblings. It doesn't explicitly name alternatives but the purpose is unambiguous.

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

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

No guidance on when to use this tool versus alternatives like create or delete. The clearing behavior implies use for modifying existing contacts, but there are no explicit exclusions or conditions. Sibling tools exist but are not referenced.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false and openWorld=true, so the safety profile is covered. The description adds genuinely non-redundant context: no recursive parent creation, the returned fields (ID, name, web URL), and a recovery path for ambiguous outcomes — which matters precisely because idempotentHint=false.

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?

Four short sentences, each carrying distinct information: capability, exclusions, return shape, retry advice. Capability and scope are front-loaded with 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?

For a two-parameter, non-destructive creation tool with no output schema, the description covers capability, negative scope, return values, and failure-recovery behavior. Nothing an agent needs in order to call it or handle its result 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% and both parameters already document that name is a single folder (not a nested path) and that parentPath is a root-relative existing path defaulting to root. The description restates this constraint but adds no syntax, validation, or format 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?

Specific verb (create) plus resource (one folder) plus scope (OneDrive root or an existing parentPath). It immediately separates itself from the file siblings (m365_files_list, m365_files_read, m365_files_info, m365_files_search) which do not create anything.

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 states what it does NOT do — no file uploads, no creation of missing parent folders — and names m365_files_list as the check before retrying an uncertain creation. That is real routing guidance, though it stops short of covering other edge cases (e.g. duplicate-name handling).

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 non-destructive behavior. The description adds no further behavioral context, such as error handling or what metadata is included. It neither contradicts nor enriches the annotations.

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

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

The description is a single, short sentence with no filler words. It's highly concise and immediately readable.

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

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

Given the tool's low complexity (one parameter, no output schema), the description is sufficient. The read-only and idempotent annotations cover the behavioral contract, and the description clearly identifies the target resource. It doesn't detail the metadata fields returned, but that's acceptable for a simple metadata getter.

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

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

The schema has one parameter (itemId) with only a minimal description. The main description clarifies that the ID can refer to either a file or a folder, adding meaning that was not explicit in the schema.

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

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

The description clearly states the tool's function: retrieving metadata for a file or folder. It uses a specific verb ('Get') and resource ('file or folder metadata'), which distinguishes it from file content read (m365_files_read) and file listing (m365_files_list).

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

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

The description implies usage when metadata is needed, but it doesn't explicitly state when not to use it or mention alternatives. Sibling tools like m365_files_read and m365_files_list are not referenced, so the 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 already cover read-only, idempotent, non-destructive, and open-world behavior. The description adds important context beyond them: the listing is non-recursive, returns IDs and metadata rather than file contents, and 'top' applies across internal pages rather than to a single page.

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 definition is front-loaded and compact: it first defines the action and scope, then the return behavior, then the sibling alternatives. Every sentence earns its place by resolving a specific ambiguity an agent would otherwise face.

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

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

For a simple two-parameter read-only listing tool, the description covers the essential call context: non-recursive scope, root default, return format, pagination behavior of 'top', and sibling alternatives. Annotations and schema already carry safety and parameter details, so no important gap remains.

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 path semantics that the schema does not state: the folder listing is immediate and non-recursive, and the root is the default. It also reinforces that 'top' limits total returned children across internal pages, consistent with the schema's note that it is not page size.

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: browsing immediate files and folders in one OneDrive folder, with the root as default and explicitly non-recursive. It also distinguishes itself from m365_files_search, m365_files_info, and m365_files_read by naming the exact sibling that handles each alternative case.

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

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

It explicitly routes the agent to alternatives: use m365_files_search for matches across the drive, m365_files_info for a single item's metadata, and m365_files_read for text content. The scope of this tool, browsing one folder non-recursively, is clear enough that there is no ambiguity about when to select it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description usefully adds the text-only restriction and the 50KB default cap, but says nothing about truncation behavior or what happens when a file exceeds the cap — a meaningful gap for a read tool.

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 short sentence with zero waste; the core action is front-loaded and the constraints are compactly parenthesized.

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, so the description should clarify what comes back (raw string content? truncation indicator?) and whether exceeding maxBytes errors or truncates. For a simple two-parameter read that is otherwise well covered, these omissions leave it only adequate.

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 both parameters are fully documented in the schema, including itemId's provenance ('from list/search') and maxBytes bounds. The description adds only a restatement of the default cap, so 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?

Specific verb+resource: 'Read a file's content' with the qualifier 'text files only, max 50KB by default'. This distinguishes it implicitly from m365_files_info (metadata) and m365_files_search, though it never names those siblings.

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?

'text files only' gives an implicit when-not (binary files), but there is no explicit guidance on when to use this versus m365_files_info, m365_files_list, or m365_files_search, nor any stated prerequisite (e.g. obtaining itemId from list/search).

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond that: it scopes the return payload to metadata rather than content, and discloses that result capping happens across internal pages, which is non-obvious server behavior. It stops short of describing match semantics or empty-result behavior, 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 short sentences, zero waste, front-loaded with the capability and output scope, then alternatives, then the one non-obvious parameter caveat. Every sentence earns its place.

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

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

For a 2-parameter read-only search with rich annotations and no output schema, the description covers capability, return shape, sibling routing and the top-cap behavior. Minor gap: nothing about match semantics (e.g. whether query is substring, prefix, or relevance-ranked) or behavior on zero matches, which could affect how an agent phrases the query.

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 already states that top is "Maximum total matches to return, not page size"; the description's closing sentence largely restates that. No added meaning for the query parameter (matching syntax, tokenization, scope) beyond the schema's example. 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 and resource ("Find matching items across your OneDrive") and bounds the output ("returning IDs, paths and basic metadata, not file content"), which immediately separates it from content-read and browse tools. An agent can distinguish it from the four m365_files_* siblings 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?

Explicitly routes three alternatives: browse a known folder (m365_files_list), get item details (m365_files_info), read text content (m365_files_read). The condition selecting this tool (unknown location, name/keyword known) is implied by the contrast and is unambiguous in practice.

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

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

Annotations already indicate destructive intent and non-idempotent behavior. The description adds useful context that the delete action is not permanent but moves the message to Deleted Items, providing the agent with a fuller understanding of the operation's 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?

The description is a single, concise sentence with a useful parenthetical. Every word adds value, and it is front-loaded with the action and object.

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 single-parameter delete operation with no output schema, the description is complete. It clearly states the behavior and consequence, and annotations cover the safety profile.

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 only one parameter fully described in the schema, the description adds no additional detail about the messageId beyond what is already provided. The baseline of 3 applies as no parameter semantics are missing.

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

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

The description clearly states the action ('Delete') and object ('an email'), and the parenthetical ('moves to Deleted Items') clarifies the specific folder destination, distinguishing it from other mail operations like m365_mail_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?

The description does not explicitly state when to use this tool over alternatives such as m365_mail_move. The intent is implied from the verb 'delete' and the note about moving to Deleted Items, but no exclusions or preferred scenarios are given.

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 this as a read-only, non-destructive, idempotent operation. The description adds the expectation of counts in the output, which is a behavioral trait not covered by annotations. However, it does not disclose other behavioral details such as whether folder hierarchy is included, pagination, or performance implications. With good annotation coverage, this is sufficient for a 3.

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

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

The description is a single, front-loaded sentence that directly states the tool's function without any filler. For a simple tool with no parameters, this is appropriately concise and well-structured.

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?

In the absence of an output schema, the description should clarify what the tool returns. It says 'with counts' but does not specify counts of what (e.g., messages, unread items) or any structural details (e.g., nested folders). While annotations provide safety context, the description leaves some ambiguity about the return value shape, making it incomplete for a tool with no output schema.

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

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

The tool has zero parameters, so the schema provides complete coverage (100%). The description adds no parameter details because there are none. Following the baseline rule for 0-parameter tools, a score of 4 is appropriate.

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

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

The description clearly states the action ('List'), the resource ('all mail folders'), and adds a specific detail ('with counts'). This distinguishes it from sibling tools like m365_mail_list (which lists emails) and m365_mail_read (which reads a single email).

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

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

No guidance is provided about when to use this tool versus alternatives. The description does not mention any exclusions, such as 'use m365_mail_folders when you need folder structure, not email content.' Without this context, the agent is left to infer usage from the tool name alone.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered; the description goes further by disclosing the return shape, the 200-character preview cap, the newest-first ordering and that top caps totals across internal pages rather than page size. It stops short of noting auth requirements or rate limits, so it is strong but not exhaustive.

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

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

Three sentences, none wasted: scope first, then the constraint on arguments, then sibling routing. Front-loaded with the primary behavior and free of restated 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?

For a read-only list tool with no output schema, it supplies everything an agent needs: default folder, what is returned, preview limits, ordering, pagination cap semantics and which sibling to use instead. Annotations carry the safety profile, so no critical gap remains.

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 already explains each parameter, so the baseline is 3. The description adds real interpretive value by clarifying that top is a total cap across internal pages and that filter and search are mutually exclusive — both are easy misuse traps the schema only partially signals.

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 — browse one mail folder — plus the default (inbox), the return shape (IDs, summaries, previews up to 200 chars) and ordering (newest first within the returned set). An agent can distinguish it from m365_mail_search, m365_mail_read and m365_mail_folders 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?

Explicitly routes the agent: use m365_mail_search across folders, m365_mail_read for a body, m365_mail_folders for folder IDs. It also states an intra-tool exclusion (filter or search, not both), so both the tool choice and the argument choice 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?

The description adds no behavioral context beyond what annotations already state (readOnlyHint=false, destructiveHint=true, idempotentHint=true). It doesn't explain side effects, reversible nature, permission requirements, or whether the message must exist. With no added transparency, the description relies entirely on annotations.

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

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

The description is a single, concise sentence that immediately states the purpose. No filler words or redundant information. It is front-loaded and easily parsed.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description covers the essential function. It doesn't mention return values, but none are defined in the schema, and the annotations provide safety context. A short statement about returning a success/failure could be added, but the current description is adequate for the simple operation.

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

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

Schema description coverage is 100% with clear parameter descriptions (messageId and isRead with True/False meanings). The description itself adds no further parameter 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 clearly states the action: 'Mark an email as read or unread', using a specific verb and resource. It distinguishes itself from sibling tools like m365_mail_read (which reads email content) and m365_mail_move/delete by specifying the exact state change.

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 usage is implied by the action (changing read/unread status), but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. Sibling tools exist but no cross-references are provided.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. However, the description adds no extra behavioral context beyond what the name conveys, such as whether the move is reversible, whether the original is deleted, or any side effects like moving to trash. It does not contradict annotations, but it also does not enrich them.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately conveys the action and resource, making it easy to parse quickly.

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

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

For a simple two-parameter tool with annotations and full schema coverage, the description is minimally adequate. It lacks any mention of return values, prerequisites beyond the folderId hint, or edge cases (e.g., moving to a non-existent folder). Given the low complexity, it is not severely incomplete, but it does not go beyond the bare minimum.

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%: both messageId and folderId have descriptions, with folderId additionally referencing m365_mail_folders to list valid IDs. The description itself does not add parameter semantics, but the schema already provides sufficient meaning. Baseline of 3 applies given high 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?

The description 'Move an email to a different folder' uses a specific verb ('move') and resource ('email') and clearly distinguishes this from sibling tools like m365_mail_delete, m365_mail_send, or m365_mail_mark_read. It is concise and unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions. However, the folderId parameter schema hints at a prerequisite ('use m365_mail_folders to list'), which gives some implicit usage context. Overall, usage is implied by the name and simple description, but no explicit guidance is provided.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior not in the structured data: body truncation at 10,000 characters and the fact that attachments are noted but not downloaded — both key for an agent deciding whether this call is sufficient.

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, front-loaded with the core action and followed by the return-shape caveats. No filler or restated names.

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 what is returned (recipients, metadata, capped body) and flagging the attachment limitation. Nothing essential for a 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?

Only one parameter with 100% schema coverage, so the baseline is already satisfied. The description adds meaning by tying messageId to the tools that produce it, which is more than the schema's bare 'Email message ID' label.

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 one email by message ID') and immediately distinguishes itself from the sibling list/search tools that produce those IDs. An agent can tell this is a single-item fetch rather than a bulk or mutation operation.

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 points to m365_mail_list and m365_mail_search as the sources of the required messageId, which effectively conveys the retrieval workflow. It doesn't state any when-not conditions, but for a single-read tool the implicit 'use after you have an ID' context 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?

Annotations already declare non-readOnly, non-idempotent and non-destructive, but the description adds genuinely new behavior: the call sends immediately (no draft), returns success only with no new message ID, and repeated calls can produce duplicate replies. That duplicate-send and retry guidance is exactly the kind of side-effect disclosure 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?

Three dense sentences, front-loaded with the action, then the sibling disambiguation, then the return/retry caveat. No sentence is filler and each adds a distinct fact.

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 stating exactly what the response contains ('success only, not a draft or new message ID'). Combined with the duplicate-send warning and messageId sourcing hint, nothing an agent needs to invoke this safely 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 all three parameters are documented in the schema. The description only slightly enriches replyAll by clarifying that the extra recipients are the original message's, which is close to what the schema already says; 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 ('Send a reply to an existing email immediately') and immediately clarifies the replyAll variant. It explicitly distinguishes itself from the m365_mail_send sibling, so an agent can route correctly 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?

Names the alternative tool and the condition that selects it ('Use m365_mail_send for a new conversation'), and adds a retry rule ('check Sent Items before retrying an uncertain send'). Both the when-to-use and the when-not-to-use 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 already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real context beyond that: results are IDs and summaries rather than bodies, ordering is newest-first, and `top` caps total results across internal pages. It stops short of noting auth requirements or rate limits, 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 short sentences, front-loaded with what the tool does, followed by return shape and sibling routing. 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 two-parameter read-only search with rich annotations, the description covers purpose, return format, ordering, result capping, and alternatives. No output schema exists, yet the description already explains what comes back, so 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 coverage is 100% and the schema already documents both `query` (with a KQL example) and `top` (default 20, max 500, explicitly 'not page size'). The description's line about `top` capping totals across internal pages adds a modest amount of pagination clarity but largely restates 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 and resource ('Find emails across mailbox folders') plus the input constraint (non-empty KQL search text). An agent can immediately distinguish it from m365_mail_list and m365_mail_read 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?

Explicitly routes to alternatives: m365_mail_list when the search must be scoped to one folder, and m365_mail_read when full message content is needed rather than IDs and summaries. Both the when-to-use-this and when-to-use-something-else conditions are present.

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 non-idempotent, non-read-only, open-world behavior; the description goes further by spelling out the consequence (repeated calls send duplicates) and the mitigation. It also clarifies the return contract (success, to, subject) and the crucial semantic limit that success means submission, not delivery — none of which the annotations convey.

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

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

Four tight clauses, front-loaded with the action and immediately followed by the two highest-risk facts (no draft, duplicates on retry). No filler sentences; each clause carries decision-relevant 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, and the description compensates by stating exactly what is returned and what the success flag does and does not guarantee. Combined with the duplicate-send warning and reply-tool routing, an agent has everything needed to call this safely.

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

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

Schema description coverage is 100% and each of the 7 parameters is documented in-schema (comma-separated recipients, html flag, replyTo constraints). The description adds no syntax or format detail beyond "supplied recipients," 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?

Specific verb+resource ("Send a new email immediately") with an explicit disambiguation from drafts ("this does not create a draft") and from the reply tool. An agent can distinguish it from m365_mail_reply and any draft-creating path 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?

Names the alternative explicitly ("Use m365_mail_reply for an existing conversation") and adds a concrete retry protocol ("check Sent Items before retrying an uncertain send"). Both the selection condition and the failure-mode guidance are stated rather than 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 already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true. The description adds real value on top: it states what is returned (task ID, title, status) and gives duplicate-avoidance guidance for a non-idempotent create, which is exactly the risk the idempotentHint=false flag implies. It does not mention required permissions/scopes, 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?

Front-loaded with the core action, then the prerequisite, then the return value, then the retry/alternative guidance. Every sentence carries distinct, non-redundant information 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?

No output schema exists, but the description compensates by naming the returned fields. All five parameters are documented at 100% coverage in the schema, and the non-idempotent create risk plus sibling alternatives are covered, so an agent has everything needed to call this 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%, including the listId provenance and the UTC/ISO 8601 due-date caveat, so the schema does the heavy lifting. The description only restates the listId source (m365_tasks_lists) and adds nothing about the optional body, importance, or due fields. 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+resource ('Create a task in an existing Microsoft To Do list') and immediately disambiguates from the sibling m365_tasks_lists by clarifying that this does not create a task list. An agent can distinguish it from m365_tasks_update and m365_tasks_list 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?

Explicitly routes to m365_tasks_lists for obtaining listId, to m365_tasks_update for editing/completing, and to m365_tasks_list before retrying an uncertain creation. Both the when and the alternatives are named explicitly.

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

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

Annotations already carry destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds two things beyond them: that only a success indicator comes back ('Returns success only') and that completion is a different operation entirely. It stops short of saying whether the deleted task is recoverable or where it goes, which would be the remaining high-value detail for a destructive 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 clauses, all front-loaded: the action and its scope come first, the disambiguation second, the ID sourcing last. No sentence restates the tool name and none could be dropped without losing routing 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?

For a two-parameter destructive delete with no output schema, the description covers what the tool does, what it does not do, which sibling to use instead, and that the return value is just a success signal. Nothing an agent needs in order 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% and both schema fields already document their own provenance ('from m365_tasks_lists', 'from m365_tasks_list in that list'). The description's matching sentence largely repeats that, adding only the pairing constraint ('matching listId/taskId'), so this sits at the baseline for a fully documented two-parameter schema.

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

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

States a specific verb and resource ('Delete one existing To Do task') plus the scope ('from the specified list'), and explicitly rules out the two nearest misreadings: task completion and list deletion. An agent can distinguish it from m365_tasks_update and m365_tasks_lists 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?

Names the alternative explicitly and the condition that selects it: 'Use m365_tasks_update with status=\'completed\' to finish a task while keeping it.' It also tells the agent where to source both IDs (m365_tasks_lists and m365_tasks_list), so the caller knows the prerequisite chain.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is lifted; the description adds real value with result ordering, returned field inventory, the 500-character notes truncation, and the fact that top caps total results across internal pages rather than page size. It does not mention error behavior or permission scope, keeping it 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?

Two sentences, zero filler: the first establishes scope, ordering, and return contents; the second handles sibling routing. The core operation is front-loaded before alternatives.

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 enumerates the return fields and the truncation rule, and the truncation/paging cap ambiguity is resolved in prose. Combined with full schema coverage of all three parameters, 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% and the schema itself explains top's 'maximum total, not page size' semantics and gives an OData filter example. The description restates the top paging behavior and names the source of listId, which is modest added value rather than new meaning, 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 (list) and resource (tasks inside one Microsoft To Do list), plus ordering semantics (newest created first). An agent can distinguish it from m365_tasks_lists, m365_tasks_create, and m365_tasks_update without inspecting 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 routes the agent: use m365_tasks_lists to find list IDs, m365_tasks_create to add, m365_tasks_update to change or complete. The precondition for the required listId is spelled out, leaving no inference needed.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds the context that it lists 'your' task lists (user-specific), but does not disclose pagination, sorting, or the structure of returned data. This meets the baseline but adds limited behavioral context.

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

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

The description is a single, concise sentence that starts with the action verb and resource. There is no extraneous information, making it highly efficient and easy for an agent to parse.

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

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

This is a trivial list operation with no parameters and strong annotations. The description covers the core action and resource. However, with no output schema, a slightly richer description mentioning what fields are returned (e.g., list IDs or names) would improve completeness, though it is not critical for such a simple 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?

The input schema has zero parameters, so schema coverage is complete. With no parameters, the description does not need to explain parameter meanings, and the baseline for zero parameters is 4. The description is sufficient in this regard.

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

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

The description uses the specific verb 'List' and identifies the resource as 'Microsoft To Do task lists', which clearly indicates it returns the user's task list containers. This distinguishes it from sibling tools like m365_tasks_list which likely lists tasks themselves, though it could be more explicit about that contrast.

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

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

No usage guidance is provided. The description does not state when to use this tool versus alternatives such as m365_tasks_list, nor does it mention any prerequisites or context where this tool is the appropriate choice.

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 real context beyond annotations: omitted fields are preserved, at least one editable field is required, and completion is a status assignment rather than a delete. It also states the return payload ('success and taskId'). The one gap is that annotations declare destructiveHint=true while the description frames the tool as purely additive — it never explains what could be lost, so the destructive flag is left unexplained rather than contradicted.

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

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

Front-loaded with the core action and its partial-update rule, then prerequisites, then return value, then the sibling handoff — a sensible ordering. It is dense (five clauses in one paragraph) but 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?

No output schema exists, and the description compensates by naming the return value; it also covers ID provenance and the completion-instead-of-delete path. What it omits is the destructive side implied by annotations — whether overwriting title/due/status can lose prior values or trigger downstream effects on open-world To Do data.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by stating the 'at least one editable field required' constraint and the '=' syntax for status completion, neither of which is in the schema. Enum values for status/importance are already fully documented in the schema, so nothing further is needed there.

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 ('Change supplied fields on an existing To Do task') and immediately encodes the partial-update semantics that distinguish it from m365_tasks_create. An agent can pick this over its siblings 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 explicit alternatives and conditions: 'Set status=completed to complete it instead of deleting it' routes away from m365_tasks_delete, and 'use m365_tasks_create for a new task' routes away from create. It also says where listId and taskId come from (m365_tasks_lists, m365_tasks_list), removing the main discovery question.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: result ordering ('sorted by last update') and the non-obvious fact that 'top' caps the total across internal pages. It does not mention auth requirements or throttling, which keeps it below 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 tight sentences with zero filler: purpose and return fields first, then the sibling routing, then the exclusion. The most decision-relevant 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?

There is no output schema, but the description compensates by enumerating the returned fields, their ordering, and the paging/total-cap interaction. For a one-optional-parameter read tool with full annotation coverage, 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% and the single parameter's own description already says 'Maximum total chats to return; pages contain at most 50 chats', which is essentially what the description restates. The description reinforces the total-cap-across-pages semantics but adds no new syntax, defaults, or interaction detail.

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

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

States a specific verb and resource ('List Teams chats you participate in') and immediately enumerates the returned fields (chat IDs, topics, member names, last-updated times). It also draws an explicit boundary against the two relevant siblings and excludes channel conversations, so an agent can identify 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?

The description names both alternatives with their selecting condition: 'Use m365_teams_messages to read a chat or m365_teams_send to post to it.' It also gives a negative condition ('Channel conversations are not included'), covering when/when-not/alternatives in one sentence.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses real behavioral caveats: bodies are capped at 2,000 characters, may contain incomplete HTML, and are not guaranteed to be the full history. It also states ordering (newest first), which annotations 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?

Three tight sentences, front-loaded with what it does, followed by caveats, then the sibling routing. No sentence is redundant or restates the schema.

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

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

With no output schema, the description carries the return-shape burden and does so: sender, timestamp, content type, and explicit truncation/incompleteness limits on the body. An agent has everything needed to call it and to set expectations about the result.

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 chatId and top are already documented, including the important note that top is a total cap across internal pages rather than page size. The description adds only the 'newest first' ordering and does not restate or enrich the pagination semantics, 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 precise verb and resource ('Read messages from one Teams chat') plus scope ('newest first') and return fields ('sender, timestamp and content type'). This clearly separates it from m365_teams_chats (which yields the chatId) and m365_teams_send (which writes).

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

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

It explicitly routes the agent: 'Get chatId from m365_teams_chats' establishes the prerequisite, and 'Use m365_teams_send to post a message' names the write-side alternative. It stops short of stating when not to use it (e.g., that it reads a single chat rather than listing all chats), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, openWorld=true, but the description adds the operational consequences: sends are immediate, no draft stage exists, repeated calls can duplicate messages, and the response carries a message ID plus success flag. The duplicate/retry warning is genuinely non-obvious context beyond the idempotentHint.

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, front-loaded with the core action, then the exclusions, prerequisite source, and retry hazard in a single dense clause. No filler or restated 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?

There is no output schema, but the description discloses the return shape (message ID and success), plus the preconditions, side effects, and retry protocol. For a two-parameter send tool this is enough for an agent to call and recover 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% and both parameters are documented in the schema itself, including the plain-text/HTML caveat and the chatId provenance, so the description's restatement of the same points adds little. 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?

States a specific verb and resource ('Post a plain-text message... to an existing Teams chat') with immediate scoping, and explicitly rules out three near-miss operations: creating a chat, posting to a channel, and creating a draft. That lets an agent distinguish it from m365_teams_chats and any channel-oriented tool 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 routing to m365_teams_chats for the chatId prerequisite and to m365_teams_messages as the verification path before retrying an uncertain send. It also states the condition where a send would be wrong or risky (repeated calls duplicating messages), which is exactly the when-not guidance an agent needs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly focuses on supplemental context: the delegated User.Read.All permission and admin-consent requirement, which is real activation friction an agent should know. It omits pagination behavior for large directories, 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?

A single front-loaded sentence: purpose first, then the auth constraint in parentheses. Zero wasted words.

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

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

For a simple read-only list tool with full schema coverage and annotations, the description covers purpose and permissions, but leaves out result-volume behavior (no mention of pagination or that top caps at 500), which matters for directory listing.

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 top/filter/search are fully documented in the schema and the baseline of 3 applies. The description adds nothing about filter syntax (OData), search semantics, or result limits beyond what the schema already provides.

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

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

States a specific verb+resource: 'List users in your organization'. This clearly distinguishes it from sibling m365_users_profile (single user) and m365_contacts_people_list, though it never names those alternatives explicitly.

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

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

No when-to-use or when-not-to-use guidance. It does not say whether to use this vs. m365_users_profile for a single lookup, or vs. m365_contacts_people_list for people search. The agent must infer usage from the tool name alone.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the 'or your own' behavior (default to 'me'), but this is also present in the input schema. No additional behavioral context (e.g., auth requirements, null return behavior) is provided, which would have elevated the score.

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

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

The description is a single, front-loaded sentence with zero waste. It conveys the core action and the default behavior in minimal words, perfectly matching the conciseness ideal.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description and schema together provide sufficient context to select and invoke the tool. The lack of an explicit return-value description is a minor gap, but annotations cover safety, and the scope is clear.

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

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

The input schema has 100% coverage for the single parameter 'user', fully describing it as 'User email or ID (defaults to me)'. The description does not add further semantic detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb ('Get') and resource ('a user's manager'), with a useful qualifier 'or your own' that clarifies the 'me' default. This distinguishes it from sibling tools like m365_users_profile and m365_users_list, which serve different user-related purposes.

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

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

The description implies the tool is used to retrieve a manager relationship, but it does not explicitly state when to use it versus alternatives. For example, it doesn't mention that other profile details should use m365_users_profile, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that. It adds a behavioral nuance—defaulting to 'me' when no user is specified—which is not present in the annotations. This is useful contextual information beyond the structured metadata.

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

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

The description is a single, front-loaded sentence that conveys the action, the resource, and the default behavior with zero wasted words. It is appropriately sized for the tool's simplicity.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It tells the agent what the tool does and when the parameter can be omitted. The annotations cover safety, and the tool's purpose is self-explanatory without needing to enumerate profile fields.

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

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

The input schema fully describes the only parameter ('User email or ID (defaults to 'me')'), with 100% schema description coverage. The tool description essentially reiterates this default behavior without adding new semantic details, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('user's profile') and clearly distinguishes this tool from siblings like m365_users_list (which lists users) and m365_users_manager (which gets the manager). It also notes the default behavior when no user is specified, making the tool's scope unmistakable.

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

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

The description provides clear context for when to use this tool: to fetch a single user's profile, with the convenience of defaulting to your own profile. While it does not explicitly exclude alternatives or mention sibling tools, the context is sufficient for an agent to decide between this and the related list/manager tools.

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