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

The description adds no behavioral context beyond what the annotations already declare (readOnlyHint, idempotentHint, etc.). It does not explain what 'availability' output looks like, whether it returns per-user free/busy slots, or any details about timezone handling or response structure. With annotations present, the bar is lower, but the description fails to add any 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?

The description is a single, front-loaded sentence with no wasted words. It precisely communicates the tool's purpose without any fluff, making it highly 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?

Given the absence of an output schema, the description should explain what the caller can expect in the response (e.g., a list of busy times, availability per user). It does not, leaving a significant gap. The simple nature of the tool does not excuse the lack of return-value information, but the annotations and schema provide some 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?

The input schema fully describes all three parameters (users, startDateTime, endDateTime) with 100% coverage, so the baseline is 3. The description does not add any additional parameter semantics 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?

The description clearly states the tool's function: checking free/busy availability for users. The verb 'check' is specific, and the resource ('availability for users') is distinct from sibling tools like m365_calendar_list or m365_calendar_today, which focus on listing events rather than availability.

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 should be used when free/busy information is needed, but it provides no explicit guidance on when to prefer this over other calendar tools or any exclusions. The usage context is implied by the tool name and description but not explicitly stated.

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

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

Annotations already indicate readOnly=false, so the agent knows this is a write operation. The description adds the behavioral detail of optional Teams meeting creation, but it does not disclose other important behaviors such as whether attendees receive invitations, required permissions, or side effects of openWorldHint=true. This is adequate but not rich 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 with no redundant information. Every word earns its place, and it front-loads the core purpose. Ideal for a minimal description, though it sacrifices completeness.

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 7 parameters, no output schema, and a mutation operation, the description is far too short. It does not mention return values (e.g., created event ID), what happens when isOnline is false, or any prerequisites. The tool's complexity demands more context than offered.

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% with all 7 parameters having descriptions. The description does not add any parameter semantics beyond the schema; the mention of 'optional Teams meeting' simply reinforces isOnline, which is already described as 'Create as Teams meeting'. 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 'Create a calendar event (with optional Teams meeting)' uses a specific verb and resource, clearly distinguishing it from sibling tools like m365_calendar_list, m365_calendar_update, and m365_calendar_delete. The optional Teams meeting feature adds a distinguishing detail that separates it from other calendar tools.

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

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

No guidance is provided on when to use this tool versus alternatives such as m365_calendar_update or m365_calendar_list. The description does not mention contexts like 'use for new events' or describe any exclusions, leaving the agent without explicit selection criteria.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent is aware this is a destructive write. The description adds 'cancel/delete' which aligns with the annotations, but it does not disclose additional behavioral context such as whether attendees are notified, whether the event is permanently deleted, or any side effects. With annotations covering the safety profile, a score of 3 reflects the minimal extra 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, front-loaded sentence that is easy to parse. However, it uses the slash 'cancel/delete' which introduces slight ambiguity, and it lacks any additional detail that could be provided in a second sentence. Still, it is appropriately concise for a simple 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?

Given the tool is destructive and has no output schema, the description should provide more context about the effect, such as whether it sends cancellation notifications, if the comment is included in the cancellation message, or what happens after deletion. The description is too minimal to fully inform the agent of consequences, especially with openWorldHint=true suggesting side effects.

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

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

Schema description coverage is 100%, with both eventId and comment having clear descriptions. The tool description adds no further semantic value beyond what the schema already provides. Since the schema does the heavy lifting, a baseline 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 'Cancel/delete a calendar event' uses a clear verb and resource, distinguishing it from sibling tools like m365_calendar_list, m365_calendar_create, and m365_calendar_update. It precisely indicates the action and target, leaving no ambiguity about 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 does not provide any guidance on when to use this tool versus alternatives. It does not mention that this should be used for removing or cancelling events, nor does it exclude use cases such as updating an event instead. No alternatives or contextual use cases 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, idempotentHint=true, and destructiveHint=false. The description adds valuable context that when no range is provided, the tool returns upcoming events—something not present in 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, front-loaded sentence with no redundant wording. It efficiently communicates the primary purpose and the optional behavior.

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 simple tool with 3 optional parameters, strong annotations, and no output schema, the description covers essential behavior. It would be more complete if it explicitly named sibling tools for comparison, but current coverage is 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?

The schema has 100% description coverage for all three parameters. The description's 'or upcoming if no range' clarifies behavior when startDateTime and endDateTime are omitted, which goes beyond the schema's per-property descriptions.

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

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

The description identifies a specific verb ('List') and resource ('calendar events'), and clarifies scope via date range or upcoming default. However, it does not explicitly distinguish itself from sibling tools like m365_calendar_today or m365_calendar_week, which also list calendar events.

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 arbitrary date ranges or upcoming events, but does not explicitly state when to use this tool over alternatives. No exclusions or alternative tool names are mentioned.

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 establish this as a destructive, non-read-only operation. However, the description adds no extra behavioral context, such as whether updates are partial or full replacements, or whether special permissions are needed. It simply repeats the act of updating without disclosing anything beyond what annotations convey.

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

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

The description is a single short sentence, making it concise. However, it essentially restates the tool name and lacks substantive detail, so it is not especially valuable. It is not verbose, but also does not fully earn 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 an update operation with six parameters and no output schema, the description is too thin. It omits any mention of return values, error conditions, or usage guidance. The schema covers parameters and annotations cover safety, but the overall context remains incomplete.

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?

All six parameters are documented in the input schema with clear descriptions (100% coverage), so the schema carries the semantic burden. The tool description does not mention any parameters, but given full schema coverage, the baseline 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 tool updates an existing calendar event, identifying the action (update) and resource (calendar event). The word 'existing' signals it is not for creation, but it does not enumerate which fields can be updated or contrast with delete/list siblings, so it remains a bit generic.

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 on when to use this tool versus alternatives like create or delete. There are no usage scenarios, prerequisites, or references to sibling tools, leaving the agent to infer when this tool is appropriate.

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 label this as destructive and non-readonly; the description adds a useful scoping constraint ('top-level or direct-child'). However, it does not disclose behavioral details beyond that, such as conflict handling, reversibility, or side effects on child folders.

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 sentence, front-loaded with the core action. Every word earns its place; no filler or redundant restatement of the tool name.

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

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

Given a 4-parameter mutation tool with no output schema, this description is too minimal. It does not explain the relationship between rename and move parameters, whether they can be combined, or how to target top-level versus child folders, leaving significant gaps for the agent.

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

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

Schema coverage is only 50% and the description does not compensate. While 'rename' implies displayName and 'move' implies moveToParentFolderId, the description provides no explicit mapping or usage semantics for any parameter, leaving folderId and parentFolderId entirely unexplained.

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 specific verbs 'Rename or move' with a resource 'top-level or direct-child contact folder,' clearly distinguishing it from sibling tools like create, delete, and list operations. The scope restriction adds further clarity.

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

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

No guidance is given on when to use this tool versus alternatives or when not to use it. The phrase 'top-level or direct-child' implies a constraint but does not explain how to determine eligibility or what other tools to use for non-matching folders.

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 readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds no extra behavioral context, such as what 'full details' includes or any error conditions like contact-not-found.

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 unnecessary words. It immediately states the action and resource, making it highly scannable.

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

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

The description is minimally acceptable for a straightforward read operation. However, with no output schema, it could benefit from indicating that it returns the full contact record or that contactId is required. The existing annotations cover safety, but the description lacks details about expected output or prerequisites.

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

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

The description does not clarify the required 'contactId' parameter, which has no schema description. The optional folder parameters are already well-described in the schema, so the description adds no value beyond the schema.

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

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

The description clearly states the action ('Read') and the resource ('a contact's full details'). The singular form and the verb 'read' distinguish it from sibling tools like m365_contacts_list and 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 offers no guidance on when to use this tool versus alternatives. It does not mention that users should have a contactId or that list/search tools are more appropriate for discovery.

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?

The description adds no behavioral context beyond the annotations. It does not mention consequences of duplicate names, permissions required, or whether it creates parent directories. The annotations already indicate this is a write operation, so the description is consistent but adds no extra transparency.

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 one concise sentence, immediately front-loaded with the verb and resource. 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?

For a simple create-folder tool with two parameters and a clear schema, the description is adequate but could benefit from mentioning behavior like creating subfolders or returning folder metadata. However, the schema covers parameter details, and the operation is straightforward.

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 both parameters (name and parentPath) with clear descriptions, so the baseline is 3. The description does not add any further parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool's action ('Create') and resource ('a new folder in OneDrive'), distinguishing it from sibling tools like m365_files_list or m365_files_read. 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 provides no information about when to use this tool versus alternatives, such as prerequisites or edge cases. It simply states the action without context on when to invoke 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 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety is clear. The description adds the behavioral fact that it returns both files and folders, which is beyond the name. However, it does not disclose pagination behavior, return format, or that the path is relative to OneDrive root.

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 sentence with no redundant words. It states the core action and resource up front, and every word earns its place. It is appropriately concise.

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 and the strong schema/annotation coverage, the description is minimally viable but has gaps. It does not explain the default behavior when 'path' is omitted (e.g., lists root of OneDrive), nor does it describe the return structure (names, types, metadata). No output schema exists, so more context would be helpful.

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% description coverage: 'top' is documented as 'Max results' and 'path' as 'Folder path (e.g. Documents/Work)'. The description adds no further parameter meaning 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 uses a specific verb ('List') and identifies the resource ('files and folders in your OneDrive'). This clearly distinguishes it from sibling tools like files_read (reads content), files_info (gets metadata), and files_search (searches), which have different 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 provides no guidance on when to use this tool versus alternatives. It does not mention that this is for browsing directory contents, nor does it suggest using files_search for keyword search or files_info for single-item metadata. There is no explicit context or exclusions.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, covering the safety profile. The description adds useful constraints (text-only, 50KB default limit) but does not disclose behavioral details like truncation vs. error for oversized files or encoding handling.

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, tight sentence with the verb front-loaded. No filler or redundant explanation—every word adds value.

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 tool with rich annotations, a clear description, and full schema coverage, the definition is largely complete. It falls short only in not clarifying behavior when content exceeds maxBytes (truncation vs. failure), which is a minor gap.

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

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

Schema coverage is 100% for both parameters (itemId, maxBytes), so the baseline is 3. The description reinforces the maxBytes default and text-only constraint, but it does not add much beyond the schema for itemId; the schema already explains its origin.

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 ('Read') and resource ('file's content'), immediately clarifying the tool's function. It also distinguishes from siblings like m365_files_info (metadata) and m365_files_list (listing) by focusing on content retrieval. Constraints (text only, 50KB) further sharpen the purpose.

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

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

The description implies usage for reading text file content and notes size limitations, but it does not explicitly mention when to prefer this tool over alternatives or give exclusions beyond 'text files only.' No sibling tool is referenced, so the guidance is implicit 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety and non-mutating profile is clear. The description adds the scope 'in your OneDrive', which is useful context, but it does not disclose any additional behavioral traits such as search fields (name/content), pagination, or result ordering. Given the presence of thorough annotations, a score of 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, clear sentence that delivers the core purpose without any unnecessary words. It front-loads the action and resource, making it immediately scannable. There is no filler or redundant detail, achieving maximum conciseness for a simple 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 search tool with only two parameters and no output schema, the description is somewhat minimal. It tells what the tool does and the scope ('in your OneDrive'), but it does not explain return format, search semantics, or any limitations. While annotations cover safety and the schema covers parameters, the description alone would not fully prepare an agent for invocation without additional inference. It is adequate but with clear gaps.

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

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

The input schema provides 100% coverage with descriptions for both parameters ('Search query' and 'Max results'). The description adds no further parameter semantics beyond stating the overall purpose. Since the schema already documents the parameters fully, the baseline of 3 applies without additional value from the description.

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

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

The description clearly states the tool's function: 'Search for files in your OneDrive'. It uses a specific verb (search) and resource (files), and the location scope (OneDrive) distinguishes it from sibling tools like m365_files_list or m365_files_read. However, it does not explicitly contrast with other file tools, so it falls short of a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives such as m365_files_list or m365_mail_search. It does not mention contexts where search is preferred over list, nor any exclusions or limitations that would help an agent choose between this and sibling tools. The single sentence is purely declarative with no usage direction.

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 readOnlyHint=true and destructiveHint=false, establishing the safe, read-only nature. The description adds no further behavioral context such as pagination behavior, default result ordering, or potential rate limits. It merely restates the action, missing the opportunity to add value beyond the annotations.

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

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

The description is a single, front-loaded sentence that communicates the core function efficiently. Every word earns its place, and there is no extraneous information or repetition. It is clear and direct without being overly verbose.

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 and limited description, the tool lacks clarity about the return format or what fields are included in the email list. It also does not mention the 'top' parameter's pagination behavior, which is a meaningful operational detail. Although the context signals indicate a simple list operation, the absence of return-value documentation and usage guidance leaves the description incomplete.

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 parameter descriptions in the schema fully document 'top', 'filter', 'folder', and 'search'. The description repeats 'folder, filter, and search' but does not add new semantic details about how these parameters interact or their default values. This aligns with the baseline of 3 when schema covers parameters.

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

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

The description uses a specific verb ('List') and clearly identifies the resource ('emails from your mailbox'), making the primary purpose unambiguous. It mentions optional folder, filter, and search, which helps scope the operation. However, it does not explicitly differentiate itself from the closely related sibling tool m365_mail_search, which may also perform search-based 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 provides no guidance on when to use this tool versus alternatives such as m365_mail_read or m365_mail_search. There is no indication of appropriate use cases, exclusion criteria, or why one would choose this over sibling tools. The minimal 'list emails' phrasing leaves the user without decision support.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the behavioral detail 'including full body', which tells the agent the response will contain the email body content beyond just metadata—an important expectation for a read operation.

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 sentence, front-loaded with the action and resource, and contains no redundant or filler words. Every word earns its place, making it highly 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?

Given the tool's low complexity (one required parameter, no output schema, high annotation coverage), the description fully covers what the agent needs: it can read a specific email by ID and expect the full body. The annotation and sibling context fill any remaining gaps, making this description complete for this 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 schema already provides 100% coverage for the single parameter 'messageId' with the description 'Email message ID'. The tool description does not add any further semantics about the ID format or how to obtain it, so it meets the baseline but no more.

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 'Read' with the resource 'email' and adds scope 'by ID, including full body'. This clearly distinguishes it from sibling tools like m365_mail_list (which lists emails) and m365_mail_search (which searches), making the purpose unambiguous.

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

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

The description implies the tool is for reading a specific email when you know its ID, providing clear context for use. It does not explicitly name alternatives or state when not to use it, but the 'by ID' phrasing effectively differentiates it from list and search tools, so it meets the 'clear context' bar.

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 indicate a non-read-only mutation (readOnlyHint:false), but the description adds no additional behavioral context. It doesn't disclose whether the reply is sent immediately, if it creates a draft, or any permission requirements, offering no value beyond annotations.

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

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

The description is a single, clear sentence, which is concise and front-loaded. While it's extremely minimal, it earns its place by stating the core action, though it could be more informative.

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 tool with full schema coverage and no output schema, the description is adequate but leaves gaps about the tool's behavior, such as how the reply is sent or the effect of replyAll. It doesn't explain return behavior, but that's not required 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 coverage is 100%, with each parameter described in the schema. The description adds no parameter semantics 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 'Reply to an email' clearly states the verb and resource, and the name m365_mail_reply reinforces it. However, it doesn't explicitly distinguish from sibling tools like m365_mail_send, relying on the name for differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as having a messageId, or when to prefer reply over send, leaving the agent to infer usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the 'all folders' scope, which is a meaningful behavioral trait not conveyed by annotations. However, it does not disclose return format, result ordering, or whether searches cover message bodies vs. metadata, so it only partially enriches beyond annotations.

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

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

The description is a single, front-loaded sentence: 'Search emails across all folders.' It states the core purpose and key differentiator with zero wasted words, earning top marks for conciseness and structure.

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

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

While the annotations and schema cover safety and parameters, there is no output schema, and the description does not explain what the search returns (e.g., message summaries, counts, or full content). Given the tool's moderate complexity, this missing return-value information leaves the description minimally adequate but not fully complete.

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

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

Schema description coverage is 100%: both 'query' (supports KQL) and 'top' (max results) are described in the schema. The tool description adds no additional parameter context, so it lands at the baseline score of 3, as expected when the schema carries the full burden.

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 'Search emails across all folders' clearly states the verb (search) and resource (emails), with an explicit scope ('across all folders') that distinguishes it from sibling tools like m365_mail_list (which likely lists emails in a specific folder). This is a specific, non-tautological purpose.

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

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

The description implies a clear use case: perform a global email search across all folders, versus using m365_mail_list to browse a specific folder. While it does not explicitly name alternatives or provide exclusion criteria, the 'across all folders' phrase gives clear contextual guidance for when to select this tool over folder-scoped 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description simply restates the action without adding context such as authentication requirements or side effects, but it does not contradict the annotations. The bar is lower due to annotations, and the description adds minimal 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?

The description is a single sentence of five words, extremely concise and free of fluff. It states the core purpose without wasted words, though it is so minimal that it could be perceived as under-specified. Still, it earns its place by being efficient.

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

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

The tool is straightforward with full schema coverage and annotations. However, there is no output schema, so the description could benefit from noting that a success/failure response is returned. It also does not mention any prerequisites or post-conditions. For a simple send operation, this is minimally acceptable but not rich.

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 provides detailed descriptions for all 6 parameters, achieving 100% coverage. The description adds no parameter-specific information, so it relies entirely on the schema. Per the rubric, a score of 3 is appropriate when schema coverage is high.

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 'Send an email from your account' clearly states the action (send) and resource (email). However, it does not explicitly distinguish from sibling tools like m365_mail_reply, which also involves sending an email, so it loses a point for lack of sibling differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or reference any sibling tools, leaving the agent without context for tool selection.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context beyond the act of creation. No mention of required fields, return values, side effects, or permissions, so it fails to add value beyond annotations.

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

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

At just four words, the description is extremely concise and front-loaded with no wasteful content. However, it is slightly under-specified, so it does not earn a 5, but it is still efficient.

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

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

With five parameters, two required, and no output schema, the tool is not trivial. The description provides no additional context about how the task is created, what list it goes into, or what the caller can expect as a result. Relies entirely on schema and annotations.

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

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

Input schema has 100% description coverage for all five parameters, providing clear meanings. The description itself adds no parameter information, but baseline 3 is appropriate because the schema handles 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 'Create a new task' uses a specific verb and resource, clearly distinguishing it from sibling tools like m365_tasks_update and m365_tasks_delete. It unambiguously 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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or context in which update/delete/list would be more appropriate.

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 destructive nature is known. However, the description adds no extra behavioral context such as permanence of deletion, cascading effects, or error handling. 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, clear sentence with no wasted words. It is front-loaded and readable. However, it is almost too terse, lacking contextual phrases that would make it genuinely helpful, so it earns a 4 rather than a 5.

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 parameters and rich annotations, the description is minimally viable. It tells the agent the core action, and the schema covers parameters. But it omits information about side effects, permanence, or permissions that would be important for a destructive tool. This is a clear gap, so it gets a middle score.

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 listId and taskId have clear descriptions. The description 'Delete a task' adds no additional meaning to the parameters, leaving the schema to do the heavy lifting. This aligns with the baseline of 3.

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 'Delete a task' clearly states the action and resource, using a specific verb ('delete') and noun ('task'). It is unambiguous and distinct from sibling tools like m365_tasks_create or m365_tasks_update, though it lacks explicit scoping or additional detail.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context about required permissions or conditions. It is essentially the tool's name restated in a sentence, offering no strategic direction for the agent.

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

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

Annotations already declare readOnlyHint:true, idempotentHint:true, and destructiveHint:false, so the safety profile is well covered. The description adds minimal context by noting tasks are within a task list, but it does not disclose pagination behavior, default limits, or filtering semantics beyond what the schema already provides. With annotations in place, this is acceptable but not rich.

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 sentence with no filler words. It states the core action and scope efficiently, earning every word. There is no redundant or vague phrasing, making it highly concise.

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 operation with comprehensive annotations and full schema descriptions, the description is minimally viable but lacks usage guidance and explicit mention of return behavior or the need for a valid listId. The output schema is absent, but the operation is straightforward. A slightly richer description could improve completeness, but given the structured fields, it is 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 description coverage is 100%, with each parameter having meaningful descriptions (listId source, top max, filter syntax with an example). The tool description itself adds no parameter information, but since the schema fully documents them, a baseline of 3 is appropriate without needing to compensate.

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 tasks') and the resource ('in a task list'), which distinguishes it from sibling tools like m365_tasks_lists (which lists the lists themselves) and mutation tools such as m365_tasks_create/update/delete. The inclusion of 'task list' and the required 'listId' parameter make the scope unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites (e.g., obtaining a listId from m365_tasks_lists), and no exclusions. It simply states the action without context. The schema mentions the listId comes from m365_tasks_lists, but that is not part of the tool description itself.

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?

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds no additional behavioral context beyond the word 'Update', such as whether it performs partial or full updates, what fields get overwritten, or any side effects. It does not contradict the annotations, but it also adds zero value beyond them.

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

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

The description is a single short sentence of four words, with no redundancy or wasted content. It is appropriately sized for its simplicity, though it could be slightly more informative without losing conciseness.

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

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

Given an update mutation tool with no output schema, the description lacks essential context: it does not explain what happens after the update (e.g., return value), whether only specified fields are updated, or error conditions. The annotation destructiveHint=true suggests data loss but the description doesn't clarify this, leaving the agent under-informed.

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?

Input schema coverage is 100%, with each parameter having a clear description (e.g., 'New due date (ISO 8601)', 'Task list ID'). The description itself does not add any parameter-level meaning, so it relies fully on the schema. Baseline 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 'Update' and the resource 'existing task', unambiguously indicating what the tool does. It distinguishes from sibling tools like create and delete by the verb, but does not elaborate on scope or specific updatable fields.

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 on when to use this tool versus alternatives such as m365_tasks_create or m365_tasks_delete. The phrase 'existing task' implies a prerequisite of an existing task ID, but there is no explicit context, exclusions, or comparison to sibling tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal value beyond this, only implying the scope ('your') but not disclosing behavioral details like pagination, ordering, or what constitutes a chat. With annotations carrying the burden, a score of 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, short sentence that is front-loaded with the essential information. It contains no filler or redundant content, making it highly 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?

For a simple list tool with one optional parameter and robust annotations, the description is largely complete. The absence of an output schema is not a major issue given the tool's simplicity, but the description could have briefly noted what a chat represents or how the 'top' parameter affects results. Overall, it is adequate for the tool's complexity.

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

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

The only parameter 'top' has a schema description ('Max chats') that fully covers its meaning, giving 100% schema description coverage. The description adds no additional context about the parameter, so the baseline of 3 is correct.

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

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

The description uses a specific verb ('List') and resource ('your Teams chats'), and the possessive 'your' scopes it to the current user's chats. This clearly distinguishes it from sibling tools like m365_teams_messages, which list messages within a chat, and m365_teams_send, which sends messages.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions or scenarios where another tool would be preferred, leaving the agent to infer usage solely from the tool's name and one-line description.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context (e.g., ordering, pagination, error handling) but does not contradict the annotations.

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

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

The description is a single, focused sentence with no redundant information. It is concise and front-loaded with the essential verb and resource.

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, the strong schema, and thorough annotations, the description is functionally complete. Since there is no output schema, the phrase 'Get messages' adequately implies the return of a list. It doesn't mention pagination details, but those are covered by the schema's top parameter.

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 provides 100% coverage of the two parameters with clear descriptions ('Max messages' for top, 'Chat ID (from m365_teams_chats)' for chatId). The description itself adds no parameter details beyond the schema, so the baseline 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 'Get messages from a Teams chat' uses a specific verb ('Get') and resource ('messages'), clearly distinguishing it from sibling tools like m365_teams_send (send messages) and m365_teams_chats (list chats). It accurately 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 offers no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as obtaining a chatId from m365_teams_chats, nor any exclusions or alternative tools. The only related hint ('from m365_teams_chats') appears in the schema, not the description.

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

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

The description adds no behavioral details beyond the annotations. Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description does not mention any side effects, auth needs, rate limits, or that the message is delivered asynchronously. The agent is left unaware of any potential failure modes or response expectations.

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 unnecessary words. It is appropriately sized for a simple send operation, gets directly to the point, and is 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?

For a simple 2-parameter send operation, the description is minimally viable but lacks context on how to obtain chatId, expected return values, and potential errors. Without an output schema, the agent needs some hint about what the tool returns, which is missing. The annotations provide some safety context, but the description itself is incomplete.

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% with both chatId and message provided descriptions. The description does not add any semantic meaning beyond the schema, so it adds no value for parameter understanding. The baseline of 3 applies due to full coverage 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 'Send a message to a Teams chat' clearly identifies the action (send) and the resource (Teams chat), making it easy to distinguish from mail-related tools. However, it does not explicitly differentiate from sibling team tools like m365_teams_messages, and it could more clearly state that it targets an existing chat identified by chatId.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mention that chatId should be obtained from m365_teams_chats. It does not state exclusions or alternative tools, so the agent gets no context for choosing this over other send operations.

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

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

Annotations already cover the read-only, idempotent, and open-world hints. The description adds the specific permission requirement (User.Read.All) and admin consent note, which is useful behavioral context beyond the annotations.

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

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

The description is a single, front-loaded sentence that states the action, scope, and a critical prerequisite. Every word earns its place, with no fluff or redundancy.

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 operation with no output schema, the description is adequately complete: it states the purpose and the main requirement. The schema handles parameter details, and the absence of output schema means return format is not explicitly needed.

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

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

The input schema has 100% coverage for all three parameters (top, filter, search) with descriptions. The description itself adds no parameter details beyond what the schema already provides, 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 clearly states a specific action ('List users') and resource ('in your organization'), which distinguishes it from other M365 tools like contacts or files. It also notes a key scope element.

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

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

The description gives context on what the tool does but does not explicitly mention alternatives or when NOT to use it. It implies usage for enumeration of users, but does not reference sibling tools like m365_users_profile for single-user lookups.

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.