ms-365-mcp-server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.0.0-development
Disambiguation2/5
With 188 tools, many overlap significantly, especially calendar (list-calendar-events vs list-specific-calendar-events vs get-calendar-view vs get-specific-calendar-view, plus multiple delta/instance tools), contacts (list-outlook-contacts vs list-contact-folder-contacts, create-outlook-contact vs create-contact-in-folder), and mail reply/forward drafts vs direct sends. Even with detailed tips, an agent would struggle to reliably select the correct tool for a given intent, leading to frequent misselection.
Naming Consistency5/5
The naming pattern is consistent and predictable: verb-noun with hyphens (list-, get-, create-, update-, delete-, send-, etc.). All tools follow this convention, including specialized ones like download-bytes, create-upload-session, and parse-teams-url. No camelCase or mixed styles exist, making the naming highly consistent.
Tool Count1/5
188 tools is an extreme count for any single server, far exceeding the 50+ threshold for a score of 1. While it covers a broad suite of Microsoft 365 services, the sheer number makes it unwieldy and increases cognitive load and disambiguation difficulty. The set would be better split into multiple focused servers.
Completeness3/5
The server covers nearly all major Microsoft 365 domains (mail, calendar, contacts, OneDrive, Excel, OneNote, Planner, To Do, subscriptions) with extensive CRUD and specialized operations. However, a notable gap exists: the tool list-users is referenced in many critical tips for resolving recipient email addresses but is not actually provided, which would cause agent failures when following those instructions. Minor gaps like missing chart deletion also exist, but overall the surface is broad.
Average 3.9/5 across 159 of 188 tools scored. Lowest: 1.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description merely states 'Read-only,' which is already fully captured by the annotations (readOnlyHint: true, destructiveHint: false). It adds no additional behavioral context such as pagination, response size, or side effects. Since annotations already convey the safety profile, the description contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely short, the description is under-specified rather than concise. The two sentences provide minimal value and are not structured to highlight key usage points. It is not appropriately sized for a tool with six parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is completely inadequate for a tool with six parameters and no output schema. It does not mention return values, pagination, or any operational details. An agent would have no idea what to expect from the call or how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no information about parameters, but the schema already documents each of the six parameters thoroughly. The description does not help compensate for any gaps, but none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'The root folder of the drive' is a nominal phrase that essentially restates the tool name without a verb. It fails to specify an action like 'retrieves' or 'gets', making it a near-tautology. It also does not differentiate from siblings such as get-drive-item, which could also fetch items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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 list-folder-files or get-drive-item. The description does not mention any context, exclusions, or preferred conditions for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
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 covered. However, the description adds no behavioral context—it does not mention how the content is returned, potential large payloads (only hinted in a parameter description), or any other runtime behavior. Since the description contributes nothing beyond annotations, it scores at the floor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but it is under-specified rather than concise. It lacks essential information about the tool's action and scope. While it is front-loaded and free of fluff, it fails to 'earn its place' because it conveys almost no useful content to an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four parameters, one required, no output schema, and only basic read-only annotations, the description does not provide sufficient context. It does not explain what the HTML content represents, how it is structured, potential errors, or when it is appropriate to use. The tool's behavior is almost entirely unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description itself does not elaborate on any parameters, but the schema provides detailed descriptions for each (e.g., onenotePageId has a clear explanation of usage). Thus, the description does not need to compensate, and a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'The page's HTML content.' is a noun phrase rather than a clear verb+resource statement. It does not explicitly state the action (e.g., 'Retrieves the HTML content of a OneNote page'), and it offers no differentiation from sibling tools like list-onenote-pages or get-onenote-page. An agent would have to infer that this tool fetches HTML content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of context (e.g., needing a specific page's content vs. listing pages), no exclusions, and no mention of preference over other retrieval tools. The lack of any usage direction leaves the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Read-only', which merely repeats the readOnlyHint annotation and adds no additional behavioral context. It does not describe the return format, whether pagination is supported, or any edge cases. With annotations already covering the read-only nature, the description adds minimal value 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is concise (one sentence), it is under-specified rather than effectively concise. It does not front-load the action or clearly state the resource and operation. It reads more like a resource definition than a tool description, which hampers quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 13 parameters and no output schema, the description should provide some context about what the tool returns and how it works. The one-line description is grossly inadequate; an agent cannot determine what 'list-excel-worksheets' actually does or what the response will contain. It is incomplete for an operation of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 13 parameters, so the schema itself documents them thoroughly. The description does not mention parameters, but per the baseline rule for high schema coverage, a score of 3 is appropriate since the schema carries the semantic weight and the description adds no additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description, 'Represents a collection of worksheets associated with the workbook. Read-only.', does not explicitly state that the tool lists or retrieves worksheets. It uses a nominal phrasing ('Represents a collection') rather than a clear verb+resource construction. It also does not distinguish from sibling tools like list-excel-tables, which could be confused for a similar operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, such as 'Use this to get the worksheets in an Excel workbook'. It also provides no alternatives or exclusions, leaving the agent to infer the use case from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint: true and readOnlyHint: false, so the tool is known to mutate data. The description adds no behavioral context beyond that—it doesn't disclose that it modifies the workbook, that confirmation may be required, or any side effects. It does not contradict annotations, but it also doesn't add value over them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—one sentence—which is concise in length but not in usefulness. It omits essential context, making it under-specified rather than efficiently concise. Important information about usage and parameters is missing entirely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex operation requiring a workbook driveItem, worksheet, and a body describing chart details. Without any explanation of these requirements, the description is completely inadequate. It doesn't mention that the operation is destructive, that confirmation might be gated, or what the expected inputs are. An agent cannot call this tool correctly based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, but the tool description adds nothing about parameters. The body parameter's subproperties (type, seriesBy, sourceData) are undocumented in both the schema and the tool description. With high schema coverage, the baseline is 3, but the description fails to explain what kind of data to pass, especially for the body object, which is critical for chart creation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Creates a new chart,' which identifies the verb and resource clearly. However, it provides no context about what kind of chart, where it is created, or how it relates to the Excel workbook. It does not distinguish itself from other Excel tools in the sibling list, though no other chart-creation tool exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description says nothing about the required workbook/worksheet context or that it modifies an existing Excel file. No exclusions or alternative tool recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint=false and destructiveHint=true, and the description adds no behavioral context of its own — it doesn't clarify the mutating effect, non-idempotency, or how creation interacts with the confirm gate documented in the schema. It neither contradicts the annotations nor supplements them with any disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, satisfying conciseness and front-loading. However, the brevity simply omits content rather than compressing useful information, making it under-specified rather than efficiently comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a destructive, complex create operation with a deeply nested body (tasks, assignments, checklist, dueDateTime) and no output schema, yet the description is one sentence. It omits the relationship to a plan, the confirmation requirement, and any guidance on constructing the body, leaving an agent under-equipped for a mutation with real side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, and the schema itself documents parameters well (name, planId, orderHint). But the description contributes zero parameter information and doesn't even note that planId is needed to place the bucket in a plan. What little the description adds is a restatement of the body object present in the schema, providing no value beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action (create) and resource (plannerBucket object), so the verb+resource is present and clear. However, it is essentially a restatement of the tool name and does nothing to distinguish create-planner-bucket from close siblings like create-planner-task, update-planner-bucket, or list-plan-buckets. It is clear but barely more informative than the title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of when not to use it, and no prerequisites stated. The schema reveals that planId is required to associate the bucket with a plan, but the description never communicates this needed context, so an agent gets no help choosing or preparing a valid call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description's 'Retrieve' is consistent with that. However, it adds no further behavioral context (e.g., permissions, return format, or the two scenarios it started to explain). The incomplete sentence prevents any meaningful disclosure 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is not concise; it is a truncated fragment. It starts a second sentence about 'two scenarios' but never finishes, making it structurally incomplete. The core purpose is stated efficiently, but the dangling clause undermines conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is critically incomplete. It promises to describe two scenarios but fails to do so, which is likely essential for proper use (e.g., accessing contacts in other users' folders). With no output schema and no guidance on return values or special cases, the description is nowhere near sufficient for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all six parameters, so the schema fully documents them. The description itself mentions no parameters and adds no extra meaning. This meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'properties and relationships of a contact object', which distinguishes it from list operations like list-outlook-contacts. However, it does not explicitly contrast with any sibling, so it's clear but not fully distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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 begins to mention 'two scenarios where an app can get a contact in another user's contact folder' but is cut off, leaving the reader without any usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, indicating a mutable operation, and the description adds no additional behavioral context. It does not explain whether sorting modifies data in place, whether it is reversible, or whether confirmation is needed. The description fails to capitalize on the lower bar set by annotations to provide useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The one-sentence description is extremely concise and front-loaded, but it is under-specified rather than appropriately sized. While there is no fluff, the brevity comes at the cost of essential information required for correct usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of sorting an Excel range (multiple potential criteria, sorting in place, header handling), the description is woefully incomplete. There is no mention of return values, side effects, or required parameters beyond generic placeholders. The absence of an output schema and sparse description leaves even basics unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 86% of parameters with descriptions, but the critical 'body' parameter (which likely contains sort criteria) is only described as having an 'id' and allows additional properties. The description does not explain how to specify sort columns, order, or other options. With schema coverage high, baseline is 3, but the description adds nothing about the core sorting parameters, so a 2 is warranted as it fails to fill the domain-specific gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Sort an Excel range.' clearly states the verb (sort) and resource (Excel range), making the tool's basic purpose unambiguous. It is distinguishable from range operations like get, update, or clear by the specific action of sorting. However, it does not differentiate itself from potential sibling tools like inserting or formatting ranges, though those have distinct names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it mention any prerequisites, required parameters like the sort key or order, or preconditions such as selecting a range. An agent would have to inspect the schema and infer usage, which is insufficient for a nuanced operation like sorting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=true, which already signal this is a mutating/write operation. The description 'Create a new plannerTask' is consistent with these annotations and adds no contradiction, but it also contributes nothing beyond the annotations—no mention of side effects, required context like plan/bucket existence, confirmation behavior, or return values. Given that annotations carry the safety profile, the bare minimum is met, but the description adds no behavioral depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence and is appropriately front-loaded. However, it is under-specified rather than economically concise—it conveys the bare minimum and could benefit from a qualifying phrase about what the tool actually does with the body payload. It scores a 3 for being adequately short but not adding useful structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex creation tool with a deeply nested body schema, yet the description gives no indication of what fields are necessary to create a valid task (e.g., that body is required, whether planId or bucketId is needed). With no output schema and no description-level guidance, an agent would have to infer all requirements from the JSON schema alone. For a write operation of this complexity, the description should do far more to orient the caller.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, placing it near the high-coverage baseline of 3. The schema itself is extremely rich—the body parameter contains detailed descriptions for priority (with the 0-10 interpretation), dueDateTime (ISO 8601 format), percentComplete, and various read-only flags. The description adds nothing about parameters beyond what the schema already documents, which is acceptable at this coverage level but not exemplary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource combination: 'Create a new plannerTask.' This does identify the action (creating a planner task) and differentiates it from siblings like list-planner-tasks or delete-planner-bucket. However, it's minimal—'plannerTask' is a slightly awkward compound term and the description adds nothing beyond the name itself, offering no detail about what a planner task is or what fields are involved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. Siblings include create-todo-task, create-planner-bucket, create-planner-task-message, and update-planner-task, but the description gives no context on how to choose among them. A tool as generic as 'Create a new plannerTask' would benefit from at least a note on prerequisites (e.g., a plan or bucket must exist first).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the description adds little beyond that. It mentions the return value (created contactFolder with id), but it does not disclose side effects, permission requirements, or behavior related to the confirm parameter. Moreover, it introduces a potentially misleading capability (child creation) without clarifying the actual behavior, which is a transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences plus a tip, but the first sentence is redundant and confusing because it repeats a claim later contradicted by the tip. The tip is concise and useful, but the overall structure would benefit from removing the conflicting opening and stating the intended scope upfront.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the return value (created contactFolder with id) and a simple example, which is helpful given there is no output schema. However, it fails to clarify the exact creation scope (default vs. child) and does not explain other required parameters beyond displayName. The ambiguity about child folder creation leaves a significant gap in an agent's ability to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 75% description coverage and already documents most parameters, so the baseline is 3. The description adds a concrete body example ({ displayName: 'Family' }) which is helpful, but it does not explain how to specify a parent folder (e.g., via parentFolderId) and instead redirects that use case to a sibling. This adds some value but not comprehensive parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the verb and resource clearly ('create a new contactFolder'), but the scope is ambiguous: the first sentence claims it can create under the default folder or as a child of a specified folder, while the tip says to use create-contact-child-folder for sub-folder creation. This internal contradiction weakens the clarity of what the tool actually does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the sibling create-contact-child-folder for sub-folder creation, which is good guidance. However, the opening sentence contradicts this by implying this tool can also create child folders, so the when-to-use guidance is muddy. The tip partially clarifies, but the conflict reduces confidence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds no extra behavioral context—no mention of pagination (though fetchAllPages exists), response structure, or potential limitations. It fails to provide any 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, which is concise. However, it is too minimal to be well-structured; it lacks any contextual organization or flow that would help an agent parse critical information quickly. It's under-specified rather than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 7 parameters, 4 required, no output schema, and numerous sibling tools. The description is woefully incomplete—it doesn't explain what the tool returns (e.g., cell values, formulas, metadata), how to format the address parameter, or any caveats about range size. The schema covers parameter syntax but not the tool's overall behavior, leaving agents underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all parameters are described in the schema itself (e.g., driveId, address, fetchAllPages). The tool description adds no parameter-level information, so it doesn't enhance what the schema already provides. Per rubric, a baseline of 3 is appropriate given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('Excel range'), which clearly differentiates it from sibling tools like get-excel-table or get-excel-used-range. However, it doesn't specify whether the tool returns values, formatting, or the range object itself, making the purpose slightly vague but still understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 get-excel-used-range or get-excel-table. There are no usage contexts, exclusions, or conditions mentioned, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true and readOnlyHint: false, so the mutation aspect is covered. The description adds minimal behavioral context beyond that: it mentions 'Enable, configure, or disable' but does not discuss side effects, permission requirements, reversibility, or the confirm gate. The example is helpful but does not disclose consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose and runs together multiple concerns. It starts with a general statement, then dives into format specifics, and ends with a tip and example. The structure is not front-loaded with the core purpose; it mixes purpose, formatting rules, and an example without clear organization. It could be trimmed significantly without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, destructive tool with nested objects and no output schema, the description is incomplete. It does not mention the confirm parameter, error handling, required permissions, or what the response looks like. It also lacks guidance on how to use the other parameters (like workingHours, delegateMeetingMessageDeliveryOptions). The example covers only OOO, leaving other settings under-explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so most parameters are already described. The description adds crucial format requirements for date/time and time zone (short date/short time, Windows or IANA formats) that are not in the schema, and provides a full example body for Out-of-Office, significantly clarifying usage of nested objects. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool enables, configures, or disables mailbox settings, and gives specific examples of settings (date/time, time zone, OOO). It is clear what the tool does, though it does not explicitly differentiate from the read-only sibling get-mailbox-settings; the purpose is evident but not explicitly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 get-mailbox-settings is the read counterpart, nor does it state any prerequisites or exclusions. The only usage nuance is format guidance, not selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate those. However, it adds no additional behavioral context, such as potential side effects (e.g., sending invitations, modifying calendars) or prerequisites beyond the email tip. The description adds no value beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences. The first sentence clearly states the purpose, and the second is a practical tip. It is front-loaded with the core purpose and wastes no words. However, the tip, while important, is somewhat tangential to the main purpose, 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of this tool (large nested body, many optional fields, and a destructive action), the description is incomplete. It does not explain the calendarId parameter, required fields, or any response/error information. The schema covers parameter details, but the description offers no high-level usage context, such as what to set for a simple event or common pitfalls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, which is high, so the baseline is 3. The description provides no extra parameter information; it relies entirely on the schema. Since the schema already documents body and calendarId well, the description doesn't need to compensate, but it also doesn't enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create a new event in a calendar') and the resource (a user's calendar or default calendar of a Microsoft 365 group). It is specific and understandable, though it doesn't explicitly differentiate from similar sibling tools like create-calendar-event, which limits it to a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The tip about using list-users to find recipient email addresses is a prerequisite, but it does not clarify the tool's specific context (e.g., when you have a calendarId vs. the user's default calendar). No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond what annotations already provide. Since destructiveHint is true and readOnlyHint is false, the agent already knows this is destructive. The description adds no additional context about irreversibility, confirmation, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, comprising two short sentences. It front-loads the operation and adds a helpful tip, but it is sparse. It is appropriately sized for a simple delete, though it lacks useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive operation with no output schema, the description lacks details about return values, error conditions, or confirmation requirements. The schema includes a confirm parameter for destructive operations, but the description does not mention it, leaving the agent without guidance on confirmation behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all 7 parameters with descriptions (100% coverage). The description adds no parameter-specific meaning beyond what the schema provides, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'linkedResource object', and the tip adds that it removes a linked resource from a To Do task. This gives a clear purpose, though it doesn't explicitly differentiate from sibling delete tools, but the resource name does that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. There is no mention of prerequisites, exclusions, or conditions, leaving the agent to infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description 'Delete' aligns with that. However, the description adds no additional behavioral context beyond what the annotations provide. It doesn't mention side effects, required permissions, reversibility, or the confirm gate that might be mandatory. Given the annotations cover the core destructive nature, the description contributes nothing extra, earning a 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, 'Delete a todoTask object.' It's minimal and efficient with no wasted words. For a straightforward delete operation, this is appropriately sized, 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description is too sparse. It doesn't mention the confirm gate requirement (even though it's in the schema, the description doesn't point to it), nor does it provide any context about irreversible consequences or when confirmations are needed. The output schema is absent, but the description doesn't clarify return behavior either. An agent has to rely entirely on schema and annotations, which are sufficient for parameters but not for usage context. This is incomplete for a delete operation of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning all six parameters are documented in the schema with descriptions. The tool description itself provides no additional semantic meaning for the parameters. Since the schema fully describes parameters like todoTaskId and the confirm gate, the baseline 3 applies—the description doesn't need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a todoTask object.' clearly states the verb (delete) and the resource (todoTask), making the purpose unambiguous. It doesn't explicitly differentiate from sibling delete tools like delete-todo-task-list, but the resource name is specific enough to avoid confusion. A 4 is appropriate because it's clear but doesn't provide any additional context about scope or variations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 any conditions, prerequisites, or scenarios. The confirm gate behavior is described in the schema parameter, but the description itself gives no usage context or exclusions. An agent would have no idea from the description alone 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and readOnlyHint=false, but the description adds no further context about behavioral effects, such as whether the existing fill is replaced, what happens if no color is provided, or whether the confirm gate applies. It does not supplement the annotation-provided safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, stating the core action in the first sentence. However, the tip is somewhat redundant with the main sentence, and the extreme brevity sacrifices important context, such as usage alternatives and behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a potentially destructive mutation tool with many sibling formatting tools, the description is insufficient. It does not explain consequences, how it interacts with the confirm gate, or when to prefer it over other formatting tools. The agent lacks guidance on critical decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 88%, so parameters like color, address, driveId, etc. are already well-documented in the schema. The description adds no parameter-level meaning beyond what the schema 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Format an Excel range fill') and the tip clarifies that 'fill' means the background fill color. It distinguishes this from other formatting tools like format-excel-range-font and format-excel-range-border, though not explicitly by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that this should be used specifically for setting background fill color as opposed to font or border formatting, nor does it note any exclusions or prerequisites. The tip is a restatement, not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description redundantly repeats 'Read-only' and 'Nullable,' adding no new safety information. It does add some context about the output structure (roles, grantedTo, link, inheritedFrom), which is useful but not extensive. It does not mention pagination, potential large result sets, or response format beyond the field names, so behavioral disclosure is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of a short lead sentence and a tip. The lead sentence is almost tautological with the title, and the tip is appended with a lightbulb emoji but lacks clear structure (no separation of usage, output, or limitations). It is efficient but under-specified, so it does not earn a higher score for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 13 parameters, two required, and no output schema, the description should provide more context about the return shape, pagination behavior, and typical usage. It mentions some fields but does not explain how to handle large permission lists or how the parameters relate to each other. The schema covers parameter semantics, but the description leaves gaps in usage guidance and output expectations, making it incomplete for an agent to confidently use the tool in all scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so all 13 parameters are already documented in detail (e.g., $top, $skip, $filter). The tool description does not add any parameter-specific meaning beyond what the schema provides. According to the rubric, a baseline of 3 applies when the schema fully documents parameters, and the description adds no extra value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists permissions on a file or folder and mentions the types of permissions (sharing links, direct access, inherited). It identifies the resource (drive item) and the verb (list), which is sufficient to understand its purpose. However, it does not explicitly distinguish it from sibling tools like delete-drive-item-permission, though the naming and context make the distinction obvious for a listing operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 deletion or creation of permissions, nor does it state any prerequisites or conditions for use. The only contextual hint is the tip, which explains what the tool returns but not when to choose it over other permission-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 known. The description adds no behavioral context beyond the purpose—no mention of pagination, return shape, or potential large payloads. With annotations present, the bar is lower, but the description still contributes nothing about behavior beyond what the annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the purpose without verbosity. It is front-loaded with the core action. It could arguably be slightly more detailed, but it does not waste words, which earns a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters, no output schema, and many sibling list tools, the description is too minimal. It does not explain what a notebook object contains, how to handle large lists, or when to combine with other OneNote tools. The schema helps, but for a complex tool with no output schema, the description should provide more context about expected results and typical usage patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 11 parameters have detailed descriptions), so the baseline is 3. The tool description itself adds no parameter-specific meaning, but the schema covers query options like $top, $filter, and $search. The parameter descriptions are generic Graph API guidance and do not tie to notebooks specifically, but this is acceptable given high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource pair: 'Retrieve a list of notebook objects.' It is specific enough to identify the tool's primary function and distinguishes it from sibling tools like list-onenote-notebook-sections which handle sections. However, it does not elaborate on scope (e.g., user's notebooks) or provide any extra differentiating detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as list-all-onenote-sections or search tools. The description does not mention that this is for notebooks specifically or when to prefer it over other list tools. There is no mention of prerequisites or common use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, matching the read-only nature of 'retrieve'. However, the description adds no additional behavioral context beyond this. It does not mention pagination, response size, the need for selecting fields, or the possibility of large payloads. With annotations covering safety, the description is consistent but fails to add value like explaining that the tool follows OData conventions or that fetchAllPages can return huge results. It does not contradict annotations, but it is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that clearly states the core function. It is not overly verbose and is front-loaded with the action and resource. However, it omits any context that might be useful, but conciseness itself is not the issue. It earns its place, though it could slightly expand to mention the section scoping without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and the tool has 12 parameters, the description is incomplete. It does not explain what the returned page objects contain, how pagination works, or that the tool is limited to a single section. With many sibling tools, an agent cannot determine when to use this vs. list-onenote-pages. The openWorldHint suggests behavior may vary, but the description gives no additional context. The schema helps with parameters but not with overall tool behavior or usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all 12 parameters have descriptions in the schema. The tool description itself adds no parameter-level meaning, but the schema carries the burden. Per the rubric, with high coverage, a baseline of 3 is appropriate. The description does not add clarity beyond what the schema already provides, so it does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve a list of page objects from the specified section' clearly specifies the action (retrieve) and the resource (page objects within a section). It distinguishes from the sibling 'list-onenote-pages' by scoping to a section, though it does not explicitly name alternatives or contrast with them. The verb and resource are specific, but differentiation relies on the word 'section' rather than an explicit mention of when to use this tool over others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 it is for listing pages within a specific section, that users should have a section ID, or that other tools like 'list-onenote-pages' exist for broader queries. The schema includes detailed parameter descriptions but does not address tool selection context. No when/when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure, but it only says 'Authenticate with Microsoft account.' It does not mention side effects like establishing a session, whether user interaction (e.g., browser prompt) is required, or how the 'force' parameter affects behavior. The parameter is mentioned in the schema but not integrated into the tool's behavioral description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence with no wasted words. However, it lacks structured presentation of key aspects (e.g., side effects, usage), so it is very concise but not well structured for complex information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an authentication tool that likely has significant side effects and requires user interaction, the description is incomplete. It does not mention what happens after authentication, return values, or the effect of the 'force' parameter in context. Without annotations or output schema, the agent lacks essential context to predict outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete documentation for the single 'force' parameter (coverage 100%), so the description does not need to add parameter details. It adds no extra meaning beyond the schema, aligning with the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Authenticate with Microsoft account' clearly states the verb (authenticate) and resource (Microsoft account). It distinguishes from siblings like verify-login (which checks status) and logout (which ends session), though it does not elaborate on the specific outcome (e.g., establishing a session or obtaining tokens).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 related authentication tools such as verify-login, select-account, or remove-account. The description does not mention typical call scenarios, prerequisites, or when the 'force' parameter is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds one specific, non-obvious behavioral detail: the emailAddresses array is replaced entirely. This is valuable because it warns against partial updates. However, it does not disclose other side effects (e.g., impact on unmentioned fields) or the confirm gate, though that is covered in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a two-sentence declaration with a front-loaded purpose and a practical tip. Every word earns its place, with no fluff or redundancy. The structure is optimal for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity (nested objects, many optional fields, destructive nature), the description is minimal. It lacks guidance on when to use it, what happens on partial updates, error handling, or expected response format. The tip helps but does not make the tool complete for an agent to invoke correctly without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 80% schema description coverage, most parameters are already documented. The description adds meaning specifically for emailAddresses by clarifying its replacement semantics, which is beyond the schema. It does not add semantics for other parameters, but the schema covers them adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Update the properties of a contact object.' It distinguishes from create/delete/get by the update action, and the tool name makes the 'Outlook' scope explicit. It could be more specific about the contact type (e.g., Outlook contact) but is unambiguous enough for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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 like create-outlook-contact, delete-outlook-contact, or other update tools. It does not mention prerequisites, conditions, or which scenarios are appropriate. The only extra content is a tip about emailAddresses, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the bar is lowered. The description adds no extra behavioral context, such as whether creation overwrites existing contacts or requires specific permissions, but it doesn't contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It's appropriately concise for stating the core action, though it sacrifices useful usage detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fails to explain how the tool targets a folder beyond root—there's no folder ID parameter in the schema—and doesn't clarify the distinction from create-contact-in-folder. This ambiguity means an agent may not know how to set the intended folder.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, and the schema itself provides detailed field descriptions (e.g., displayName, emailAddresses). The tool description adds no parameter semantics, but given the coverage, this is adequate and doesn't require compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Add a contact') and resource (contact), and specifies two target locations (root Contacts folder or another contact folder). It's clear but doesn't explicitly differentiate from sibling tools like create-contact-in-folder, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus create-contact-in-folder or how to select between the root folder and another folder. There's no mention of prerequisites or the confirm gate behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 covered. The description adds context about HTML-only response bodies and extension support, which is useful. It does not contradict annotations, but adds only moderate extra behavioral detail 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and gets to the point immediately. It states purpose first, then adds the HTML format note and extensions. No waste, though it could be slightly more structured with a purpose-first approach already in place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters (1 required) and many similar siblings, the description is incomplete. It does not mention how parameters like expand, select, or timezone should be used, nor does it help the agent choose between this and get-specific-calendar-event. The read-only nature is covered by annotations, but overall context for correct invocation is thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 8 parameters are documented in the schema. The description does not add meaning to parameters beyond what schema already provides. The baseline of 3 applies because the schema carries the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource pair: 'Get the properties and relationships of the specified event object.' It also adds a useful detail (HTML-only bodies) and mentions extensions. However, it does not differentiate from similar siblings like get-specific-calendar-event or list-calendar-events, so it's clear but not distinctive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. It mentions a scenario for getting events in another user's calendar, but does not state exclusion criteria or point to a sibling. With many calendar event tools available, this lacks needed routing information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false, and the description reinforces 'Read-only' without contradiction. It adds minimal extra behavioral context, such as the return properties (columns, showHeaders, etc.), but does not describe pagination defaults or any side effects beyond the schema's fetchAllPages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, but the first sentence 'Represents a collection of tables associated with the workbook' is redundant and potentially misleading; the useful tip is not front-loaded. It could be tightened by starting with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain what the response contains. The tip does list a few properties, but it omits other common ones (e.g., id, name) and does not mention how to use select/expand. For a simple get tool it is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented, but the description adds no meaningful parameter guidance and introduces confusion by saying 'by name or ID' when only workbookTableId (an ID) is offered. It does not clarify that 'name' is not an acceptable input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The tip clearly states 'Gets a specific table by name or ID', which is specific and distinguishes it from list-excel-tables. However, the opening sentence 'Represents a collection of tables associated with the workbook' is misleading and conflicts with the 'specific table' focus, so it's not 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a specific table via the tip, but it does not explicitly mention when to choose this over list-excel-tables or other siblings. There is no exclusion context or alternative reference, so 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states the action without explaining side effects such as token invalidation, whether it affects all sessions, or if it is permanent. This lack of detail leaves an agent uncertain about the consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear clause with no unnecessary words. It is appropriately concise for a simple, parameterless action, though it could benefit from a sentence about behavior or usage context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple logout action with no parameters or output schema, the description provides the essential action but lacks context about the result (e.g., does it invalidate tokens? clear local state?). It is sufficient for basic invocation but leaves some behavioral ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers them (100% coverage). The description correctly adds no parameter information because none exist, meeting the baseline of 4 for 0-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Log out') and the resource ('Microsoft account'), making the primary purpose unambiguous. It does not explicitly differentiate from siblings like 'remove-account' or 'login', but the verb and resource are specific enough that the intent is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 'remove-account' or 'login'. It does not mention context like ending a session before switching accounts, nor does it explain differences from related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description does not need to repeat that. It adds a specific constraint—'Cannot update the default calendar's name'—which is useful behavioral information. However, it does not disclose other behavioral aspects like permission requirements, side effects (e.g., affecting events), or response format, leaving the agent to infer these from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences including the tip), which makes it concise and front-loaded with the primary action. The example body is placed in the tip, providing practical value without adding bulk. However, the tip graphic (💡 TIP:) is slightly informal but does not hurt clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—5 parameters, nested objects for body, and a rich schema—the description is overly terse. It does not explain how to construct the body beyond a trivial example, nor does it clarify the calendarId requirement or what the tool returns (no output schema). The description leaves critical information to the schema, which is adequate but not sufficient for an agent to confidently invoke the tool correctly without consulting the schema in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so most parameters are documented in the schema. The description adds a concrete example body: { name: 'New Name', color: 'lightBlue' }, which helps clarify the expected structure but does not explain any parameter that is not already described. It also lacks guidance on the calendarId parameter, though the schema provides a note about passing it under 'calendarId'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a calendar' and expands with 'Updates a calendar's properties,' which is a specific verb+resource. It distinguishes from siblings like create-calendar and delete-calendar by focusing on updating existing calendars, though it doesn't explicitly contrast with update-calendar-event or update-specific-calendar-event beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 or when not to use it. The only constraint mentioned is 'Cannot update the default calendar's name,' which is a restriction but not usage context. The description does not explain prerequisites, such as needing to fetch the calendarId first, or scenarios where creating a new calendar 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=true, so the description doesn't need to repeat that this modifies data. It adds a useful behavioral tip about not guessing email addresses, which helps avoid a common mistake. However, it doesn't disclose other behaviors like sending invitations, confirmation requirements, or side effects beyond creation. Given annotations carry the safety profile, this is adequate 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main purpose in the first sentence and a clear, actionable tip in the second. It front-loads the intended action and capabilities without excessive length. The use of 'CRITICAL' and a tip icon adds emphasis but is not overly verbose. Overall, it is well-structured and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with a large nested schema, yet the description is minimal. It doesn't indicate required fields, return values, or potential errors. However, the schema provides extensive parameter descriptions, and the annotations cover destructive behavior. The tip about recipients is helpful but not comprehensive. Given the tool's complexity, the description could do more to guide the agent, but it isn't misleading and leverages the schema sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so most parameters are already described in the schema. The description lists fields like subject, start/end times, time zone, location, body, and attendees, but doesn't add deeper meaning beyond that. It doesn't clarify required parameters (though body is required per schema), nor does it explain nested structures. This provides little added value over the schema itself, consistent with the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a calendar event with specific fields (subject, times, location, etc.) and capabilities (online meetings, recurrence). It is specific about the verb and resource. However, it does not explicitly distinguish this from the sibling 'create-specific-calendar-event', which creates an event in a specific calendar, so it doesn't fully separate from that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like 'create-specific-calendar-event'. The only guideline is the tip about using 'list-users' to find email addresses, which is a prerequisite but not a when-to-use instruction. There is no mention of which calendar this targets (default vs. specific) or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation aspect is known. The description adds a valuable behavioral detail: partial HTML fails silently, which is beyond what annotations provide. However, no other behavioral context (e.g., idempotency, rate limits) is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the primary purpose front-loaded and the critical tip as a secondary note. Efficient and well-structured, though the tip emoji is slightly informal but does not harm clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the most important caveat (full HTML requirement) and the purpose. Given the schema provides required parameters and confirm gate details, the description is minimally sufficient, but it does not explain the relationship between the body object schema and the HTML requirement, leaving ambiguity for a tool with nested object complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the body parameter as an object with page properties, but the description's tip insists body must be a full HTML document—a critical but potentially contradictory clarification. This adds value beyond the schema's 80% coverage, yet the mismatch between schema type and description content may confuse agents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new page in the specified section', identifying the verb, resource, and location. It distinguishes from sibling create-onenote-page by the section qualifier, though it does not explicitly name the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus sibling tools like create-onenote-page. The only usage hint is the HTML format tip, which addresses parameter formatting rather than tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=true) and the description's "create" claim is consistent with them — no contradiction. The description adds the uniqueness constraint and required body shape as useful behavioral context, but contributes little beyond the annotations beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and the whole text is short, but the TIP line redundantly restates "Creates a new OneNote notebook" before delivering the body and uniqueness details. The redundancy costs it a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a large nested schema and no output schema, the description is sufficient to invoke the tool correctly (creates a notebook with a displayName), but it omits response expectations, error behavior on name collision, and the confirm-gate semantics that appear in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so the schema already documents most parameters including body.displayName. The description adds a helpful shorthand (Body: { displayName: 'Notebook Name' }) that clarifies the single required field, but doesn't go beyond what the schema provides for the rest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Create a new OneNote notebook" names a specific verb and resource, making it distinguishable from siblings like create-onenote-page and create-onenote-section. However, the TIP line repeats the same purpose verbatim rather than refining the scope, so it earns points for clarity but not full distinctiveness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a practical usage note — the name must be unique across the user's notebooks — which helps the agent avoid a failed call. But it never routes to alternatives (e.g., create-onenote-section for working inside a notebook) nor states when not to use the tool, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' adds no behavioral insight beyond the structured metadata. The description does not disclose whether the deletion is permanent, any cascading effects, or the existence of the confirm gate, which is only mentioned in the schema parameter descriptions. It fails to add context that would help the agent understand the consequences beyond what annotations already state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core purpose with no unnecessary words. It is ideally sized for a simple operation, front-loading the essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward delete operation, the description is minimal but not fully comprehensive. It omits mention of the confirm gate behavior (only in schema) and any post-deletion effects. However, given the schema covers all parameters and the annotations indicate destructiveness, the description is sufficient for the agent to call the tool correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented. The description adds no additional meaning about parameters, but the schema sufficiently explains messageId and attachmentId requirements. Since the schema carries the full burden, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'mail attachment', making the purpose unambiguous. The tool name is self-explanatory and distinct from siblings like delete-mail-message, so there is no confusion about what it removes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 list-mail-attachments or add-mail-attachment. It does not mention prerequisites like retrieving the message and attachment IDs or any context like permanent deletion. There is no distinction of when this tool is appropriate versus other delete operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint: true, so the description isn't required to state that deletion is destructive. However, it adds no extra context—such as irreversibility, permission requirements, or effects on related data—beyond what the annotation provides. It neither contradicts nor enriches the behavioral understanding, earning a baseline score given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It front-loads the action without extraneous detail, which is appropriately sized for a simple deletion operation. It could never be more concise without losing completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description is minimal but not entirely inadequate. It doesn't mention that deletion is permanent, but the annotation covers destructiveHint. It also doesn't explain the confirm gate or ETag behavior, though the schema does. Given the tool's simplicity and the rich schema, it's acceptable but could benefit from one caveat about irreversibility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, thoroughly explaining the confirm gate, ETag, contactId, includeHeaders, and excludeResponse. The description adds nothing to parameter meaning—it doesn't even mention them. Baseline of 3 is appropriate because the schema carries the full semantic burden and the description doesn't need to repeat it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('a contact'), which clearly distinguishes it from sibling tools like 'update-outlook-contact' and 'create-outlook-contact'. The action is unambiguous and the tool name reinforces it, so an agent can easily infer the purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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, nor does it mention any prerequisites, such as requiring the user's explicit approval for a destructive operation or the confirm gate. There is no indication of when deletion is appropriate versus other contact operations, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=true, so it is a destructive write operation. The description adds no behavioral details beyond this, such as whether existing formatting is overwritten, whether confirmation is needed, or any permission requirements. With annotations present, the bar for additional disclosure is lower, but the description provides no extra context about the operation's effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence followed by a helpful tip. The main purpose is front-loaded, and the tip adds actionable detail without redundancy. There is no fluff, and every phrase contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a simple purpose and well-described parameters, the description is adequate. The annotations cover the destructive nature and confirm gate, and the schema covers the required parameters. However, it does not mention that formatting will overwrite existing font settings or specify any return values (though no output schema exists). It is complete enough for basic invocation but lacks a few nuanced details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 88%, so most parameters are already documented (e.g., name, size, color, underline enum). The description's tip simply lists the same properties (bold, italic, underline, size, color, font name) without offering additional meaning or examples beyond the schema. Since the schema does the heavy lifting, this score reflects that no extra value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Format an Excel range font.' The tip adds the specific font properties that can be set (bold, italic, underline, size, color, font name). While it does not explicitly contrast with sibling tools like format-excel-range-border or format-excel-range-fill, the purpose is specific enough for an agent to distinguish it based on the font focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when font formatting is needed ('Set font formatting on a range'), which provides situational context. However, it does not mention alternatives or when not to use this tool, such as when dealing with borders or fills. The guidance is implied but not explicit, so it meets the baseline for implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description repeats 'Read-only', adding little. It does disclose that the result is 'Nullable' and lists the metadata fields returned, which adds context. However, the statement 'All items contained in the drive' falsely implies it returns multiple items, which misrepresents actual behavior. With the annotation bar lowered, this partial but misleading disclosure warrants a mid-range score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise with a useful TIP section that provides actionable guidance on download alternatives. However, the opening 'All items contained in the drive' is not only misleading but also redundant given the tool name and later clarification. It could be tightened to a single clear statement of purpose without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and readOnly annotations, the description reasonably covers the key aspects: it states the metadata fields returned, guides on download alternatives for large/small files, and implies the response includes a download URL. It does not explain differences between this and other drive-item tools (e.g., get-drive-root-item), but given the openWorldHint and structured schema, it is sufficiently complete for common use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (driveId, driveItemId, expand, select, etc.) already has a detailed description. The tool description adds no additional parameter-level meaning—it does not explain parameter formats, constraints, or relationships beyond what the schema provides. Per calibration, baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'All items contained in the drive' which is misleading—this tool actually retrieves metadata for a single file/folder. The tip later clarifies 'Gets metadata for a file or folder' and lists specific fields, so the purpose becomes clear, but the contradictory opening undermines clarity and fails to immediately distinguish from listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use alternative tools for content download: for large files, call get-download-url; for small files, call download-bytes. This clearly identifies when not to use this tool for content. However, it does not discuss when to use this over other metadata-centric siblings (e.g., list-drive-item-versions), so it is not fully comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint true and readOnlyHint false, so the description is not the sole source of side-effect info. It adds that the message is saved to Sent Items and notes no request body needed. However, it doesn't mention irreversibility or what happens to the draft after sending, which would be expected given the destructive hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus a tip, all containing useful information. The primary action is front-loaded, and no filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward send operation, the description covers core requirements but omits output format, error cases (e.g., missing draft), and any post-send behavior. With no output schema, more detail on expected response or failure modes would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters described. The description reinforces that only messageId is needed and that the draft must exist, which is helpful but adds little beyond the existing parameter descriptions. Baseline is appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send an existing draft message' and enumerates the draft types (new, reply, reply-all, forward). It distinguishes from sibling mail tools by focusing on drafts, but the 'Alternatively, send a new message in a single operation' clause introduces slight ambiguity about the tool's primary scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like send-mail or create-* draft/send flows. The tip about drafting presence ('Draft must exist in Drafts folder') is a constraint, not a selection criterion. It doesn't mention when to choose 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is known. The description adds no behavioral context beyond saying 'retrieve', which aligns with the read-only annotation. It does not describe return format, pagination, or any side effects. Since it is consistent with annotations but provides no extra transparency, a score of 3 is justified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states exactly what the tool does without any fluff. It is front-loaded and every word contributes to meaning. This is an example of efficient writing, appropriately sized for a simple GET operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with annotations covering safety, schema covering all parameters, and no output schema, the description is adequate. It conveys the core action and resource type, and the existing metadata reliably informs an agent about required parameters and behavior. It does not mention the need for a plannerPlanId, but that is documented in the schema, so it is not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 6 parameters, including detailed explanations for expand, select, fetchAllPages, etc. The description itself mentions no parameters and adds no additional semantic meaning. The baseline of 3 applies because the schema carries the full burden, and the description does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'plannerplan object', making the tool's purpose unambiguous. It does not explicitly differentiate from sibling planner tools like get-planner-bucket or get-planner-task, but the resource type is distinct enough that an agent can identify it. A score of 4 is appropriate because it is specific but lacks explicit sibling comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 it is the appropriate tool for fetching a single planner plan by ID, nor does it list any prerequisites or exclusions. This leaves usage entirely to inference, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the readOnlyHint annotation: it specifies the fields returned (id, lastModifiedDateTime, lastModifiedBy, size) and how to use a version id with /versions/{id}/content to download. It also states 'Read-only' and 'Nullable', which align with annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The structure includes a brief main description and a separate TIP. The main description ('The list of previous versions of the item.') is vague and terse, while the TIP is more informative but placed separately. It is not front-loaded with the most essential clarifications, though it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with readOnlyHint and destructiveHint annotations, the description covers the core purpose, returned fields, and download workflow. With 13 parameters but 100% schema coverage, the schema handles parameter detail. The lack of an output schema is mitigated by the field enumeration in the tip. Minor gaps like pagination behaviors are addressed by parameter descriptions (e.g., top, fetchAllPages).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having detailed descriptions (e.g., top, skip, expand). The tool description does not add extra parameter semantics beyond the tip, which mentions version id usage but not a parameter. This meets the baseline for well-documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool as listing previous versions of a drive item, and the TIP clarifies it 'lists version history of a file' with specific fields. This distinguishes it from siblings that list other drive content (e.g., list-folder-files). However, the main description is fragmentary and could more explicitly state it returns version metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get-drive-item or list-drive-item-thumbnails. The tip mentions downloading a specific version but doesn't say when to call this vs other list operations. There are no exclusions or context about context-dependent usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true, and the description adds context about conflictBehavior (rename, replace, fail) and that 'replace' can overwrite an existing folder. However, it does not explicitly warn about the destructive potential or explain the confirm gate, which is only in the schema. It provides some behavioral detail beyond annotations but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with a clear primary action and a succinct TIP. It is front-loaded and every sentence provides value, with no filler or redundancy. The structure efficiently conveys the core purpose and key usage details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the complex nested body schema, the description identifies the required fields and conflict resolution options, which are the most critical for correct invocation. It does not describe return values or the confirm gate, but these are covered by the schema and annotations. For a folder-creation tool, it provides sufficient guidance for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 83% schema description coverage, the description goes further by specifying that the body must include name (string) and folder ({}) fields, which are essential for a folder creation. It also clarifies the use of @microsoft.graph.conflictBehavior, a parameter not listed in the schema properties. This adds meaningful semantics beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a OneDrive folder' with a specific verb and resource, and the TIP adds that it creates inside a specified drive item. While it doesn't explicitly contrast with sibling tools like create-onenote-page, the resource type is clear enough for an agent to select it for folder creation. It is not a tautology and effectively communicates the primary action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 mentions what to include in the body (name and folder fields) but does not state when not to use it, prerequisites, or alternative tools for related operations like file upload or renaming. The usage context is only implicit from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the destructiveHint annotation by explaining that deletion shifts remaining content and that the shift direction is controlled via the body. It doesn't mention side effects like irreversibility or the confirmation gate, but the destructive annotation already covers the core risk, and the shift behavior is a useful addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action, followed by a helpful tip. There's no redundant text, and the format makes the key information easy to find. Slightly informal due to the emoji, but that doesn't detract.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with multiple required identifiers, the description covers the main behavior and the critical shift parameter, but it doesn't address the confirmation mechanism (though it's in the schema) or provide examples for the address format. It's adequate but not exhaustive, leaving a few gaps for an agent to fill.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (88%), and the description adds meaningful semantics for the body.shift parameter by explaining the allowed values ('Up'/'Left') and that 'Up' deletes entire rows. Other parameters (driveId, address, etc.) are adequately described in the schema, so the description's extra detail for shift is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool deletes an Excel range and specifies that it shifts remaining content, which distinguishes it from a plain clear operation. It doesn't explicitly name sibling tools like clear-excel-range, but the behavior is enough to infer the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip implies the tool is for deletion with shifting, and specifically mentions using 'Up' to delete entire rows. However, it does not explicitly state when to choose this over alternative range operations (e.g., clear-excel-range) or provide exclusions, leaving the usage guidance somewhat implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 known. The description adds behavioral details beyond annotations: it excludes canceled occurrences, mentions it's a navigation property, and is nullable. These are useful despite annotations covering the core read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description has a verbose formal part that partly duplicates schema information, followed by a practical tip. It is not overly long but could be more concise by removing the academic phrasing and focusing on the actionable tip. The structure is acceptable but not tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain return value expectations, but it does not. It also lacks guidance on pagination or behavior beyond 'instances.' However, the schema covers parameters like top and fetchAllPages, so the agent can infer some behavior. Given 17 parameters and complexity, more contextual details on response shape would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description adds minimal extra semantics—only reiterating that startDateTime and endDateTime are required and in ISO format, which the schema already specifies. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists occurrences of a recurring series, and the tip explicitly says 'Expand a recurring event into individual instances within a date range.' This is a specific verb (list) and resource (instances). It does not explicitly name sibling tools for differentiation, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip provides clear when-to-use guidance: requires startDateTime and endDateTime, and is used to see all occurrences of a recurring event. It does not state when not to use or name alternatives like get-calendar-view, but gives enough context for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 context about the navigation property and the ability to scope to a specific calendar group, which is useful. However, it does not disclose behavioral details like return shape or pagination behavior, which could be relevant for a list endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and then clarifies scoping options. It is concise with no extraneous wording, though it could mention expected output in a second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with no required parameters and a rich schema, the description is adequate. It covers the main functionality and scoping, and the schema handles specific query parameters. Missing return format details are minor given the standard nature of list operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each of the 11 parameters is individually documented. The tool description does not add any parameter-specific meaning beyond what is already in the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'calendars', and specifies the scope: the user's calendars, and the ability to fetch from the default or a specific calendar group. This is specific and distinguishes the tool from event-focused siblings like 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.
Usage Guidelines2/5
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 such as get-specific-calendar-view or list-specific-calendar-events. There is no mention of exclusions, prerequisites, or preferred use cases, leaving the agent to infer its applicability from the name and resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 genuine behavioral context beyond that: the critical double-quote requirement for $search, KQL property syntax, pagination behavior via @odata.nextLink, and the advanced-query mode tied to $count. 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a dense wall of text with an emoji, ALL-CAPS warnings, five KQL examples, and an external reference URL all packed into one paragraph. While the purpose is front-loaded, the high-concern formatting warnings and example overload make it hard to scan and exceed what is needed for correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 params, KQL search syntax, pagination) and the absence of an output schema, the description covers the non-obvious essentials: search quoting rules, prop-tagged KQL fields, pagination via @odata.nextLink, and a pointer to get-mail-message for full bodies. It only omits an explicit statement of the default return shape when no folder is specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 12 parameters thoroughly, setting a baseline of 3. The description adds some complementary value — the recommended default $select field list and the reminder to use bodyPreview over body — but most parameter meaning lives in the schema's own rich descriptions rather than the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb and resource clearly: 'Get all the messages in the specified user's mailbox, or those messages in a specified folder in the mailbox.' This conveys the scope distinction, though it does not explicitly differentiate from the closely-related sibling list-mail-messages, leaving the agent to infer which is for the whole mailbox versus a folder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is useful routing guidance: 'To read the full email body, use get-mail-message with the specific message id' and a tip framing the tool as a way to 'List read search Outlook emails within a specific mail folder.' However, it never contrasts this tool with list-mail-messages (whole mailbox) or list-mail-folder-messages-delta (delta changes), so an agent could pick the wrong sibling when the folder scope is ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 a tip about priority values, which is useful domain knowledge but does not disclose behavior beyond that. It does not mention pagination, ordering, or response format, but the schema parameters (e.g., $top, fetchAllPages) cover those. With annotations present, the description adds minimal but valid context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one clear sentence plus a practical tip, with no fluff. It front-loads the purpose and keeps the tip at the end. This is appropriately concise, though a bit sparse; a score of 4 reflects its efficient structure without being overly elaborate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters) and rich schema descriptions, the description provides the essential return type ('plannerTask objects') and a helpful tip. It does not need to explain all parameters since the schema covers them. The lack of output schema is mitigated by the clear phrase 'list of plannerTask objects'. Minor gaps like default ordering or response size are acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a detailed description (e.g., $top pagination advice, $filter requirements). The description itself adds no parameter-specific meaning, only a file-level tip about priority values which is not a parameter. Thus baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Retrieve a list of plannerTask objects associated with a plannerPlan object', which specifies the verb, resource, and scope. It clearly differentiates from sibling tools like 'list-planner-tasks' by indicating the tasks are scoped to a specific plan, not all user tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 plan-scoped tasks or that 'list-planner-tasks' is for all tasks. There are no exclusions or context about prerequisites, leaving the agent to infer usage from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds two specific behavioral warnings: attendees are entirely replaced (not incrementally updated) and email addresses must not be guessed but looked up via list-users. This is valuable beyond the annotation info and directly addresses common pitfalls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a short preamble and two front-loaded warnings. Every sentence carries critical information. It is well structured for an agent to quickly grasp essential cautions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool, the description covers the two most critical gotchas (attendee replacement and email lookup). It does not mention partial vs. full update behavior or response format, but neither is required given the destructiveHint and no output schema. Overall, it is sufficiently complete for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 83% schema description coverage, the schema thoroughly documents all parameters. The description adds no top-level parameter details; the attendee warning refers to a nested body property, not the required parameters. It does not compensate for any missing schema coverage, but given high coverage, a middle score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a specific calendar event' with a specific verb and resource. It is distinct from siblings like create-specific-calendar-event or get-specific-calendar-event, but does not explicitly differentiate from the generic update-calendar-event sibling, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides parameter-level tips (e.g., use list-users for email addresses, attendee list replacement) but offers no guidance on when to choose this tool over alternatives like update-calendar-event or create-specific-calendar-event. There is no mention of selection criteria or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'check', implying a read-only operation with no side effects, but it does not mention dependencies (e.g., requires an active session) or what happens if the user is not authenticated. The description adds no detail beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the action word 'Check'. There is zero wasted wording, and it is immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description provides the essential purpose. However, it does not mention what the expected outcome is (e.g., returns a boolean or status object), which could leave an agent uncertain about how to interpret the result. Some additional detail about the return value would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema description coverage is 100% (vacuously). Since there are no parameters, the baseline is 4. The description does not need to explain parameters that don't exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Check current Microsoft authentication status' clearly states the verb 'Check' and the resource 'current Microsoft authentication status'. It distinguishes itself from sibling tools like 'login' and 'logout' by focusing on verification rather than initiating or terminating a session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 it should be used to confirm authentication before other operations, nor does it contrast with 'login' or 'logout'. The context is implied 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description's semantics ('copy', 'duplicating', 'preserving an immutable snapshot') directly conflict with annotations' destructiveHint=true. Even though the description usefully discloses async execution and the 202/Location monitor response, the rubric requires a score of 1 when the description contradicts an annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the operation, then gives a compact body example, response note, and use cases. It is efficient and scannable, though the three-item use-case list is slightly more expansive than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, mentioning '202 Accepted with a Location header pointing at a monitor URL' is helpful, but the async workflow is incomplete: it never says to poll the monitor URL, explains failure behavior, or covers body options such as childrenOnly and includeAllVersionHistory. Adequate, but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so the schema does most of the parameter documentation work. The description adds value beyond it with a concrete body example ('parentReference: { driveId: '...', id: '...' }, name?: 'New Name.xlsx'') and by connecting the 'new location and/or name' idea to the body fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Copy a drive item' and elaborates 'Asynchronously copy a file or folder to a new location and/or name.' This gives a specific verb, resource, and scope, and it is naturally distinct from sibling move, delete, and share operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete when-to-use guidance: 'Ideal for duplicating templates..., bulk file provisioning, or preserving an immutable snapshot.' It clearly sets context but does not explicitly state when not to use the tool or name alternatives, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it creates a personal calendar and provides a body example and color list, but does not describe side effects, confirmation requirements (only in schema), or permission needs. The annotations (destructiveHint) are not contradicted, but the description adds little beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, stating the main action first and a helpful tip with a body example. It is efficient with no fluff, though the informal 'TIP' style is slightly non-standard.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough for basic use (name and color) but does not clarify the full scope of the body object, read-only restrictions, or the openWorldHint behavior. Given the complex schema, it leaves some ambiguity for advanced usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers parameters extensively (75% coverage). The description adds a concrete body example and lists valid color values, but these are largely redundant with the schema's enum and descriptions, adding marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'a new calendar', with a specific body example. It is unambiguous and distinct from sibling tools like create-calendar-event or list-calendars.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool's purpose but does not provide guidance on when to use it vs alternatives, nor conditions or exclusions. It lacks context such as prerequisites, when to prefer other calendar tools, or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true and readOnlyHint: false, so the description's 'Create' is consistent. It adds no extra behavioral context beyond the annotation—no mention of side effects, confirmation requirements, or error conditions. The body example is more about parameters than behavior, so the description adds minimal value beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but redundant: the first sentence already states the purpose, and the tip repeats it ('Creates a new section in a notebook'). The body example is useful, but the tip adds no new information. The structure is acceptable but not tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with a standard destructive annotation and 80% schema coverage, the description covers the essential intent and parameters. It omits details like return value or confirmation behavior, but these are captured in the schema and annotations, so the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so baseline is 3. The description adds a concrete example for the required body parameter (displayName) and implies the notebookId is required via 'specified notebook'. This helps the agent construct valid calls, going slightly beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create'), a specific resource ('onenoteSection'), and the scope ('in the specified notebook'). It clearly distinguishes from sibling tools like create-onenote-section-page and create-onenote-notebook. The added body example reinforces the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs. alternatives. It does not mention any conditions, exclusions, or relationship to sibling tools. With over 200 sibling tools, this is a significant omission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the agent knows this is destructive. The description adds no additional behavioral context (e.g., whether deletion is permanent, if recycle bin is used, or any consequences). The 'confirm' parameter is documented in the schema, not the description, and the description does not mention the destructive nature beyond the name. Since annotations cover the destructive hint, a baseline of 3 is appropriate, but the description could add details about permanence or recovery.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, very concise and front-loaded with the core action. It is not verbose. It could include a bit more detail about usage context but achieves the goal of being concise. Given the tool's simplicity and the rich schema, a single sentence is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with two required parameters, the schema descriptions are thorough and the annotations cover the destructive nature. The description does not need to explain return values because there is no output schema. The tool is relatively simple, and the schema provides enough context for the agent to call it correctly. The only missing piece is explicit mention of when to use this vs. alternatives, but given the sibling list, the name is self-explanatory. Overall, complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. However, the schema descriptions are unusually detailed: they explain that 'driveId' and 'driveItemId' must be passed under those exact names (not 'id') and how to obtain them from the drive object. This adds value beyond the basic type and required flags. The 'confirm' parameter is well-explained with the gate behavior. The description itself adds little, but the schema carries the semantic weight, so a 4 is justified because the schema descriptions are exceptionally clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a OneDrive file'). It is distinct from sibling tools like 'delete-drive-item-permission' and 'move-rename-onedrive-item' because it focuses on deleting the file itself. However, it does not explicitly differentiate from other deletion tools in the OneDrive family, though the name itself is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It is implied that this is the tool for deleting a specific file when you have its driveId and driveItemId. No exclusions or alternative tool mentions are given, but the context of sibling tools (e.g., deleting permissions, moving files) makes the purpose relatively clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and destructiveHint. The description's 'Retrieve' is consistent with these and adds no new behavioral context such as response size or pagination hints, but it does not contradict. Since the annotations carry the safety profile, the description provides minimal incremental value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the core action and object type with no filler. It is perfectly sized and front-loaded, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema with exhaustive parameter guidance and annotations covering safety, the one-line description is adequate for a list operation. The purpose statement clarifies the return type (plannerBucket objects), and no output schema exists to require additional description. Some might argue pagination context is missing, but schema parameters (top, skip, fetchAllPages) already cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific information; all parameter meanings and usage caveats are fully documented in the schema, leaving nothing for the description to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('list of plannerBucket objects contained by a plannerPlan object'), clearly distinguishing it from single-bucket tools like get-planner-bucket or create-planner-bucket. It is unambiguous and names the exact object type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 list-plan-tasks or get-planner-bucket. Although the schema contains detailed usage tips for pagination and filtering, the description itself offers no exclusions or context for selecting this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description's 'Retrieve' aligns with a read operation. The description adds a tip about priority value semantics but discloses no further behavioral traits such as pagination, rate limits, or response characteristics. Since annotations cover safety, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: a one-sentence purpose and a complementary tip about data values. No filler or redundant phrasing. The structure is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with fully documented parameters and no output schema, the description is sufficient. It specifies the scope (assigned to a user), includes a helpful interpretation tip for priorities, and aligns with annotations. Minor omission: no mention of default pagination behavior, but that is covered in the $top parameter description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed explanations for all 11 parameters (e.g., $top, $filter, $search). The description adds no parameter-specific information beyond the schema; the priority tip is unrelated to parameters. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states a specific verb ('Retrieve') and resource ('plannertask objects assigned to a User'), which differentiates it from sibling tools like list-plan-tasks (which lists tasks in a plan) and list-planner-task-messages. The 'assigned to a User' qualifier makes 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical scenarios, or conditions under which another tool (e.g., get-planner-task or list-plan-tasks) would be more appropriate. The only extra is a hint about priority values, which is not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds the `across`-dependent behavior (merging entire range vs. each row separately), which is useful. It does not describe side effects on cell contents or reversibility, but given annotation coverage, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact—two sentences plus a tip—and the critical `across` distinction is front-loaded within the tip. No wasted words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is destructive and has no output schema, yet the description does not mention return values or what happens after merging (e.g., which cell retains data). It also doesn't address prerequisites like worksheet existence. While adequate for a simple operation, an agent might need additional details about the response or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 88%, but the description explicitly explains the `across` parameter's semantics (false merges whole range, true merges per row), which is not evident from the schema alone. It does not elaborate on other parameters, but those are path segments with clear schema descriptions, so the added value is substantial for the key parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb (merge) and resource (Excel range), and the tip clarifies that merging combines cells into one. It does not explicitly differentiate from siblings like unmerge-excel-range or other range operations, but the purpose is unambiguous enough for an agent to grasp.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip provides specific use cases ('styled headers, banner rows, and report layouts'), giving implied context for when to use the tool. However, it does not mention alternatives or explicitly state when not to use it, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's mutation nature is covered. The description adds valuable behavioral detail beyond annotations, specifically the attendee replacement behavior ('Setting attendees replaces the entire attendee list — include all attendees, not just new ones'). This is a critical side effect that could cause data loss. It also offers tips like using list-users, which contextualizes behavior. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the core purpose stated in the first sentence, followed by a compact tips section. The critical tips are highlighted with emojis and uppercase 'CRITICAL' and 'WARNING', making them stand out. There is no fluff; every sentence earns its place. It could be slightly more structured, but it is well within appropriate length and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (large nested body schema, destructive hint, no output schema), the description provides some critical context (attendee replacement) but omits other important guidance. It does not explain partial update semantics (whether sending only some properties leaves others unchanged) or the need for eventId as a path parameter, though that is in the schema. It also does not mention the confirm parameter, which is crucial for destructive operations when the confirm gate is enabled. The tip about list-users is helpful, but overall the description is not fully comprehensive for a mutation tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so most parameters are already documented in the schema. The description adds value for the attendees parameter by explaining its replacement semantics, which is not in the schema (schema only says 'The collection of attendees for the event.'). It also indirectly references the emailAddress field. This is a modest enhancement beyond the schema, but it does not address other parameters like confirm, eventId, or includeHeaders, which are explained in the schema. Baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Update the properties of the event object.' However, it does not distinguish from sibling tools like update-specific-calendar-event, which also updates a calendar event. The name 'update-calendar-event' implies a general update, but the description leaves which specific event is targeted ambiguous without reference to the eventId parameter. This is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides critical usage guidance: it warns against guessing recipient emails and instructs to use list-users, and explicitly warns that setting attendees replaces the entire list. This helps the agent avoid common mistakes. However, it does not explain when to choose this tool over alternatives like update-specific-calendar-event, nor does it mention any prerequisites or context for normal use. The guidance is useful but incomplete for full selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations flag destructiveHint=true and readOnlyHint=false, and the description adds specific behavioral details: 'Overwrites existing files without warning' and the risk of truncation with no error. It also discloses the 250MB limit and that the body travels as a tool argument. This goes beyond the annotations and gives the agent actionable warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but structurally scattered. It starts with an ambiguous sentence, then jumps into a tip block, then the overwrite warning. It's not front-loaded with a clear purpose statement, and the information is presented as a series of caveats rather than a coherent explanation. It is still concise, but the organization could be improved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key operational risks (truncation, overwrite, size) and points to the alternative for large files. However, it does not explicitly state the tool's primary function or return value, and it omits any prerequisites (e.g., authentication, permissions). Given no output schema, the agent must infer the purpose from the title and the scattered hints, which introduces ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context that is not in the schema: the truncation risk when the base64 string is cut off, the size limit, and the path format for new files. This enriches the understanding of the body and driveItemId parameters beyond their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description never explicitly states 'This tool uploads file content to a specified drive item.' It opens with an ambiguous fragment, 'The content stream, if the item represents a file,' and then provides operational tips. The purpose is inferable from the title and the tip about path format, but the description itself lacks a clear verb+resource statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to avoid this tool: it warns against using it for large files and directs the agent to create-upload-session instead. It also notes that new files use a path format, which differentiates from existing items. It does not explicitly state when to use this tool over alternatives, but the exclusion is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare destructiveHint: true, but the description describes a benign 'create preview' operation with no mention of destructive side effects. This directly contradicts the annotation. The description gives the impression of a safe, non-destructive action, which is misleading given the annotation. This is a serious inconsistency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the core action, and uses a tip to provide key details. It includes body structure and return values in a compact format, with no redundant text. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functional aspects, use case, and return values, but fails to disclose the destructive nature indicated by annotations. Without that disclosure, the agent may make an incorrect safety assessment. While the schema and output information are adequate, the destructiveHint contradiction makes the description incomplete for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), but the description adds value by specifying the body fields (page, zoom, viewer) and explaining the return values (getUrl and postUrl). It also clarifies the purpose of the body. While it doesn't detail driveId/driveItemId, those are already described in the schema. The additional viewer option (not in schema properties) is useful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Create a drive item preview') and explains the purpose: generates a short-lived embeddable preview URL for files. It differentiates from sharing tools by emphasizing previews for inline use in emails/chats. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case ('surfacing inline previews in summary emails or chat messages') and notes the URLs are short-lived and embeddable. It does not explicitly exclude alternatives like share links, but the context makes the intended scenario clear. Sufficient guidance for most agents, though not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal this is a write operation (readOnlyHint=false) and potentially destructive (destructiveHint=true). The description adds valuable behavioral detail by warning that the body must be a full HTML document and that partial HTML or plain text 'fails silently or creates malformed pages.' This goes beyond the annotations and is critical for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat wordy and repeats 'default notebook' multiple times, making it less concise than it could be. It does have a logical structure: main purpose, section targeting, notebook limitations, then a tip. But some sentences could be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what the response contains (e.g., page details, URLs). It does not. It also omits mention of the confirm parameter, which might be required given the destructiveHint annotation. For a complex operation with nested objects and a write/possible-destructive flag, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so most parameters are already described. The description adds meaningful context by detailing the sectionName query parameter (which is not present in the schema) and emphasizing that the body must be a full HTML document. However, the sectionName parameter isn't exposed in the schema, which could confuse agents about how to set it. The HTML tip is genuinely useful beyond the schema's 'content' field description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new OneNote page') and the resource ('in the default section of the default notebook'). It also mentions the sectionName parameter and the limitation to the default notebook, which helps distinguish it from related tools. However, it does not explicitly contrast with the sibling 'create-onenote-section-page', leaving some ambiguity for an agent to choose between them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: only for the current user's default notebook, and how to target different sections via the sectionName parameter. It also hints that other notebooks require a different approach ('you can create pages in a specified section'). However, it does not name the alternative tool or enumerate when-not-to-use scenarios, so it's not fully comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds a crucial detail that the deletion is permanent and irreversible, which is not redundant. It does not contradict annotations. The description also does not mention potential side effects like cascading deletions, but given the annotations, the added permanence tip is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single declarative sentence plus a short tip. The main purpose is front-loaded, and every word earns its place with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward destructive operation with annotations covering safety and a schema fully detailing parameters. However, it lacks usage guidance (when to delete versus other actions), which is a notable gap for an agent selecting among many OneNote-related tools. The lack of an output schema is acceptable since it is a delete operation, but the missing usage context prevents a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with all five parameters (confirm, If-Match, onenotePageId, includeHeaders, excludeResponse) described. The description adds no parameter-level information, so it neither compensates nor detracts. Baseline of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Delete a OneNote page.' The tip adds that it is permanent and cannot be undone, which further clarifies the exact intent. It is distinct from other sibling tools that target different resources (e.g., delete-calendar, delete-onedrive-file).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it mention any prerequisites or context for deletion. There is no reference to other OneNote operations (like moving a page or creating a page) that an agent might consider instead. The tool name and schema imply usage, but explicit guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, indicating a mutating operation. The description adds that it sets one border side, which is a useful behavioral detail, but it doesn't mention side effects on existing borders, reversal, or permission requirements. The description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by a practical tip. There is no wasted text, and the tip is directly relevant to the tool's main concept of side selection. It earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, some required, the description covers the most critical nuance (sideIndex) and how to compose multiple calls. The schema handles the rest. There is no output schema, so return value explanation isn't needed. However, given the destructive annotation, it could have mentioned the confirm gate, but that is covered in the confirm parameter description, so it's acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 89%, so most parameters already have descriptions. The description adds value by explicitly listing the valid values for sideIndex (EdgeTop, EdgeBottom, etc.) and explaining how to use it for multiple sides. This goes beyond the schema's generic 'Value for the 'sideIndex' path segment.' The body parameters (color, style, weight) are well-covered in the schema, so no need to repeat.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Format an Excel range border' which clearly identifies the verb and resource. It distinguishes from sibling formatting tools (fill, font) by specifying 'border', and the tip clarifies it sets one border side. However, it doesn't explicitly state that it sets the style, color, and weight of that side, which would make it even more precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives usage guidance on how to outline all four edges by calling once per side, and explains the sideIndex parameter selects the side. However, it does not mention alternatives like format-excel-range or when to use this tool versus those siblings. There is no explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read. The description adds valuable behavioral context by noting that only a subset of properties is returned by default and that $select is required for additional properties. It also discloses the extension capability. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that starts with the core action and then elaborates on default properties and usage. It is informative without being overly verbose, though the final sentence about Entra ID customers is somewhat tangential and could be trimmed. The structure is logical and easy to follow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only GET operation with no required parameters, the description covers the essential behavior: default property subset, $select usage, and extension support. It does not describe the response format, but since there is no output schema, this is a minor gap given the simplicity of the operation. The information is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter well-documented in the schema. The description does not add further meaning to the parameters; it only explains the $select parameter's usage indirectly. Since the schema handles parameter documentation, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the properties and relationships of a user object, and the tool name narrows it to the current user. It mentions the ability to get custom properties and extension data, which adds specificity. However, it does not explicitly differentiate from the sibling tool get-my-profile, leaving some ambiguity about when one is preferred over the other.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the $select parameter to request non-default properties and mentions extensions support, but it does not provide guidance on when to use this tool versus alternatives like get-my-profile or other user-related operations. There is no explicit 'use this instead of X' direction, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 no further behavioral traits, such as pagination behavior, output size, or response format. With annotations present, the description's minimal disclosure is acceptable but does not exceed the baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately states the action and resource. No wasted words; the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions 'for a target User, Group, or Site' but provides no parameter or instruction on how to specify that target—none of the 11 parameters appear to accept a user/group/site identifier. This ambiguity could confuse an agent about how to invoke the tool correctly. While the tool may operate on a pre-selected context, this is not stated, leaving a gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each of the 11 parameters thoroughly documented (e.g., top, skip, count, expand, filter). The description contributes no additional parameter meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retrieve') and resource ('list of Drive resources') with a clear scope ('for a target User, Group, or Site'). This clearly distinguishes the tool from siblings like get-drive-item, which fetches a single drive, and list-folder-files, which lists files within a drive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context about the target scope but does not offer explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like get-drive-item or list-folder-files. Usage is implied (list drives) but no exclusions or routing hints are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, signaling a write operation. The description adds no extra behavioral context (e.g., what happens to existing properties, whether changes are reversible). It's consistent but doesn't go 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The main purpose is front-loaded, and the tip is immediately useful. It's concise and structured for quick comprehension without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex body schema with many properties, the description plus the schema covers what an agent needs: required fields are clear, and the tip provides a practical workflow. The only minor gap is not explicitly stating which properties are non-updatable (e.g., isHidden is creation-only), but that's already conveyed in the schema property descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (80%), and the parameter descriptions are rich—especially mailFolderId, which clarifies naming convention and origin. The tip further highlights displayName as a key property for renaming, adding semantic value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update the properties of mailfolder object,' which identifies the verb and resource. The tip adds a concrete use case (renaming via displayName). However, it doesn't explicitly distinguish itself from sibling update tools like update-calendar-event or update-mail-rule, though the resource is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip advises using list-mail-folders to find the folder ID, which is a helpful prerequisite. It also implies this tool is for renaming or updating folder properties. However, it doesn't explicitly state when NOT to use it (e.g., use create-mail-folder for new folders, delete-mail-folder for deletion) or compare with other update tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=false and destructiveHint=true, indicating this is a mutating operation. The description does not add behavioral context beyond that, such as confirming that rows are appended to the end of the table, that it does not modify existing rows, or any side effects like overwriting data if the table changes. With no additional context, an agent knows it is destructive but not the precise behavior, which is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, using a single line for the core action and a well-formatted tip that provides the essential body example. It is front-loaded with the primary purpose, and every element earns its place: the action, the body template, and the column-count constraint. There is no verbose or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (nested body, 4 required parameters) and no output schema, the description adequately covers the key usage: how to structure the values array and the column constraint. However, it does not mention what happens after execution (e.g., returns the added rows) or the confirm gate behavior (though confirm is documented in the schema). This is acceptable for a simple tool, but a mention of the append operation's effect would have made it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers most parameters (86% coverage), but the description adds crucial semantics for the 'body' parameter by showing the exact structure: an array of arrays where each inner array is a row. It also clarifies the constraint that values must match the number of columns. This goes beyond the schema's terse description of 'values' and helps the agent construct a correct payload.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Add Excel table rows.' This clearly distinguishes it from sibling tools like list-excel-table-rows, update-excel-table-row, and delete-excel-table-row. The added tip reinforces the action by showing an example of the body payload, so an agent can immediately grasp the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives such as update-excel-table-row or delete-excel-table-row. The purpose is implied by the name, but there is no explicit 'use this when you need to append rows' or 'use this instead of update for new rows.' This leaves some ambiguity for an agent choosing among the Excel table row operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: annotations mark destructiveHint=true, yet the description says 'Create' which is a non-destructive operation. No additional behavioral context is provided beyond what the annotations already state (readOnlyHint=false, destructiveHint=true). The description does not mention side effects, reversibility, or confirmation requirements, and the contradiction makes it misleading. Flagging as annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence clearly states the purpose, followed by a tip with emoji that contains the body format, parent discovery, and return ID usage. It is moderately long but every sentence carries useful information. The tip could be more integrated, but the structure is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-object schema with five parameters, the description covers the essential usage: how to format the body, how to obtain the parent ID, and how to use the returned folder's ID with other tools. It omits mention of the confirm gate (present in schema) but that is already documented in the parameter description. Overall, the agent has enough to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds valuable semantics beyond the schema: it gives an explicit body example '{ displayName: 'Sub-folder name' }' and tells the agent to use 'list-contact-folders' to discover the parent ID. This compensates for the schema's generic descriptions and provides practical guidance for the required parameters (body and contactFolderId).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Create' and the resource 'contactFolder' as a child of a specified folder or the user's default folder. It distinguishes itself from the sibling 'create-contact-folder' by emphasizing 'child' and 'sub-folder', making its scope unambiguous. The purpose is clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete usage instruction: 'Use list-contact-folders to discover the parent id.' It also covers two scenarios (under specified folder or default folder). However, it does not explicitly contrast with the root-folder creation tool 'create-contact-folder', relying on implication rather than stating when not to use this tool. This is a minor gap but the provided guidance is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the description does not carry the full safety burden. It adds behavioral context such as uniqueness and case sensitivity, which are beyond annotations. However, it does not explain side effects, permission requirements, or the result of creation, leaving gaps that annotations only partially cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise and front-loads the main action. The tip section repeats the action but also provides essential parameter details (color mapping, uniqueness) that are not redundant. There is minor redundancy between the first sentence and the tip, but overall it is efficient and well-structured with a clear format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested body schema, no output schema, and annotations already indicate it is a write operation. The description explains required parameters and constraints, but does not mention authentication prerequisites, potential confirmation requirements (though the schema documents the confirm parameter), or what the response contains. It is adequate but not exhaustive for an agent that might need to handle responses or understand side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the input schema by mapping color preset values to human-readable names and emphasizing displayName uniqueness and case sensitivity. With schema coverage at 75%, the description compensates for the undocumented 'color' parameter and enriches understanding of 'body' fields, which is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (create) with a clear resource (outlookCategory object) and scope (user's master list of categories). It is not a tautology and clearly distinguishes from sibling tools like list-outlook-categories by its verb. The addition of uniqueness and case-sensitivity constraints further clarifies the object's semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it creates a category, but it does not explicitly mention when to use this tool versus alternatives, nor does it provide exclusions or preconditions. The note about case sensitivity is a usage detail, but there is no guidance on when to prefer this over other category-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 covered. The description adds the useful context that any calendar can be addressed (openWorldHint), but it does not disclose additional behaviors such as response format, error cases, or pagination. Given the annotations, the description provides modest added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no fluff. The core purpose is front-loaded, and the second sentence adds a clarifying scope detail. Every word contributes to understanding what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with full schema coverage and safety annotations, the description covers the essential purpose and scope. It does not discuss return formats or edge cases, but the absence of an output schema and the read-only nature reduce the need for extensive detail. A slight gap is the lack of explicit usage differentiation from sibling tools, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each parameter. The description only restates that the tool is 'addressed by calendar ID and event ID', which adds no new meaning beyond the schema's explicit descriptions. No parameter-specific guidance is provided beyond what the schema already contains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get a single event'), the resource (calendar events), and the addressing method (calendar ID and event ID). It also explicitly notes that any calendar, including the default, can be addressed, which distinguishes it from generic 'get-calendar-event' tools that might assume the default calendar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the need for both calendar ID and event ID, but it does not explicitly state when to choose this tool over alternatives like 'list-specific-calendar-events' or 'get-calendar-view'. No exclusions or alternative conditions are mentioned, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive (destructiveHint: true), so the description does not need to reiterate that. It adds useful behavior details: inserts blank cells at the given range and shifts existing content. It does not mention side effects like formatting or undo, but given annotation coverage, it provides sufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences plus a tip. It is front-loaded with the main action and immediately provides the key parameter direction. There is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema and multiple path parameters, the description is lean but adequate. It explains the core effect and gives a tip for the shift parameter. It does not discuss response format, confirmation requirements, or error cases, but these are not critical given the schema and annotations. It could be slightly more thorough about what 'range' means in terms of the address parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all parameters with high coverage (88%). The description adds specific guidance for the 'shift' parameter by showing valid values ('Down' or 'Right') and their effect, which is not present in the schema. This enhances parameter understanding beyond the basic type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: inserting blank cells at the given range and shifting existing content. It distinguishes from siblings like delete-excel-range or clear-excel-range by explicitly describing the insertion-and-shift behavior. The verb 'insert' is specific, and the tip clarifies the exact effect, though it does not mention the address parameter explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives one practical usage hint: using 'Down' to insert rows above existing data. However, it does not explain when to choose this tool over alternatives like delete-excel-range or clear-excel-range, nor does it mention any prerequisites or context. The guidance is minimal and focuses on the shift direction rather than overall usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 further behavioral context such as pagination limits, rate limits, or error scenarios. It is consistent with annotations but adds minimal 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without extraneous detail. Every word earns its place, making it concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity and rich schema (which covers pagination and parameter behavior), the description is complete enough for an agent to decide to call the tool. It clearly states the purpose and scope, though it doesn't mention edge cases like invalid notebook IDs or response size warnings (which the schema partially covers).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 12 parameters are well-documented in the input schema itself. The description adds no parameter-specific details, which is acceptable given the high schema coverage. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve), the resource (list of onenoteSection objects), and the scope (from the specified notebook). It is specific enough to distinguish from sibling tools like list-onenote-notebooks (which lists notebooks) and list-all-onenote-sections (which lists all sections across notebooks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('from the specified notebook') but does not explicitly mention when to use this tool over alternatives like list-all-onenote-sections. It lacks explicit 'when not to use' guidance or references to sibling tools, leaving the agent to infer from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds that certain fields (subject, body, recipients) are only editable for drafts, which is useful nuance. It does not mention other side effects like confirmation requirements or authorization needs, but the schema covers the confirm parameter. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-structured sentence that front-loads the action and resource, then lists examples. No redundant terms or vague filler. Efficiently conveys the core purpose without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has complex nested objects and many parameters, but the description gives enough to understand what it does and what fields are relevant. It lacks explicit details on limitations (e.g., sent messages cannot have body/recipients changed, requiring draft status) and does not mention the return format, though no output schema exists. For a mutation tool, it is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents most parameters. The description adds semantic examples (isRead, flag, categories, importance) that clarify what kind of updates are typical, but it does not explain the structure of the body object beyond that. It adds modest value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('update an existing Outlook email message by its message ID') and lists concrete examples of what can be changed (read status, flag, categories, importance, draft content). This clearly distinguishes it from creation, sending, or deletion tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool is appropriate (updating existing messages) and implies it is not for creation or sending. It does not explicitly name alternatives or state when-not-to-use, but the enumerated use cases (marking read/unread, flagging, editing drafts) give an agent enough to select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint false, destructiveHint true, and openWorldHint true, which already inform the agent about mutation and flexibility. The description adds the valuable clarification 'does not send' — a behavioral guarantee beyond the annotations. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but redundant: the first sentence and the tip both repeat 'Create a forward draft.' The tip could be merged into a single sentence without losing meaning. It is not poorly structured, but it wastes a little space with repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema provides detailed parameter descriptions, including the requirement for messageId. However, the description does not mention that a forward requires an original message or that the body field structures the forward content. For a tool with nested objects and 5 parameters, the description relies heavily on the schema, which is mostly sufficient but lacks high-level context about the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents most parameters (messageId, confirm, etc.). The description adds no parameter-specific guidance. Per the rubric, with high schema coverage the baseline is 3, and there is no additional value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Create a forward draft') and immediately clarifies the critical distinction that it does not send. This differentiates it from siblings like send-mail, forward-mail-message, and create-reply-draft. The reader instantly knows what the tool does and why it exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear usage context: 'Useful when user wants to review before sending.' This tells the agent when to prefer this tool over a direct send. It does not explicitly name alternatives, but the hint implies the alternative (sending immediately) and the condition is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral side effects: deleting an organizer's event sends a cancellation message to attendees. It also explains the cascading behavior for seriesMaster. Annotations already mark destructiveHint true, so the destructive nature is known, but the description adds specific consequences that an agent needs to anticipate. It does not mention the confirm gate, but the schema documents that parameter, so this is adequately covered elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the core action is stated first, followed by a relevant behavioral note, and a tip for recurring events. No redundant sentences. The tip is valuable and earns its place. Slightly longer than the minimum, but each sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (reacting to series/instance behavior and meeting cancellation), the description covers the critical behavioral nuances. The schema handles parameter semantics, and output schema is absent so no return info is expected. The description could have mentioned the confirm gate, but that is documented in the schema, so completeness is acceptable. It is adequate for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented in the input schema. The description adds no parameter-specific information beyond what the schema provides; it only touches on eventId interpretation implicitly via the recurring-event tip. Since the schema carries the full parameter documentation, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Removes') and resource ('specified event from the containing calendar'), and it implicitly distinguishes from sibling cancel-calendar-event by noting that deleting the organizer's event sends a cancellation message. However, it does not explicitly name or contrast with cancel-calendar-event or delete-specific-calendar-event, leaving some differentiation to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete usage guideline for recurring events: it explains that deleting a seriesMaster deletes all occurrences and directs to delete a specific instance ID from list-calendar-event-instances for a single occurrence. This gives a when-to-use alternative. It stops short of explicitly recommending this tool over cancel-calendar-event for any scenario, but the recurring-event guidance is practical and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the description adds value by explaining the empty-collection return case and detailing the return structure (id, classifyAs, senderEmailAddress). It also clarifies the semantic effect on message classification, which is beyond the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the core purpose in the first sentence and a detailed tip that adds useful specifics without being verbose. The structure is well-organized, though the tip slightly overlaps with the first paragraph in explaining the concept.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the comprehensive schema and annotations, the description completes the picture by specifying the return object structure and the empty-collection behavior. It does not cover every edge case (e.g., pagination details are in schema), but it is sufficient for an agent to call the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides thorough descriptions for all 11 parameters (100% coverage), so the description does not need to elaborate on parameter usage. The tool description does not add parameter-specific meaning beyond what the schema offers, which aligns with the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get the overrides') and the resource (focused inbox overrides), and explains what an override is. It distinguishes itself from sibling tools like create/update/delete by focusing on retrieval. The mention that each override corresponds to an SMTP address adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case (checking which overrides exist) and notes the initial empty state, but it does not explicitly mention alternatives or when not to use it. While siblings for mutation are obvious from their names, the tool lacks direct guidance on when to choose it over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint: true and destructiveHint: false, and the description's 'Get' operation is consistent (no contradiction). Beyond annotations, the description adds a valuable behavioral detail: the $filter limitation (only startswith() supported for this endpoint) and the $search alternative, which is non-obvious Graph API behavior an agent would not infer from the schema. Pagination behavior is referenced implicitly through parameters but not described in the tool text, though annotations carry the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in the first sentence, and the tip is useful. However, the sentence 'There are two scenarios where an app can get contacts in another user's contact folder:' is clearly truncated—it introduces content that never materializes, which is confusing and wastes space. The description is short but completeness suffers from this dangling clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 11 optional parameters and no output schema, the description covers the primary purpose and provides a key filtering tip, but the unfinished 'two scenarios' sentence leaves a meaningful contextual gap. It doesn't describe the response shape, which given no output schema would be helpful (though the parameter docs mitigate this). The pagination and safety aspects are reasonably handled via schema and annotations. Decent but incomplete due to the truncation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter docs (e.g., top explains context-window considerations, fetchAllPages warns about enormous payloads, count explains ConsistencyLevel). The description's tip adds meaning about filter/search semantics beyond the schema—specifically that contains()/eq on emailAddresses fail and $search is the alternative—which directly informs how to use those parameters. This extra nuance elevates it above the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') with a clear resource ('contact collection') scoped to 'the default contacts folder of the signed-in user,' which distinguishes it from siblings like list-contact-folder-contacts (specific folder) and get-outlook-contact (single contact). The tip about $filter and $search further clarifies its filtering capabilities. Purpose is unambiguous and distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The TIP provides practical guidance on when to use $filter vs $search (startswith() works, contains()/eq on emailAddresses don't; use $search for broader matching). However, the truncated sentence 'There are two scenarios where an app can get contacts in another user's contact folder:' never completes, leaving a gap. It also doesn't explicitly differentiate from siblings like list-contact-folder-contacts or state when NOT to use this tool. Some use guidance exists but no alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark readOnlyHint and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context: the response depends on calling context, the caller must already have read permission for the subscribed resource (no dedicated scope), and it lists the returned properties. This goes beyond the annotations and helps the agent understand permission requirements and variable responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized, with a formal opening sentence and a bulleted tip that packs useful specifics. The tip is actionable and front-loaded. It is not overly verbose, though the first sentence is somewhat generic and could be tightened. The structure is logical and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 optional parameters and no output schema, the description covers the key essentials: it states what is returned (list of fields), notes permission requirements, and gives a filter example. It does not explain every nuance (e.g., pagination behavior) but the schema already handles those. The description is sufficiently complete for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description, so the baseline is 3. The tool description provides an example of using $filter ('Use $filter=resource eq '/me/messages'...'), which adds a practical usage hint, but it does not significantly enrich the semantics of individual parameters beyond what the schema already specifies. It stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve the properties and relationships of webhook subscriptions') and adds specificity with the tip: 'Lists webhook subscriptions owned by the current app/user' and enumerates the exact fields returned. This distinguishes it from sibling tools like get-subscription (single) and create-subscription (new), even without explicitly naming them. The verb-resource pair is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (for listing subscriptions) and gives a filter example for a specific resource, but it does not explicitly contrast with get-subscription, create-subscription, or other alternatives. There is no direct 'when to use this vs. that' guidance, and it does not mention situations where this tool should NOT be used. The context is clear but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 covered. The description adds that it returns localeInfo objects with specific fields and that it is sourced from the mailbox server, which is useful. It does not contradict any annotations, but it also does not disclose any additional behavioral traits beyond what annotations and schema already imply. With annotations covering the core behavior, the description provides modest added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a tip. The first sentence states the core purpose, and the second adds context about the flow. The tip is front-loaded with a bullet and provides concrete return format and usage advice. It is efficient without being overly terse, though the phrase 'You can subsequently get the preferred language by getting the user's mailbox settings' could be trimmed. Overall, it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description properly explains the return format (localeInfo objects with locale and displayName). It also gives a practical validation use case. All parameters are documented in the schema, and the description covers the essential context. It does not mention pagination behavior, but the schema already covers $top/$skip/fetchAllPages, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (top, skip, count, filter, search, fetchAllPages, includeHeaders, excludeResponse) already has a detailed description in the input schema. The tool description does not add any parameter-specific guidance beyond what the schema provides. Per the calibration baseline for high schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the list of locales and languages supported on the user's mailbox server. It specifies the exact resource and purpose, and distinguishes itself from the sibling list-supported-time-zones by focusing on languages/locales rather than time zones. The mention of 'localeInfo objects with locale (e.g. 'en-US') and displayName' further clarifies the output, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this list is used when setting up an Outlook client, and to validate a locale before calling update-mailbox-settings. It references get-mailbox-settings for retrieving the preferred language, effectively routing the agent to related tools. However, it does not explicitly state when not to use this tool or compare it to alternatives like list-supported-time-zones, so it lacks explicit exclusions—hence a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag the operation as destructive and not read-only. The description adds valuable context by explaining that the organizer is notified by default unless sendResponse is set to false, and it provides an example of the optional body. This goes beyond the annotations and clarifies the side effect of notifying the organizer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences and a tip. The purpose is front-loaded, and the tip provides a compact, actionable clarification. No unnecessary words, and the structure flows logically from purpose to usage detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters and a nested object, the description covers the primary action and key behavior (organizer notification). The schema handles the remaining parameters, including the confirm gate. It does not mention the confirm parameter, but that is documented in the schema, so the description is mostly complete. It could be slightly richer about destructive implications, but the annotations compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%), but the description enhances parameter understanding by showing an example of the body parameter with sendResponse and comment, and explicitly explains that sendResponse: false suppresses organizer notification. This adds meaning beyond the schema's default value and property types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Accept the specified event in a user calendar.' It also specifies it accepts a 'meeting invitation' in the tip, which distinguishes it from sibling tools like decline-calendar-event or cancel-calendar-event. This is a specific verb+resource with enough context to understand its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus its many sibling calendar-event actions (e.g., tentatively-accept-calendar-event, decline-calendar-event). It only explains the optional sendResponse behavior, but no selection criteria or alternatives are mentioned, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=false and destructiveHint=true, aligning with the description's 'Create' action, so there is no contradiction. However, the description doesn't disclose additional behavioral aspects beyond what the annotations already convey. It does add an example of the body structure, but that pertains to parameters rather than behavior. Since the annotation already indicates a destructive write, the description doesn't add significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose and has redundancy. The main description and the tip share similar information (both explain linking a resource and provide body examples). It could be tightened without losing meaning. The core purpose is clear, but the extra example and tip repeat content, reducing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with a required body and path parameters, the description provides enough context: it explains what the tool does, gives an example body, and clarifies the association scenario. The required parameters are documented in the schema, and the description doesn't overlook any critical usage detail. The lack of an output schema is typical for create operations, so no additional return-value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, meaning most parameters are described in the schema. The description adds a concrete example of the body object with fields like webUrl, applicationName, displayName, and externalId, giving a template that helps an agent construct the body. This enriches the schema descriptions and helps clarify expected values, especially for the nested body parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Create a linkedResource object to associate a specified task with an item in a partner application.' It uses a specific verb (create), a specific resource (linkedResource), and clarifies the association intent. This clearly distinguishes it from siblings like list-todo-linked-resources and delete-todo-linked-resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides contextual use cases, e.g., 'you can associate a task with an email item in Outlook that spurred the task,' and notes you can create a linkedResource during task creation. It also gives guidance on when to use it ('Use to link tasks to emails, files, or web pages for context'). It doesn't explicitly state when not to use it, but the siblings are obvious alternatives that are not relevant here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, covering the core safety profile. The description adds no contradictory statements and provides some useful context (e.g., the source of todoTaskListId and optional fields). However, it does not disclose any additional behavioral traits like confirmation requirements (though the confirm parameter is in the schema) or side effects beyond creation. Since the description does not contradict annotations and adds a small amount of context, a mid-range score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the primary purpose stated first and the tip as a compact, useful addition. The '💡 TIP' is informal but efficient, and there is no unnecessary verbosity. It is appropriately front-loaded and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a complex nested body and a required list ID, the description provides a minimal body example, lists optional fields, and directs the agent to the sibling tool for the ID. It does not mention the confirm parameter or output structure, but annotations and schema cover those aspects. Given the richness of the schema, the description is sufficient for correct invocation, though it could briefly note the confirmation gate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, which is high, so the baseline is 3. The description echoes some schema details (e.g., 'Body: { title: ... }' and optional fields) but does not add meaning beyond what the schema already provides. The only slight addition is highlighting the most relevant optional fields for a quick start, but it is largely redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new task object') and the resource ('task object in a specified todoTaskList'). It also frames it as a Microsoft To Do operation, distinguishing it from sibling tools like list-todo-tasks or create-todo-task-list. The verb+resource combination is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite: 'Requires todoTaskListId from list-todo-task-lists', which tells the agent where to obtain the required ID. It also furnishes a body example and lists optional fields, giving practical usage context. It does not explicitly state when to avoid this tool (e.g., for updates/deletes), but the create nature is self-evident from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description adds the constraint that only non-inherited permissions can be deleted. It does not mention potential side effects (e.g., impact on sharing) or failure behavior for inherited permissions, but the annotation covers the destructive nature. The added constraint is useful context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a one-sentence purpose plus a clearly separated tip. It front-loads the main verb/resource and keeps the tip separate for readability. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with complete schema documentation and a destructiveHint annotation, the description covers the essential prerequisite (finding the permission ID) and a key constraint (non-inherited). It does not explain return values, but no output schema exists, and the schema details all parameters. The information is sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a detailed schema description (e.g., driveId, driveItemId, permissionId, confirm, includeHeaders). The tool description does not add any additional parameter information beyond what the schema already provides, so it earns the baseline 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action ('Delete a drive item permission') and clarifies it applies to a file or folder. It clearly distinguishes itself from other permission tools (like share or list) by specifying it removes an existing permission. The tip reinforces the purpose by explaining it removes a specific permission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip provides actionable guidance: use list-drive-item-permissions first to find the permission ID, and only non-inherited permissions can be deleted. This gives a clear prerequisite and a condition for use. It stops short of explicitly naming alternatives or when not to use this tool, but the guidance is sufficient for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description does not need to restate that. It adds meaningful context by specifying the zero-based row index and that it applies to a formal Excel table, which goes beyond the annotations and helps the agent understand the deletion semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences with no wasted words. The purpose is stated upfront, and the tip adds a key detail in a scannable format with an emoji. Perfectly sized for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation, the description covers the essential action and target. It does not describe return values, but no output schema exists and delete responses are typically minimal. The parameters are well-documented in the schema, and the zero-based index detail fills a critical gap. It is complete enough for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that the 'index' parameter is zero-based, which is not obvious from the schema's generic 'Value for the index path segment.' This specific detail improves parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an Excel table row' with a specific verb and resource. The tip adds that it targets a single row in a formal Excel table by zero-based index, distinguishing it from range operations and sibling tools like update-excel-table-row.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as update-excel-table-row or list-excel-table-rows. The tip clarifies the index semantics but does not explain when deletion is appropriate or when other tools should be chosen instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the tool is known to be destructive. The description adds valuable context: it specifies 'soft delete' and its behavior (moves to Deleted Items), which is beyond annotations. It also explains the confirm gate parameter, revealing that without confirm: true, calls will fail under certain configurations. This is helpful behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and a tip, all relevant. It's concise and the tip repeats the first sentence, which is slightly redundant. However, it's not lengthy. The core purpose is front-loaded, and the tip is a quick reminder. No wasted words. It's efficient but could be more concise by removing the repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a destructive operation, annotations indicate destructiveHint true, and there is no output schema. The description covers the soft-delete behavior, the confirm requirement, and the identifier usage is covered in schema. The description is sufficient for an agent to understand how to delete correctly, including the potential need for confirmation. It doesn't cover return values, but that's acceptable without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are described in the schema. The description itself adds no additional parameter semantics, but the schema descriptions are thorough, including specific guidance on messageId (use 'id' from Graph, not as 'id'). The description's tip doesn't add parameter info. Baseline for 100% coverage is 3, but the description's tip reinforces the soft-delete behavior which is relevant to the confirm parameter. This slightly elevates it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete'), resource ('Outlook email message'), and identifies the key identifier ('message ID'). It distinguishes itself from other delete operations in the sibling list (e.g., delete-calendar, delete-todo-task). However, it doesn't explicitly contrast it with related mail operations like move-mail-message or delete-mail-folder, but the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly notes this is a 'soft delete' and states the consequence ('moves to Deleted Items'). It also provides a behavioral tip about permanent deletion. It doesn't explicitly state when to use this vs alternatives, but given the sibling list, the purpose is unambiguous enough. It doesn't mention exclusions or alternatives, but the context of deleting a specific message is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint, destructiveHint, and openWorldHint, but the description adds valuable behavioral details beyond these: it explains that the GET returns the user's chosen time zone in the administrator-configured format, that Windows format is default, and that getting a specific format requires a prior update. This is transparent and 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy, especially the time zone paragraph, which takes up several sentences. It is not front-loaded after the first sentence and includes a separate 'TIP' section at the end. While the information is relevant for correct usage, it could be more concise by trimming redundant explanations. Still, the description earns its keep with useful details, though it verges on verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description (including the TIP) enumerates the returned settings, explains time zone format behavior, and mentions the ability to request all or specific settings. It omits explicit mention of pagination or the fetchAllPages parameter, but those are covered in the schema. Overall, it provides sufficient context for an agent to use the tool correctly without surprises.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all five parameters (expand, select, fetchAllPages, includeHeaders, excludeResponse), each with detailed explanations. The description itself does not add meaning beyond the schema; it only vaguely mentions 'get specific settings' which maps to select. Since the schema carries the full weight, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the user's mailboxSettings, lists the specific settings included ('automaticRepliesSetting, language, timeZone, dateFormat, timeFormat, delegateMeetingMessageDeliveryOptions, and userPurpose'), and distinguishes between viewing all or specific settings via $select. It is unambiguous and differentiates itself from the sibling update-mailbox-settings by describing a get operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: to view mailbox settings, and it explains the workflow for time zone format conversion (update first, then get). However, it does not explicitly name alternatives or state exclusions like 'use update-mailbox-settings to modify settings', leaving some inference to the agent. The annotations (readOnlyHint) reinforce its read-only nature, but the description itself could be more explicit about not using this for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 covered. The description adds context about the returned fields (subject, sender, recipients, etc.), but does not disclose any side effects, error conditions, or limitations beyond what the parameter descriptions already provide. It adds modest 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that front-loads the core action and purpose, then adds the necessary usage hint. No wasted words, and it is appropriately sized for a straightforward tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with a fully described schema and annotations covering safety, the description is complete enough. It tells the agent what the tool does, what it returns, and how to obtain the required ID. There is no output schema, but the description mentions key returned fields. Minor omissions like pagination behavior are already addressed in the fetchAllPages parameter description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter (expand, select, messageId, fetchAllPages, includeHeaders, excludeResponse) explained. The tool description does not add further parameter semantics beyond restating the message ID in plain terms. The baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Get), the resource (single Outlook email message), and key identifiers (message ID). It also lists the content returned (subject, sender, recipients, body, attachment flags) and distinguishes from siblings like list-mail-messages and get-mail-message-mime by emphasizing 'single' and 'full' content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use list-mail-messages first to obtain the message ID, giving a clear prerequisite and usage flow. It does not explicitly list alternatives or when-not-to-use, but the contextual guidance is clear and sufficient for typical selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint and destructiveHint, so the description adds value by disclosing that event bodies are only HTML format and that recurring events are not expanded. These are meaningful behavioral traits beyond the annotations. No contradiction detected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is muddled: it contains an incomplete sentence about 'two scenarios' and a redundant warning (mentions seriesMaster twice). Key information about the tool's limitations is embedded in a TIP/WARNING block rather than cleanly structured. It lacks front-loading and wastes space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not clarify whether it operates on the default calendar or all calendars, and the incomplete 'two scenarios' sentence leaves scope unclear. It also omits details like pagination behavior beyond parameter docs. While the schema covers many aspects, the description leaves gaps for an agent deciding which calendar-related tool to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter explanations, so the description adds little beyond the schema. The baseline of 3 applies because the schema carries the full burden; the description doesn't provide any additional parameter-level insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets a list of event objects in the user's mailbox, and distinguishes itself from alternatives by pointing to get-calendar-view for expanded recurring instances and noting it returns only series masters. This is a specific verb+resource that differentiates it from sibling tools like list-specific-calendar-events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly instructs when to use alternatives: 'To get expanded event instances, you can get the calendar view' and explicitly warns 'Use get-calendar-view instead to see individual occurrences within a date range.' This gives an agent clear context for selecting the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 covered. The description adds the folder/package facet condition, which is behavioral context beyond the annotations. It does not contradict annotations and provides useful detail about when children exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. It states the core action and the prerequisite condition succinctly, front-loading the purpose. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but sufficient for a read-only list tool. It doesn't mention pagination or response format, but those are covered in the parameter descriptions and the absence of an output schema. The condition about folder facets is a useful addition. Overall, complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a description in the schema. The tool description adds no parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns child DriveItems of a DriveItem, and explains the condition (non-null folder or package facet). This is specific and distinguishes it from siblings like get-drive-item or search-onedrive-files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: it lists children of a folder. The description does not explicitly mention alternatives or when not to use this tool, but the purpose is evident from the description and schema. No explicit exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark destructiveHint: true, lowering the disclosure bar. The description adds genuinely useful context beyond the annotations: the 48h window, the lifecycle trigger, and the 'no body required' note. It does not explicitly describe timing side effects on expiry, but it goes beyond what annotations declare. No contradiction with the destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core action is front-loaded, and the text is short. However, there is noticeable redundancy: the TIP's first clause ('Reauthorizes a subscription after receiving a reauthorizationRequired lifecycle notification') nearly repeats the main description verbatim. The genuinely useful additions (48h window, no body required) could have been merged into a single tighter paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single required parameter, full schema coverage, and a destructiveHint annotation, the description covers the key operational facts: the trigger condition, the time window, and that no body is required. Absent an output schema, return-value behavior is not specified, but this is not critical for a simple reauthorization call. Reasonably complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters thoroughly, including the helpful guidance on how to pass subscriptionId (not as 'id'). The description adds 'no body required' but little parameter-specific meaning beyond what the schema supplies. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (reauthorize) and resource (subscription), and ties it to an explicit trigger: the 'reauthorizationRequired challenge' / lifecycle notification. This clearly distinguishes it from sibling tools like create-subscription, delete-subscription, and update-subscription by its unique trigger condition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use the tool — upon receiving a reauthorizationRequired lifecycle notification — and adds a timing constraint (within the reauthorizationRequiredDateTime window, typically 48h). It doesn't explicitly name alternatives or state when-not-to-use, but the trigger is specific enough that the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds that the reminder re-fires at the new time, which is useful behavioral context. It doesn't contradict annotations, but it also doesn't elaborate on side effects or confirmation requirements beyond what schema and annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The purpose is front-loaded, and the tip block is concise. Every sentence earns its place, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with annotations and a detailed input schema, the description covers the essential action and body format. It doesn't explain the confirm gate, includeHeaders, or excludeResponse, but these are generic and already in the schema. The absence of an output schema means the description isn't required to describe return values. Overall, it is adequately complete for an agent to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, and the core body structure (NewReminderTime with dateTime and timeZone) is already documented. The description adds a note about timeZone being IANA or Windows, which slightly clarifies the schema's example, but it does not add substantial new meaning. Thus, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (postpone) and the resource (a reminder for an event), and the phrase 'triggered event reminder' distinguishes it from related actions like dismissal. This makes the purpose unambiguous and differentiates it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use it: for a triggered reminder that should re-fire later. It implies the alternative (dismissing) is different but does not explicitly name it or give exclusion criteria. Still, the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's responsibility is to add context beyond these. It adds 'No request body' and the inverse relationship, which is useful. However, it omits potential data consequences (e.g., unmerging retains only top-left cell values), which would be valuable for a destructive operation. It provides some additional context but not rich behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a concise tip, with the action front-loaded ('Unmerge an Excel range.') and the clarifying tip immediately following. There is no fluff or redundant information; every word contributes to understanding the tool's purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple operation with well-documented parameters and annotations covering destructiveness, the description is largely complete. It clearly states what the tool does and references its inverse. A minor gap is the lack of explanation about data preservation after unmerging, but that is not critical given the annotations and the straightforward nature of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description does not add parameter-specific meaning beyond the vague 'given range', which loosely maps to the 'address' parameter. Since the schema carries the parameter documentation burden, the description adds minimal value, justifying the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource (unmerge Excel range) and clarifies that it reverses merged cells into individual cells, explicitly calling out the inverse relationship with merge-excel-range. It also notes 'No request body', which further clarifies the operation's scope. This distinguishes it from sibling tools without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly provides usage guidance by naming the inverse tool (merge-excel-range), allowing an agent to understand when to use this tool (to unmerge) vs the sibling (to merge). It does not explicitly list exclusions or alternative scenarios, but the inverse reference gives clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, so the write nature is already known. The description adds genuine behavioral context beyond that: the draft is persisted to the Drafts folder and is NOT sent, which materially affects how an agent sequences this call. Given annotations already carry the safety profile, this is solid added value without contradicting anything.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly packed sentences: purpose and location first, then settable fields, then the critical save-vs-send disambiguation. No filler or redundancy; every sentence earns its place. Could perhaps front-load the 'not sent' clarification even earlier, but the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a draft-creation tool with annotations covering the write/destructive profile, the description captures the essential behavior: it saves a draft, names the settable fields, and disambiguates from sending. Optional fields like attachments and bcc are absent but are documented in the schema body nested properties. The confirm-gate parameter is self-documented in the schema, so no gap there. An agent can call this correctly with the given information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (moderately high), so the schema documents most parameters. The description names the key message fields (subject, body, toRecipients, ccRecipients, importance) which maps to nested schema properties and adds modest orientation for an agent. It does not add format or syntax details beyond the schema, so a 3 baseline is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource+scope: 'Create a draft Outlook email message in the signed-in user's Drafts folder.' It names the settable fields (subject, body, toRecipients, ccRecipients, importance) and explicitly contrasts itself with send-mail by stating the draft is saved, not sent. An agent can immediately tell what this tool does and how it differs from send-mail/send-draft-message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context: it states the draft is not sent and points to send-mail as the alternative for direct sending ('use send-mail to send a message directly, or send the draft afterwards'). However, among the large sibling set there are create-forward-draft, create-reply-draft, and create-reply-all-draft, which are not explicitly excluded; the phrase 'draft Outlook email message' only indirectly implies a fresh draft. Some exclusion guidance for those variants would push this to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true and readOnlyHint: false, so the description's job is to add context. It does by stating that 'The event remains in the calendar as declined unless the user deletes it,' which clarifies the persistence behavior. It also mentions the tip with an example body, conveying sendResponse and comment semantics, though it stops short of describing all recovery options or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs, with the core action front-loaded and a separate tip that offers a concrete example. It avoids unnecessary fluff but does repeat 'Declines a meeting invitation' in the tip, which is minor redundancy. The structure is clear and scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, nested objects) and no output schema, the description covers the essential usage: what it does, how to propose a new time, and the persistence behavior. It lacks an explicit statement about the response format, but that is not critical because the schema does not define one. It also points to further documentation for proposals. Overall, enough context for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so most parameters have descriptions. The description adds value by explicitly mentioning the proposedNewTime parameter and providing a concrete example body ('sendResponse: true, comment: ...'), which clarifies how to use the body object. It also reinforces the eventId usage, but the schema already explains that. Overall it augments the schema without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Decline invitation to the specified event in a user calendar.' It uses a specific verb and resource, making the purpose unambiguous. It also distinguishes itself from sibling operations like accept or cancel by focusing on declining, and the proposedNewTime option adds nuance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when the user wants to decline a meeting invitation, and it explains the optional proposedNewTime scenario. However, it does not explicitly contrast it with alternatives such as accept-calendar-event, tentatively-accept, or cancel, leaving the choice to inference. There is no clear 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent. It adds value by specifying the return type ('MIME stream as text'), including headers/attachments, and warning about fetchAllPages potentially returning enormous payloads—beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with a clear first sentence, followed by a tip that adds context but somewhat redundantly restates the core purpose. No wasted words, but the tip could be trimmed. Front-loaded purpose and immediate actionable guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only download tool with 5 parameters and no output schema, the description covers purpose, usage scenario, return type, and how to obtain the required ID. It warns about the risk of large payloads via fetchAllPages. It does not explain failure modes or the behavior of includeHiddenMessages, but those are covered in the schema, so completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions (e.g., 'messageId' explains the naming and source, 'fetchAllPages' warns about large payloads). The description adds a tip about finding the message id earlier but does not enhance parameter understanding beyond 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Download the raw MIME source'), the resource (Outlook email message), and the method (by message ID). It explicitly differentiates from similar tools like get-mail-message (JSON retrieval) and gives a concrete use case (archiving to .eml).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear use case ('when archiving an email to disk') and tells the agent to find the message id with list-mail-messages first. However, it does not explicitly mention alternatives like get-mail-message, so the agent must infer that this is for raw MIME rather than structured data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true and destructiveHint=false. The description adds value by naming the specific fields returned (resource, changeType, notificationUrl, expirationDateTime, applicationId) and pointing to the Permissions section for supported resources. This provides context beyond the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences plus a concise tip. It front-loads the core purpose and then provides a useful shortcut. No redundant phrasing; every sentence contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return fields, mentions permissions context, and gives the id-finding workflow. Given the read-only hint and the thorough parameter schema, the description is complete enough for an agent to call this tool correctly, though it doesn't detail output structure (no output schema exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage of parameters with detailed descriptions (e.g., subscriptionId is described as a path segment with explicit naming guidance). The tool description doesn't add extra parameter semantics beyond what the schema already explains, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retrieve') and resource ('a subscription'), and differentiates itself from siblings by explicitly saying 'Gets a specific webhook subscription by id' and referencing list-subscriptions to find the id. This clearly separates it from the listing and mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip 'Use list-subscriptions to find the id' gives direct guidance on when to use this tool versus its sibling for listing. It doesn't explicitly exclude other tools (e.g., update or delete), but the focused use case is clear. A small deduction for not explicitly stating when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description reinforces this with 'Read-only' and adds context about what each table contains (id, name, showHeaders, etc.), which helps anticipate the response structure beyond annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single formal sentence plus a tip. The tip is useful and front-loaded with the main action. Minor redundancy exists between 'Represents a collection of tables' and 'Lists all named tables', but overall it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a complex OData query parameter set, the schema fully documents parameters. The description provides context that this is within an Excel workbook and what fields to expect in returned items. It does not describe pagination behavior explicitly, but the schema covers $top and nextLink, making it sufficient for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 13 parameters have full schema descriptions (100% coverage), so the description adds little about parameters. The tip mentions that table id/name can be used elsewhere, but this is not directly about parameters. Baseline 3 is appropriate since the schema handles semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lists all named tables in a workbook' with a specific verb and resource. It distinguishes this tool from siblings like 'get-excel-table' or 'list-excel-table-rows' by specifying it retrieves the table collection, not a single table or rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip suggests using the table name or id with other table endpoints, implying its output is used as input elsewhere. It does not explicitly state when to use this versus alternatives, but the purpose is clear enough that an agent would know to call it when needing an overview of tables before drilling into specific tables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 covered. The description adds value by clarifying that the tool returns metadata only, not content bytes, and explains the /$value suffix for raw bytes and the risk of truncation with embedded contentBytes. This is behavioral info 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence followed by a concise tip. It front-loads the action and places the alternative usage in a separate tip block. All sentences serve a purpose; no fluff. It could be slightly tighter, but it's well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with a rich schema covering pagination and filtering, the description covers the main use case and gives crucial guidance on downloading bytes. It doesn't describe the response structure, but there's no output schema and the fields are listed in the tip. It's sufficient for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter already has a detailed description (top, skip, filter, etc.). The description does not add new parameter-level details beyond the schema, which is acceptable given the high coverage. The tip mentions a path suffix but not a parameter directly. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of attachment objects for a message, and enumerates the fields returned (id, name, contentType, size, isInline). This distinguishes it from siblings like list-mail-messages or add-mail-attachment. The scope is explicit: attachments on a specific message (via required messageId).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip explicitly routes download intent to download-bytes with a concrete URL pattern, and warns about truncation when using the bare attachment URL. This gives a clear alternative for a common follow-up action. However, it doesn't broadly contrast with other siblings (e.g., listing all mail vs. attachments), but the tool name and parameter make that self-evident. The guidance is useful and explicit for the key alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, but the description adds valuable context: the empty return for delegates/share recipients and the note that only the owner sees the full list. It also enumerates returned fields, exceeding annotation-only disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with a clear lead sentence and additional useful details. It is moderately sized but not bloated; the field list adds length but provides needed context for a tool without an output schema. The structure is logical with the core purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description's enumeration of returned fields is essential and well-covered. It also addresses edge cases (delegate view) and the alternative for non-primary calendars, making the tool's capabilities and limitations clear. Pagination is implied via parameters, so no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented in the schema. The description's tip about using small $top and $select is already present in the parameter descriptions, so it adds little meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'list' and the resource 'calendar permissions', specifying it covers users with whom the calendar is shared. It differentiates from siblings by scoping to the primary calendar, and the mention of the non-primary alternative shows awareness of tool boundaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States that for non-primary calendars an alternative endpoint exists but is not exposed, and notes the empty-collection behavior for delegates/share recipients. This provides practical context for when the tool is appropriate, though it doesn't explicitly compare with sibling permission tools like create/update/delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with that. It adds behavioral details such as default sort order (name asc) and supported $expand values, giving agents insight into traversal. This goes beyond the annotations and is consistent, earning a solid score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative without being bloated. It front-loads the core action, then provides contextual detail in a tip. Each sentence adds value—definition, hierarchy traversal hints, and pairing advice. It's not as tight as a two-sentence ideal but earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description covers the essential context: what section groups are, default sorting, expansion capabilities, and relationship to notebooks. Pagination is not explicitly mentioned, but the schema covers top/skip/fetchAllPages thoroughly, so no gaps remain for an agent to safely invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds a specific hint for the expand parameter (listing valid navigation properties), which is helpful but not exhaustive. Since the baseline is 3 because schema covers everything, this slight addition warrants a 3 rather than a 4—there's no deep parameter-specific guidance beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Retrieve a list of sectionGroup objects.' It then defines what a section group is, distinguishing it from notebooks and sections. This makes the tool's purpose unmistakable and differentiates it from siblings like list-onenote-notebooks and list-onenote-section-pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance to pair with list-onenote-notebooks for a complete structure view and explains the folder-like nature of section groups. However, it does not explicitly state when NOT to use this tool or contrast with alternatives like list-onenote-sections. The pairing hint is useful, but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint=true and destructiveHint=false annotations by specifying the output structure: each item is represented as a linkedResource object with an external ID and a deep link. The TIP further enumerates fields like displayName, webUrl, applicationName, and externalId. This gives the agent a clear expectation of the response without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core purpose, and the TIP adds clarity with plain-language examples. It is not verbose, though the TIP partially repeats information already implied by the formal sentence. Overall, it is efficient and well-structured for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (listing linked resources) and the rich schema covering all query parameters, the description provides sufficient context: it explains that results are linkedResource objects with certain fields, and the read-only nature is annotated. It does not detail every possible query option, but those are in the schema. The absence of an output schema is mitigated by the field list in the TIP, making it complete enough for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage for all 13 parameters, including detailed guidance on $top, $filter, pagination, and required path segments. The tool description itself adds no additional parameter semantics; it does not elaborate on any parameter or usage pattern beyond what the schema provides. Thus, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get information of one or more items in a partner application, based on which a specified task was created.' It exposes the resource type (linkedResource) and the context (To Do task). The additional TIP reinforces that it lists resources linked to a task, making its role distinct from sibling tools like create-todo-linked-resource and delete-todo-linked-resource without explicitly naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context: it retrieves linked resources for a specified task, which implicitly indicates this is the tool to use when you need to list such resources. However, it does not explicitly state when to avoid it or mention alternatives (e.g., create/delete). Given the obvious read-only nature and naming, it is sufficient, but not as explicit as ideal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds the behavioral note that an email may be sent to recipients (sendInvitation) via the TIP, but it does not disclose that permissions persist and are only removable via delete-drive-item-permission, nor does it mention reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in one sentence, and the TIP section is cleanly separated with an example and role list. Dense but efficient — every part earns its place, though the single-sentence TIP runs long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-body operation with no output schema, the description covers the essential calling behavior: recipient format, roles, sendInvitation, message, and requireSignIn. It omits some body fields (password, expirationDateTime, retainInheritedPermissions), but these are documented in the schema, keeping the burden on the description manageable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high at 83%, so the baseline is 3. The TIP adds genuine value beyond the schema by enumerating the valid role values ('read', 'write', 'owner') and giving a concrete body example with the correct field shapes — details the schema does not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair ('Send a sharing invitation for a driveItem') and the effect (provides permissions and optionally sends notification email). This clearly distinguishes the tool from its sibling create-drive-item-share-link, which creates anonymous links rather than granting permissions to named recipients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The TIP explicitly frames the use case — 'Shares a file or folder with specific users' — which implies choosing this over link-based sharing alternatives. However, it does not explicitly name the sibling it competes with or state when NOT to use it, leaving part of the routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare `destructiveHint: true` and `readOnlyHint: false`, indicating this is a write operation. The description adds useful context: the optional body parameters (`sendResponse`, `comment`), the conditional ability to propose a new time, and an example. However, it does not disclose whether the action is reversible, what the event status becomes, or any side effects beyond sending a response. Since annotations already cover the mutation nature, the description adds some value but remains thin on deeper behavioral consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose, with a main explanatory paragraph and a 'TIP' section containing examples. Each sentence adds actionable information: the core action, the proposal condition, and concrete usage examples. It is more than two sentences but not bloated; the structure is logical with the tip reinforcing the main text. Some redundancy exists (e.g., the phrase 'Tentatively accepts a meeting invitation' echoes the first line), but overall it is efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nested objects, optional proposals, a confirm gate, and multiple parameters. The description covers the primary purpose, the optional new-time feature, and provides examples for the most complex part (body). It also flags the confirm gate requirement. It does not describe the response format (no output schema) or specify error conditions (e.g., if the event doesn't allow proposals), but given the absence of an output schema and the moderate complexity, the description provides enough context for an agent to invoke it correctly. A reference to external docs fills the gap for edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so many parameters already have descriptions. The description adds significant value beyond the schema: it provides concrete JSON examples for the optional body and proposedNewTime, clarifies that `eventId` must be passed as 'eventId' not 'id', and explains the `confirm` gate. It also disambiguates the nested `proposedNewTime` structure. This extra guidance compensates for the 20% undocumented parameters (like `includeHeaders` and `excludeResponse` are self-explanatory but not covered).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Tentatively accept the specified event in a user calendar.' It names the verb, resource (calendar event), and the specific state change (tentative acceptance). It indirectly distinguishes from siblings like `accept-calendar-event` and `decline-calendar-event` by its name and action, and the mention of proposing alternative times adds unique purpose. This is a specific, unambiguous verb+resource combination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when this tool is appropriate: 'Tentatively accepts a meeting invitation' and describes the optional new-time proposal behavior. It references external documentation for proposing times, but does not explicitly state when to use alternatives like `accept-calendar-event` or `decline-calendar-event`. The context is clear but exclusions against siblings are not spelled out, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 write operation. The description adds useful behavioral context: it notes that the default 'Contacts' folder may not be renameable, and clarifies that both displayName and parentFolderId are writable. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of a main sentence, a tip, and a body example. It is front-loaded with the core purpose. There is slight redundancy between 'Update the properties of contactfolder object' and 'Updates a contact folder', but overall it is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with nested objects and multiple parameters, the description covers the essential usage: which fields are writable and how to obtain the folder ID. It does not explain the response format or the confirm parameter, but these may be covered by common patterns given no output schema is expected. The description provides enough context for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so most parameters have descriptions in the schema. The description adds value by explicitly stating the body structure { displayName?: 'New name', parentFolderId?: '<id>' } and identifying the writable fields. It also instructs how to obtain the contactFolderId (via list-contact-folders), which clarifies the path parameter. This goes beyond the schema's generic parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and a specific resource ('contactfolder object'). It clearly identifies what the tool does. Sibling tools like update-outlook-contact, delete-contact-folder, and create-contact-folder are distinct, and the description makes it clear this is for updating contact folders, not contacts or other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a helpful tip to get the folder id via list-contact-folders, which is a prerequisite for the contactFolderId parameter. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use create-contact-folder vs update). The guidance is implicit based on the tool name, but not explicit about exclusions or alternative selection conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint=true), and the description doesn't contradict that. It adds behavioral context beyond annotations: the ETag requirement and the GUID-key structure for checklist items. This tells the agent about a precondition and a format detail not present in the schema, enriching the behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and efficient. Two sentences plus a focused TIP. The purpose is front-loaded, and the critical prerequisite is highlighted in the TIP. No wasted words, and the critical details are presented without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex update operation with nested objects, the description covers the vital ETag requirement and checklist format. It doesn't explain every possible property, but those are in the schema. The absence of an output schema means return format is not needed. The description is sufficient for an agent to call it correctly, though it could mention that the operation affects only details, not the main task object, but the name implies that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so parameters are mostly documented. The description adds value by explaining the checklist GUID format and the If-Match/ETag usage, which are not fully covered in the schema. It helps the agent correctly construct the body and headers beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update the properties of plannerTaskDetails object', which clearly identifies the verb (update), the resource (plannerTaskDetails), and distinguishes it from update-planner-task by specifying 'details'. It lacks an explicit contrast with siblings, but the resource name is specific enough to avoid ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides critical usage guidance: it requires an If-Match header with the ETag from get-planner-task-details and instructs using includeHeaders=true. This indicates a prerequisite step and clarifies when to fetch the ETag first. It doesn't explicitly mention alternatives, but the ETag requirement effectively routes the agent to the right predecessor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context about behavior by specifying it creates contacts in specific folders and points out the need for a folder id. Annotations already indicate a write operation (readOnlyHint=false, destructiveHint=true), so the description complements them with scope. It does not mention confirmation gate or error handling, but those are covered in the schema's confirm parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the core purpose in the first sentence and a separate tip block for additional guidance. It is front-loaded with the primary action and uses a clear, scannable structure with an emoji. Minimal waste, though the tip could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with nested body objects and response-handling parameters (includeHeaders, excludeResponse), yet the description does not mention what the response contains (e.g., the created contact object). It covers main usage but omits failure conditions and output details. The schema covers parameters, but the description could be more complete about the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives an example body structure but largely duplicates the schema's detailed property descriptions. It adds the hint to use the 'id' field for contactFolderId, which is also in the schema. Given high schema coverage (80%), the description does not significantly enhance parameter understanding, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Add a contact to the root Contacts folder or to the contacts endpoint of another contact folder.' It also names the sibling create-outlook-contact and distinguishes this tool from it, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given on when to use this tool: 'The existing create-outlook-contact (POST /me/contacts) writes to the default folder only; use this when organizing contacts into named folders.' It also instructs to get the folder id via list-contact-folders, providing a complete usage path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a non-read-only, destructive-capable operation. The description adds an error condition (invalid address or overlap) and clarifies the address-to-worksheet mapping. It doesn't mention side effects like confirm-gate behavior (handled by schema note) or what the response contains, but it does add meaningful behavioral detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences plus a succinct tip. The core action is front-loaded, the error behavior is summarized, and the example is placed as a separate tip. No wasted words – every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, nested body, no output schema) and the schema's high coverage (86%), the description covers the essential use case, error conditions, and prerequisite relationship. It doesn't explain return values (no output schema) but is otherwise sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lacks descriptions for the body's address and hasHeaders properties, but the description compensates with an explicit example ('Body: { address: 'A1:H171', hasHeaders: true }') and explains that the address determines the worksheet. This adds practical meaning beyond the schema's type-only definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create a new table') and clarifies the relationship to the worksheet via the address. It clearly differentiates from sibling table operations (list/get/update/delete rows) by focusing on creation. The tip reinforces the purpose: converting a range into a formal Excel table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when this tool is required: before using add/update/delete-excel-table-rows on a plain-cells sheet. This gives clear context and a prerequisite. It doesn't mention when not to use it, but the specificity of the prerequisite is strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a write operation (readOnlyHint false, destructiveHint true). The description adds the important nuance that isHidden must be set at creation time if desired, which is behavioral guidance beyond the schema's mere statement of the property. It does not contradict annotations, and the confirm parameter is documented in the schema, so it doesn't need repetition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences plus a tip, with the core purpose front-loaded. No redundant content, and the tip is directly actionable. It earns its place without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with a rich schema (5 params, 2 required, nested body), the description provides the essential context: what it does, how to get the parent ID, and the hidden-folder caveat. It does not describe the return value, but there is no output schema, so that is not required. The confirm parameter is covered in the schema, so the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (80%), so the baseline is 3. The description's mention of isHidden and the tip about using list tools to find the parent ID largely mirror what is already in the schema for body.isHidden and mailFolderId. It reinforces but does not add new semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'create a new child mailFolder' and 'Creates a subfolder inside an existing mail folder.' This distinguishes it from sibling tool create-mail-folder (which likely handles top-level folders) and directly points to the list tools for locating the parent folder. The verb and resource are specific, and the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear tip on how to find the parent folder ID using list-mail-folders or list-mail-child-folders, which is essential for correct invocation. However, it does not explicitly state when not to use this tool (e.g., for top-level folders) nor mention the alternative create-mail-folder. It implies the use case via 'child' and 'subfolder' but lacks explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint false and destructiveHint true, so the burden on the description is reduced. The description explains the effect (posts a message teammates will see) and adds deployment constraints (beta, delegated accounts, global cloud). However, it does not mention that this is considered destructive or that confirmation might be required (the confirm parameter is only in the schema). It adds some context but not fully beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, modernization context, body structure example, and critical constraints (beta, environment, no ETag). It is front-loaded with the core action and uses a tip for guidance. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description covers the input structure, provides an example, and lists constraints. It doesn't explain the return value, but for a create operation that is often standard. It omits mention of the confirm parameter, but the schema describes it. Overall, the description is sufficient for an agent to call it correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%), but the description adds a concrete body example: { content: 'plain text or sanitized HTML', mentions?: [...] } and clarifies that mentions are optional. It also warns that plannerTaskId must be passed under that name, not as 'id'. This goes beyond the schema descriptions and provides practical usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new plannerTaskChatMessage on a plannerTask' – a specific verb and resource. It further distinguishes this from the legacy conversationThreadId comment, clarifying exactly what object is being created. The name itself is unambiguous, and the description reinforces the purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip clearly states this is the modern 'task chat' versus the legacy comment thread, and notes that Microsoft is retiring classic comments, so this is the supported path. It also indicates the body structure and mentions. It doesn't explicitly name alternative tools like list-planner-task-messages or delete-planner-task-message, but the context implies when to use it (for posting) vs. those. The beta and environment constraints are also noted, which help an agent decide suitability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide hints (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description carries the disclosure burden. It adds valuable behavioral context: the notificationUrl must validate with token echo, expiration maximums vary by resource (1 hour for calls, 24h for messages, 3 days for mail), and enabling includeResourceData requires encryptionCertificate + encryptionCertificateId. The creation side-effect aligns with destructiveHint=true, so there is no contradiction. The description enriches rather than repeats the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first paragraph is verbose boilerplate copied from Microsoft docs, including hyperlinks an agent cannot follow ('see Set up notifications...'). The TIP block is dense but efficient, front-loading required fields before optional ones. There is redundancy — the body requirements are repeated in prose and again structured in the schema. It earns its structural clarity but could trim the doc-link prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex operation (nested body object, 4 top-level parameters, no output schema), the description is fairly complete: it covers required body fields, optional rich-notification setup, and the permission precondition. Gaps are minor — it relies on non-clickable external references for details like lifecycleNotificationUrl behavior (Teams) and exact maximum lifetime tables, deferring that to the schema. Overall sufficient for an agent to form a valid request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, borderline high, so the schema already documents most fields well. But the description adds genuine value beyond the schema: permission requirements tied to specific scopes, concrete resource path examples, and concrete expiration maximums that the schema only vaguely references as 'Subscription lifetime.' This helps the agent construct a valid body without external lookups.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource statement: 'Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph.' This distinguishes it from the sibling set (update-subscription, delete-subscription, list-subscriptions, get-subscription) — this is the create operation. Nothing tautological; it clearly establishes the tool's function as registering a webhook for change notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The TIP block gives strong when-to-use guidance: required body fields, concrete resource path examples ('/me/mailFolders/inbox/messages', '/users/{id}/events'), and a permission model ('No dedicated scope — caller must have a read permission for the target resource, e.g. Mail.Read, Calendars.Read'). It explains the validation requirement for notificationUrl. However, it never explicitly contrasts with the sibling subscription tools or states when NOT to use it — usage is implied rather than explicitly differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate that. It adds value by disclosing the behavioral consequence: 'Future messages from that sender revert to the Outlook ML classifier's default behavior.' This goes beyond the bare 'delete' and gives the agent a clear understanding of the side effect. However, it doesn't mention irreversibility (covered by destructiveHint) or any authorization requirements, which are reasonable to omit given 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: a direct statement of the action and a concise tip. The primary verb is front-loaded, and the tip is actionable without extra fluff. There is zero waste; every sentence serves a purpose for correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with one required parameter, the description covers the core behavior, the consequence, and how to obtain the required ID. The sibling set includes list and update versions, so the tool's role is clear. An output schema is absent, so no return format is specified, but that's not unusual for a delete operation. The description is complete enough for an agent to call it correctly given the schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema itself. The description does not add extra semantic meaning beyond what the schema provides (e.g., it doesn't elaborate on the confirm parameter's behavior or If-Match usage). It only points to list-focused-inbox-overrides for finding the ID, which is a usage hint rather than parameter semantics. The baseline of 3 is appropriate since the schema fully covers parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('an override'), and further clarifies it's a Focused Inbox override. The tip explicitly mentions the behavior change (reverting to default sentiment) and distinguishes it from list/create/update siblings. An agent can clearly tell what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a direct usage hint: 'Use list-focused-inbox-overrides to find the ID first.' This is a concrete prerequisite for calling the tool correctly. It doesn't explicitly state when not to use it, but the destructive nature and the alternative (update) are implied. The guidance is adequate for correct invocation, though it could be more explicit about scenarios where deletion might be inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, so the destructive nature is clear. The description adds important behavioral context beyond the annotations: the ETag requirement and the need to fetch it first. This is valuable and does not contradict annotations. The description could further disclose post-deletion effects, but given the annotation coverage, the additional context is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one line for the purpose and one line for the critical prerequisite. It is front-loaded with the action and the crucial tip. Every sentence earns its place, with zero waste. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 5 parameters and no output schema, the description covers the essential operational requirement (the ETag prerequisite). It does not explain the return format or side effects, but given the simplicity of a delete operation and the schema covering parameters, the description is sufficiently complete. It could mention the confirm gate, but that is already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and every parameter has a description in the schema. The tool description does not add any parameter-specific semantics beyond what the schema provides. Baseline is 3 per calibration, and the description does not compensate with additional details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete plannerBucket' with a clear verb and resource. It unambiguously identifies the action and distinguishes it from sibling tools like update-planner-bucket or create-planner-bucket. The purpose is specific and immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance via the critical tip: it requires an If-Match header with an ETag from get-planner-bucket (obtained with includeHeaders=true). This tells the agent the necessary prerequisite and sequence. It does not mention alternatives or when not to use it, but it gives clear context for the main workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds the specific behavioral trait that built-in lists (Flagged emails, default Tasks) return an error, which is beyond the annotations. This enriches the agent's understanding without contradicting the metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The core action is front-loaded, and the tip adds critical caveats without verbosity. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation with no output schema, the description covers the essential behavior, key limitation, and how to obtain the required parameter. It doesn't explain return values or error handling beyond the built-in list case, but given the annotations cover the destructive nature and the schema covers all parameters, this is reasonably complete. A minor gap is not mentioning idempotency or whether deleting a nonexistent list errors, but that's not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter (todoTaskListId, confirm, If-Match, includeHeaders, excludeResponse) is already documented with clear meaning. The description only reiterates getting ids via list-todo-task-lists, which is usage guidance rather than additional parameter semantics. Baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Deletes') and resource ('todoTaskList object'), and clarifies it is a Microsoft To Do task list. This distinguishes it from other delete tools like delete-todo-task or delete-calendar, and the tip about built-in lists adds further scope precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use it (delete a Microsoft To Do task list) and explicitly notes a limitation: built-in lists cannot be deleted and will cause an error. It also directs to list-todo-task-lists to obtain ids, which serves as a prerequisite. However, it doesn't explicitly contrast with sibling delete-todo-task or other alternatives, so it's not a full when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Well beyond the readOnlyHint=true/destructiveHint=false annotations, the description discloses the iterative pagination contract, that deleted items appear with a deleted facet and must be removed from local state, and the apply-to-local-state workflow. This is substantial behavioral context the annotations alone cannot convey, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description front-loads the purpose and is logically ordered (initial call, pagination, deletion handling), but it is verbose and redundant: the core statement 'track changes in a driveItem and its children over time' appears in both the body and the TIP, and the TIP largely paraphrases the body. Tightening would improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter tool with no output schema, the description explains the delta-token return contract, the collection-of-driveItems return shape, and the deleted-facet semantics, making it largely complete. Minor gaps: it never clarifies that 'without any parameters' refers to query parameters (the schema still requires driveId/driveItemId), which could mislead an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each of the 13 parameters already carries a detailed description (e.g. $top page-size advice, expand error behavior, fetchAllPages warning). The body description adds no parameter-specific meaning beyond the schema, so the baseline 3 applies; the TIP's mention of $select is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('track changes') and resource ('a driveItem and its children over time'), and frames the tool as a delta-sync mechanism distinct from the general list functions. The delta-link protocol (nextLink/deltaLink) and the deleted-facet behavior make its purpose unambiguous and clearly differentiated from siblings like list-drive-item snapshots or get-drive-item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete call sequence: start with no parameters, follow @odata.nextLink until exhaustion, then use the @odata.deltaLink for future changes. The TIP adds the prerequisite of calling get-drive-root-item first. It does not explicitly name alternatives to avoid or state 'when not to use', so it misses explicit exclusions, but the protocol guidance is thorough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering safety. The description adds behavioral detail by enumerating the returned fields (address, values, formulas, numberFormat, rowCount, columnCount) and explaining that it returns the smallest encompassing range. It also hints at response trimming via $select. This goes beyond the annotations and gives the agent a clear picture of the operation's result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, with the core purpose first, then a tip explaining the concept, a list of return fields, and a usage recommendation. It is front-loaded, informative, and free of fluff. Every sentence contributes to understanding the tool's function and value. Structure is exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only retrieval tool with high schema coverage and safety annotations, the description covers the essential aspects: what it returns, when to use it, and how to trim output. It does not describe pagination beyond the fetchAllPages parameter (already in schema) or error handling, but those are not critical for this simple operation. The absence of an output schema is compensated by enumerating returned fields. Overall, an agent has enough guidance to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already described (e.g., driveId, driveItemId, workbookWorksheetId, fetchAllPages). The description does not elaborate on these parameters but adds a tip about the optional $select query, which is not in the schema. This is minor added value. Since the schema does the heavy lifting, a baseline of 3 is appropriate; the $select mention is a small bonus but not enough to raise the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get an Excel used range') and elaborates on what a used range is (smallest range with values or formatting) and what it returns (address, values, formulas, etc.). This exceeds a simple verb+resource by clarifying the semantic scope, making it distinct from siblings like get-excel-range, which retrieves an arbitrary range. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool 'to discover the populated bounds of a sheet before reading or appending,' providing clear context on when it is appropriate. It does not name specific alternative tools or exclusion conditions, but the use case is well-defined enough to guide an agent. The mention of '$select to trim the response' adds practical guidance on output control.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already indicates read-only and non-destructive, aligning with the description. The description adds valuable behavioral info: the response includes @odata.etag, required as If-Match for update/delete, and suggests using includeHeaders=true. This goes beyond the annotations and is critical for subsequent operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with a clear primary purpose and a useful tip. It is front-loaded and efficient, with no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get operation with no output schema, the description covers the essential behavior. It provides integration guidance about the ETag and headers, which is important for later steps. Combined with the rich schema, it gives an agent sufficient context to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes all parameters fully, so baseline is 3. The description adds value by recommending includeHeaders=true to obtain the ETag, tying that parameter to the tip. It doesn't elaborate on other parameters, but the coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the resource (plannerBucket) and the action (retrieve), which is clear. However, it does not differentiate from sibling tools like list-plan-buckets or get-planner-plan. It's unambiguous for retrieving a single object but lacks explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description doesn't explicitly state when to use this tool versus alternatives. It provides a tip about ETag usage for update/delete tools, which is useful context, but it doesn't explain when to call this get vs. list-plan-buckets or get-planner-plan. The usage guidance is implied by the parameter requirement but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description need not repeat that it can mutate. It adds valuable behavioral context beyond the annotations: responses are in arbitrary order and must be matched by id, and sub-request URLs are relative to the Graph root. The confirm gate is documented in the schema, so no gap there. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is duplicated verbatim (the same text appears twice in the description field), which is a clear structural flaw that wastes tokens and reflects poor quality control. Otherwise, the content is well-organized: purpose first, then body example, then use cases, then a critical note. But the duplication knocks the score down.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex meta-tool, the description is quite complete: it specifies the 20-request limit, the request/response structure, the use cases, and the URL relativity rule. It does not mention error handling or rate limits, but given the openWorldHint and lack of an output schema, the provided information covers the essential calling contract. One could argue the confirm gate is not mentioned, but it is in the schema. Overall, only minor gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for the 'body' parameter (it is an empty object with additionalProperties true). The description fully compensates by giving a detailed example with id, method, url, headers, body, and dependsOn, including method enum and URL format. This is essential, as the body is the core parameter and without this example the tool would be unusable. The other three parameters are already described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'Combine' and resource 'Graph requests into a single HTTP call', clearly distinguishing this meta-tool from the many sibling tools that each handle a single resource. It also includes the body format and response shape, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists three concrete use cases (parallelizing reads, sequencing writes via dependsOn, batching Excel writes), which effectively communicate when to use it. It also provides a crucial note about relative URLs, but does not explicitly state when NOT to use it (e.g., for a single request). This is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true and destructiveHint=false, and the description independently states 'Read-only', so there's no contradiction. The description adds behavioral detail beyond annotations by describing the row structure (index and values array) and recommending pagination strategy, which helps the agent anticipate response shape and context limits. It doesn't detail response format or edge cases, but given the safety profile is covered, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences plus a tip. The core action and read-only nature are front-loaded, and the pagination tip is relevant and useful. No fluff or redundant information; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters and no output schema, the description is minimal but sufficient given the exhaustive schema descriptions. It covers the core purpose and gives a pagination hint, while the schema explains all parameter details. The absence of a return-format description is mitigated by the row structure hint. It's complete enough for an agent to correctly invoke the tool for typical list operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all 14 parameters have detailed descriptions covering pagination, filtering, search, select, expand, etc. The tool description adds only a generic tip on using $top/$skip, which slightly supplements but does not add new semantics beyond what the schema already communicates. Baseline 3 is appropriate when schema carries the full explanatory load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the precise verb 'Lists' and resource 'all rows in a table', and adds that each row has index and values array. This clearly distinguishes it from sibling tools like list-excel-tables (which lists tables) and add/update/delete-excel-table-row (which mutate rows). The read-only note reinforces its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly notes this is read-only and provides a concrete tip on pagination using $top and $skip for large tables. While it doesn't name alternatives or state when not to use it, the purpose is unambiguous and the tip gives actionable guidance for typical usage scenarios. It could be improved by mentioning that iterative fetching is possible via @odata.nextLink, but that is present in the schema parameter descriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 covered. The description adds behavioral detail not in annotations: the default exclusion of hidden folders and the existence of the includeHiddenFolders parameter. This goes beyond the structured annotations and gives actionable insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and a useful navigation tip. No filler or redundancy; every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 13 parameters and no output schema, the description is brief but the parameter descriptions handle much of the needed detail. It covers the purpose, the default hidden-folder behavior, and a navigation shortcut. Missing are explicit statements about the response shape (though 'folder collection' implies a list) and any mention of pagination defaults, but the parameters (top, fetchAllPages) already convey that. Overall, adequate for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description itself does not add parameter-specific meaning; the rich descriptions of OData parameters (top, filter, select, etc.) are already in the schema. The description only mentions includeHiddenFolders implicitly via the mention of hidden folders, but that parameter also has a schema description. Thus, the description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get the folder collection') and the resource ('under the specified folder'), with a concrete hint about the top-level shortcut. It distinguishes itself from sibling tools like list-mail-folders (top-level) and list-contact-folder-child-folders (contacts version) by emphasis on 'mail' and navigation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to navigate from the top-level collection using the shortcut and mentions the includeHiddenFolders parameter to control hidden folders. However, it does not explicitly state when to prefer this tool over list-mail-folders or other siblings, nor does it provide exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context about the fields each rule contains (conditions, actions, exceptions), which helps the agent understand the response shape. However, it doesn't disclose pagination behavior or performance implications, which are left to the schema. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by a concise, useful tip. It's efficiently structured with no redundant words and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, the key parameter, and the expected structure of the returned rules, compensating for the lack of an output schema. It omits pagination guidance, but the schema's parameter descriptions for $top, $fetchAllPages, etc., address that, so an agent has enough information to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds a practical hint for the required 'mailFolderId' parameter by instructing to use the 'id' from list-mail-folders, which goes beyond the schema's explanation and reduces the chance of misusing the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Get' and resource 'messageRule objects' for the user's inbox, and clarifies it lists all rules for a mail folder. It also provides a practical tip about using the Inbox folder ID, making the purpose unambiguous and distinct from sibling tools like create-mail-rule or list-mail-folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly points the agent to list-mail-folders to obtain the Inbox folder ID, guiding the first step and implicitly differentiating from modification tools. It doesn't explicitly state when not to use it, but the read-only nature is clear from the verb and annotations, and the context is sufficient for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 restate safety. It adds valuable behavioral context by specifying the return structure (displayName and color ranging from preset0 to preset24 or 'none'), which is beyond what annotations provide. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the core purpose front-loaded and the tip adding relevant workflow context. No wasted words; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description covers the purpose, result structure, and a typical use case. Pagination and other advanced behaviors are already fully documented in the schema, so nothing critical is missing. It lacks an explicit note on return format (e.g., it returns an array), but that's implied by 'get all categories' and the data model.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for all 11 parameters (e.g., top, skip, filter). The description adds no parameter-specific semantics beyond omitting them entirely. Since the schema carries the full burden, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear, specific action: 'Get all the categories that have been defined for a user.' It also explains what categories are (colored labels) and their data model (displayName, color), making the tool's purpose unambiguous and distinct from create-outlook-category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a practical tip: 'Use this to show available tags before applying via update-mail-message or update-calendar-event' — this gives clear when-to-use guidance. It doesn't explicitly contrast with create-outlook-category, but it does name relevant sibling tools and a concrete workflow, so usage is well-routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 known. The description adds valuable behavioral detail: $select is NOT supported (Graph returns 400) and that the list 'typically' has a default list. This goes beyond annotations and helps avoid misusing the select parameter, showing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal: one clear purpose sentence, a useful tip, and a critical note. It is front-loaded with the primary function, and every sentence adds value (the tip indicates the returned id's role, the note warns about a common failure). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters with full schema descriptions and no output schema, the description adequately covers the core purpose and usage. It doesn't detail return structure (e.g., whether it's a list of objects or pagination envelope), but the parameter descriptions handle pagination and the read-only annotation covers safety. It tells the agent the id is essential for subsequent operations, which is critical context. Slight lack of explicit mention of the response shape, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 11 parameters have extensive schema descriptions (100% coverage), so the schema carries the parameter semantics burden. The description itself adds only one parameter-related note (the $select unsupported warning), which is useful but marginal. Baseline 3 applies because the schema is comprehensive; the description doesn't need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific action ('Get a list of the todoTaskList objects and their properties') and clarifies it returns the id needed for all task operations. It distinguishes from sibling 'list-todo-tasks' by explicitly targeting task lists, and notes the default list name 'Tasks'. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains it lists all To Do task lists and that returned ids are prerequisites for task operations, giving clear context for when to call it. It does not explicitly name alternatives or when-not-to-use, but the purpose is so self-evident that alternatives are implied. Slight gap in not stating when to choose this over create/update/delete variants, but adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds a critical behavioral detail: 'This creates a new copy of the message in the destination folder and removes the original message.' This goes beyond the annotation by explaining the exact side effect. It also adds the tip about well-known folder names, which clarifies behavior for destination resolution. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences plus a single emoji-prefixed tip. The core purpose is stated in the first sentence, the key behavioral consequence in the second, and the tip is genuinely useful. No filler or redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive move operation with no output schema, the description covers the essential semantics: what it does, where it moves, and how to specify the destination. It does not mention return values, but the confirm parameter is separately documented in the schema, and the destructive nature is already annotated. An agent has enough to invoke it correctly, though it could benefit from a note about the confirm gate when enabled, but that is covered in the confirm parameter description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% and the schema already documents most parameters (e.g., messageId, confirm). The description adds semantic value by clarifying that DestinationId accepts either a folder ID or a well-known name (inbox, drafts, etc.), which is not evident from the schema's bare 'type: string'. This is a meaningful addition beyond the structured definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Move a message to another folder within the specified user's mailbox.' It immediately distinguishes from siblings like copy-mail-message by explicitly stating it removes the original. This leaves no ambiguity about what the tool does relative to other mail operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description never names alternative tools or gives exclusions. It implies when to use it based on the semantic of 'move' (removes original) but does not explicitly say 'use this instead of copy-mail-message when you want the original gone.' The tip about DestinationId is operational but not about tool selection. This is adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is established. The description adds the detail that move and rename can be combined and specifies how to set them, but it does not disclose potential failure modes (e.g., conflicts) or side effects. Given the annotations, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: one clear sentence plus a compact tip. The core purpose is front-loaded, and the instruction is efficient without filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description covers the main usage patterns but does not mention the confirm parameter (though described in schema) or what happens on success. It is adequate for an agent to call correctly, but slightly incomplete for a comprehensive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies the operational meaning of body.parentReference (for moving) and body.name (for renaming), which is not explicit in the schema. With 83% schema coverage, the schema already documents the properties, but this guidance adds value by linking them to the intended actions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Move or rename a OneDrive item' with a specific verb and resource, and the tip clarifies that it handles move, rename, or both. This clearly distinguishes it from sibling tools like copy-drive-item or delete-onedrive-file, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs how to perform each operation: 'To move, provide parentReference with the target folder's id. To rename, provide a new name.' It also notes both can be done in a single request. It does not explicitly mention alternatives or when not to use, but the guidance is clear and contextual for this tool's intended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the core behavior (removing from cache) but does not mention potential side effects (e.g., whether it invalidates tokens, requires re-authentication, or affects active sessions). For a simple cache operation, this is minimally 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and input format, followed by a useful usage hint. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no output schema, and no annotations, the description covers what it does, what input to provide, and how to find that input. It could mention post-removal consequences, but given the simplicity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a clear parameter description ('Email address or account ID of the account to remove'). The tool description adds value by providing an example format (user@outlook.com) and a discovery hint (list-accounts), going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Remove a Microsoft account from the cache') and specifies the accepted input format (email or account ID). It clearly differentiates from sibling tools like list-accounts and select-account by focusing on cache removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent to use list-accounts to discover available accounts, providing a clear prerequisite. It does not explicitly state when not to use it (e.g., versus logout), but the context of cache removal is inferred, making this adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds valuable behavior: it explains that MIME format saves the message in Sent Items, and that JSON format supports file attachments in the same call. These specifics go beyond the annotations and help the agent anticipate consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise but contains a non-actionable link ('see here') and an irrelevant backend-information sentence. The critical tip is highlighted and front-loaded, which is good. However, the link is a dead end and the backend note adds little for an agent. Overall it is acceptable but not tightly focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a very large, nested schema, the description covers the essential context: format options, attachment handling, default SaveToSentItems behavior, and the practical tip about recipient addresses. It does not describe response format, but there is no output schema, and the confirm parameter is self-documented in the schema. The description is sufficient for safe and effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema description coverage, the schema already documents many fields. The description adds meaning that the schema lacks by explaining the two request body formats (JSON vs MIME) and their implications (attachment support, Sent Items behavior). The tip about using list-users for recipient addresses also guides parameter construction, going beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Send' and the resource 'the message specified in the request body.' It distinguishes this tool from sibling mail actions by explicitly mentioning JSON vs MIME formats and the alternative of creating a draft. The purpose is unambiguous and unique among the many mail-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: 'Send the message' and when to consider creating a draft ('Alternatively, create a draft message to send later'). It also gives a crucial operational guideline: 'Do not try to guess the email address of the recipients. Use the list-users tool.' This effectively routes the agent to a specific workflow, though it doesn't explicitly compare to send-draft-message.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful behavioral context: the zero-based row index and the exact body format ({ values: [[...]] }). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise lines, front-loaded with the purpose and followed by a focused tip. Every word contributes value; no fluff or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update operation with no output schema and high schema coverage, the description is adequate. It covers the essential body format and indexing. A minor gap: it does not explicitly state that the row contents are fully replaced (versus partial updates), but this is reasonably inferred from the term 'update' and the body structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (88%), so most parameters are self-explanatory, but the body parameter is an untyped object in the schema. The description compensates by specifying the required structure ('values' array with one inner array matching column count) and clarifying that 'index' is zero-based.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an Excel table row') and the resource (a single row in a formal Excel table). It also clarifies the indexing scheme (zero-based) and the specific body structure, which differentiates it from sibling tools like add-excel-table-rows and delete-excel-table-row.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing row in a formal Excel table, but it does not explicitly contrast with sibling tools or provide conditions like 'use this instead of add-excel-table-rows when modifying existing data.' The tip adds operational detail but no alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds useful behavioral context beyond annotations: it clarifies that only the role property is writable (other body fields ignored) and provides an alternative workflow for changing other fields. Annotations already indicate destructiveness (destructiveHint=true), and the description does not contradict this. It adds value by explaining the constraint and the delete+recreate path.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise and front-loaded with the purpose. The tip block is organized but the misleading role list adds unnecessary length and confusion. It is not overly verbose, but the inaccurate enumeration wastes space and could mislead.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the core workflow, the writable-only-role constraint, and the alternative for changing other properties. It does not describe the response (no output schema) but that is not expected. The main gap is the incomplete role list, which undermines completeness for valid use cases. The confirm gate is described in the schema, so that is covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% and the schema already documents parameters, but the description actively misleads: it lists only four role values ('read', 'write', 'delegateWithoutPrivateEventAccess', 'delegateWithPrivateEventAccess') while the schema allows eight enum values including 'none', 'freeBusyRead', 'limitedRead', and 'custom'. This false restriction could prevent an agent from using valid roles. The statement 'Only the role property is writable' is helpful, but the role list error is a significant negative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Update my calendar permission') with a specific verb and resource, and distinguishes itself by mentioning 'existing share recipient or delegate' and contrasting with delete+create for other properties. It differentiates from sibling tools like delete-my-calendar-permission and list-my-calendar-permissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (update an existing permission) and when not (to change email or other properties, delete and recreate). It also provides the prerequisite of getting the permission id via list-my-calendar-permissions. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive (destructiveHint=true). The description adds critical behavioral detail: the requirement for an If-Match header and the 412 failure mode if missing, plus how to obtain the ETag. It also lists priority values, though the schema already documents them. This adds context beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for the purpose and a critical tip. The tip is front-loaded and every word earns its place. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, 3 required, and no output schema, the description covers the most critical operational detail (If-Match) and priority semantics. It does not mention that only certain fields are updatable or that read-only fields will be ignored, but the rich schema descriptions mitigate this. Overall, sufficient for correct basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so the baseline is 3. The description adds value by explaining why If-Match is required and how to get the ETag from get-planner-task with includeHeaders=true. It also provides a quick priority mapping, even if partially redundant with the schema. This helps an agent understand the parameter's purpose and preconditions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('plannerTask object'). It distinguishes from siblings like create-planner-task and get-planner-task by implying an existing task is being modified. The short description 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool versus alternatives such as update-planner-task-details, which could overlap. The tip about the If-Match header is valuable but focuses on a precondition rather than selecting the right tool. Usage context is implied but there are no exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write and destructive behavior (readOnlyHint=false, destructiveHint=true), so the description doesn't need to restate that. It adds context about which properties can be modified and the source of required IDs, which goes beyond the annotations. However, it does not mention confirm gating (though that is in the parameter schema) or any side effects, which is acceptable given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight two-sentence structure: first the core purpose, then a concise tip with concrete use cases and dependencies. There is no unnecessary detail, and the most critical information (what it updates and how to find the IDs) is front-loaded. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a large nested schema and no output schema, the description covers the essential operational context: purpose, specific property changes, and prerequisite IDs. The schema covers field-level details, and annotations cover the safety profile. It does not mention partial update semantics or response behavior, but these are either inferable or not critical for correct invocation, so the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 83% schema description coverage, the baseline is 3. The description adds practical value by demonstrating how to use the body parameter (e.g., { status: 'completed' }) and explaining that todoTaskListId and todoTaskId come from specific list operations. These examples clarify the meaning of the body structure and ID parameters beyond the schema's generic property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 'todoTask object,' and provides concrete examples of common operations (mark complete, reopen, rename, change due date, etc.). It distinguishes this tool from siblings like update-todo-task-list, which targets a different resource, and from create/delete operations. The purpose is unambiguous and immediately actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage scenarios (e.g., 'Use this to mark a to-do item complete or done') and specifies the required IDs from list-todo-task-lists and list-todo-tasks. It does not explicitly mention alternatives or when not to use it, but the examples and dependencies strongly imply this is the tool for modifying an existing task. This is strong guidance, though a brief note about alternatives would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, indicating a write operation. The description adds valuable context beyond this: it specifies that folders are created at the root (top-level) and that isHidden can only be set at creation time. It does not mention side effects or error scenarios, but given the annotation coverage, a 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a concise tip line. The main purpose is front-loaded, the hidden-folder condition is immediately relevant, and the tip efficiently lists alternatives and prerequisites. No redundant words or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation, the combination of description and schema provides enough information: the description states the operation and location, and the schema details all body properties (including displayName and isHidden). However, the description does not explicitly state that displayName is typically required (it's not marked required in the schema), nor does it mention potential error cases. Given that the agent can infer from the schema, but the omission of a required-field note is a gap, a 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (body lacks a direct description, while confirm, includeHeaders, and excludeResponse have descriptions). The description adds the isHidden nuance (that it must be set on creation), but it does not clarify which body properties are essential (e.g., displayName). The schema itself describes the subproperties, so the description provides some value but does not fully compensate for the missing body description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('create a new mail folder'), the resource ('mail folder'), and the location scope ('in the root folder of the user's mailbox'). It clearly distinguishes from the sibling 'create-mail-child-folder' by noting it creates only top-level folders, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (for top-level folders) and provides alternatives: 'Use create-mail-child-folder to create a subfolder inside an existing folder' and 'Use list-mail-folders to find existing folder IDs.' It also gives a conditional instruction ('If you intend a new folder to be hidden, you must set the isHidden property to true on creation'). This is clear when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (destructiveHint=true, readOnlyHint=false) already establish this is a mutating operation, and the description does not contradict them. Beyond annotations, it enumerates the eight supported actions (moveToFolder, copyToFolder, forwardTo, forwardAsAttachmentTo, delete, markAsRead, markImportance, stopProcessingRules), giving the agent concrete knowledge of what the tool can do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in the first sentence, followed by a compact tip and example. It is not verbose and every element (example, action list) earns its place, though the action list could arguably live in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a deeply nested body object, the description covers the actions fully and gives a representative conditions example. It does not enumerate all possible conditions, but the schema already documents those, so the description adequately complements the structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so a baseline of 3 applies, but the description adds genuine value by providing a complete inline example payload (displayName, sequence, isEnabled, conditions.fromAddresses, actions.moveToFolder) that clarifies the nested structure beyond what the schema alone communicates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Create a messageRule object') and explains the rule's behavior (Outlook carries out actions on inbox messages matching conditions). This clearly differentiates it from siblings like create-mail-folder, update-mail-rule, and list-mail-rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The TIP section gives actionable guidance: use the Inbox folder ID from list-mail-folders, and it shows a representative body payload. It doesn't explicitly state when not to use this tool or name update-mail-rule as the alternative for modifying existing rules, but it does point the agent to the correct folder-ID source.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'create' aligns with them. Beyond annotations, the description adds useful behavioral context: it shares the primary calendar, specifies the body structure, and notes the return value (id for subsequent operations). It doesn't disclose potential side effects like overriding existing permissions, but the given context is sufficient given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise purpose sentence followed by a tip that includes an example and related guidance. The tip is informative but could be slightly trimmed (e.g., the example contains placeholder names and addresses that could be abbreviated). Still, every sentence carries useful information, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects for an agent: what it does, the exact body structure, the role values, and the return value. It also provides a practical hint to resolve recipient SMTP via list-users. Minor gaps include no mention of side effects on existing permissions or the confirm parameter, but these are covered by schema and annotations. Overall, it's adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already documents most parameters. The description adds value with a concrete example body including emailAddress, role enum values, and other fields. It also clarifies the role options ('read' | 'write' | 'delegateWithoutPrivateEventAccess' | 'delegateWithPrivateEventAccess'). This goes beyond the schema's generic enum by showing a realistic payload.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create a calendarPermission resource'), the resource type, and the purpose (specify identity and role for sharing/delegating a calendar). The tip further clarifies it's the user's primary calendar, which distinguishes it from other calendar-related creation tools like 'create-calendar'. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: 'Shares the user's primary calendar with another user (or sets up a delegate)'. It also gives a prerequisite ('Use list-users to resolve the recipient SMTP') and ties the returned id to update/delete operations, implying when to use this vs alternatives. However, it doesn't explicitly state when not to use it or mention alternatives like creating permissions for other calendars, which would make it fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral details beyond the annotations: specifying both comment and body returns a 400 error, supplying Message.body replaces the whole draft body (excluding quoted history), and signatures are added by Outlook client not via Graph. It also explains the MIME encoding requirement. These details complement the annotations (destructiveHint: true) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-organized: a clear opening statement, bullet points for JSON and MIME formats, and a tip at the end. It front-loads the core purpose and uses structure to separate concerns. Some redundancy exists (e.g., repeating the 400 error), but overall it is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested object schema and the absence of an output schema, the description covers the essential information an agent needs: format options, key constraints, recipient behavior, and the body replacement caveat. It does not detail MIME header specifics, but that is likely peripheral for draft creation. The description is sufficient for correct invocation in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (80%), but the description enhances understanding: it clarifies the relationship between Comment and Message.body, the constraint on specifying both, and the use of replyTo vs from recipients. It also explains the messageId parameter's expected format. This goes beyond the schema's bare property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Create a draft to reply to the sender and all recipients of a message.' It distinguishes this from related tools like create-reply-draft (which replies only to sender) and create-forward-draft, and mentions two formats (JSON/MIME). The verb and resource are explicit, and the scope (reply-all) is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides substantial guidance: when to use JSON vs MIME, the constraint not to specify both comment and body, and the rule about using replyTo recipients per RFC 2822. It also mentions the alternative of doing a single-action reply-all. However, it does not explicitly name sibling tools like create-reply-draft for comparison, so the when-to-use distinction is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, potentially destructive operation. The description adds crucial behavioral context: it returns a pre-authenticated uploadUrl and the server does not perform the PUT, meaning the caller is responsible for the actual upload. This goes beyond the annotations and is essential for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. The tip and path example are brief and directly useful, with no wasted words. Although it could be trimmed, every sentence adds necessary operational detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a two-step upload process and no output schema, the description adequately explains the return value (uploadUrl) and the caller's responsibility to PUT. It also covers the path for new files and optional body. It could mention potential errors or required headers for the PUT, but the core usage is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 83% schema description coverage, most parameters are already documented in the schema. The description adds value by showing an example body with conflictBehavior and explicitly stating the body is optional. This aids in constructing correct parameters without repeating the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb and resource: 'Create an upload session.' It also differentiates from the Outlook attachment session by noting it is for large files with no size limit and no minimum, making it distinct from the sibling tool. The path example further specifies usage for new files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with the Outlook attachment session ('unlike the Outlook attachment session'), providing a scoping condition. It also gives a concrete path for new files and notes the caller must PUT bytes, which is critical usage guidance. However, it does not explicitly state when not to use this tool beyond implying the alternative for smaller files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the safety profile is known. The description adds that dismissal prevents re-firing and requires no body, which adds behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The purpose is front-loaded, and the tip provides extra usage context without bloating.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter, a fully documented schema, and destructive annotations, the description covers purpose, usage, and pairing. No missing information an agent would need to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, including the confirm gate and eventId naming. The description adds no additional parameter semantics, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (dismiss), the resource (a triggered reminder for an event), and the effect (won't re-fire). It distinguishes from siblings like snooze-calendar-event-reminder by focusing on dismissal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit pairing guidance with list-calendar-events or get-schedule to find active reminders. Does not explicitly state when not to use (e.g., snooze instead), but the action is specific enough that 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write/destructive operation. The description adds useful behavioral detail: it forwards the meeting request, notifies the organizer when forwarding from an attendee's mailbox, and adds the recipient to the organizer's copy. It also notes the Outlook.com limitation. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into a clear statement of action, side effects, and a tip. It's a bit redundant (the tip repeats some info) but remains readable and front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the main operation, side effects, and body format. It doesn't mention the return value, but that may be less critical. It also doesn't mention permissions, which are implicit for calendar operations. Overall quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly shows the body structure: '{ ToRecipients: [{ emailAddress: { address, name } }], Comment (optional) }', which complements the schema and clarifies that Comment is optional. With 80% schema coverage, this adds meaningful guidance beyond the schema for the key body parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action forwards a meeting event to a new recipient, using specific verbs 'forward' and resource 'meeting event'. It also explains side effects (notifying organizer, adding recipient), which helps distinguish it from email-forwarding tools like forward-mail-message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 (forwarding meeting requests) and notes an important limitation (not available for Outlook.com accounts). However, it doesn't explicitly name alternative tools or state when not to use it beyond the account limitation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 that the tool returns expanded recurring event instances (not just seriesMaster), which is a specific behavioral trait not in the annotations. It also notes the requirement for date parameters. No contradiction with annotations; it complements them with useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by a tip and alternative routing. It is somewhat lengthy with multiple sentences, but each sentence adds value (e.g., expanded instances, required params, filter usage). The emoji and line breaks aid scanning. It remains concise given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and 15 parameters, the description covers the key context: what items are returned, the calendar scope, required parameters, and common filter patterns. The schema handles parameter details. Missing details like pagination behavior are addressed in the schema descriptions, so the description plus schema is largely complete. A mention of default pagination could be added, but the current set is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage—every parameter has a rich description (e.g., top, skip, fetchAllPages, timezone). The tool description reinforces usage of $filter and $count but does not add new per-parameter meaning beyond what the schema already provides. Baseline 3 is appropriate given the strong schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('get') and the resource ('occurrences, exceptions, and single instances of events in a calendar view') and distinguishes it from the sibling get-specific-calendar-view ('if you need a non-default calendar'). The purpose is unambiguous and differentiation is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the required parameters (startDateTime and endDateTime), gives formatting guidance (ISO 8601), and provides routing to an alternative ('Use get-specific-calendar-view if you need a non-default calendar'). It also offers practical filtering examples for Teams meetings and subject search, making it clear when to use those options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 cover safety. It adds valuable context beyond annotations by explaining the POST call behavior, request body format, and the fact that it returns a mailTips collection per recipient. It does not detail errors or permissions, but these are less critical given the read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, and the tip paragraph is practical but somewhat lengthy. Every sentence contributes useful information (purpose, body example, return format, usage suggestion), though it could be tightened. It is not over-verbose and maintains good structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested body object and no output schema, so the description carries the burden of explaining request and response. It covers the body format, MailTipsOptions values, and return contents ('mailTips per recipient'). It does not address edge cases like invalid recipients or error handling, but for a read-only tool with clear annotations, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (only includeHeaders and excludeResponse have descriptions). The description compensates by explaining the body structure with a concrete example: EmailAddresses array and MailTipsOptions as a comma-separated subset of allowed values. This gives agents guidance on how to construct the required body, adding significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves MailTips for recipients as seen by the signed-in user. It gives a specific verb (get) and resource (MailTips), and the tip section explains concrete use cases (auto-reply/OOF, quota, external recipient, DL). This distinguishes it from any sibling tools, none of which cover MailTips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip explicitly says to use it 'before sending an email' and recommends it for short-circuiting urgent emails when a recipient is OOF or warning before fanned out to a large DL. It gives clear when-to-use guidance, though it does not mention alternatives or when-not-to-use. Since no sibling tool competes directly, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 valuable behavioral context by explaining that the profile resource has navigation properties that can be requested separately, and that $expand can be used to inline them. It also transparently flags the tool as beta, which is helpful information for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized but front-loaded with the main purpose in the first sentence. The following tip is concise and actionable, and the reference to 'methods exposed by profile' is a helpful pointer. It is not overly verbose, though it could be trimmed slightly for maximum clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description reasonably focuses on usage rather than return format. Annotations handle the safety profile, and the description explains navigation properties and expand/select usage. The only minor gap is the slight inconsistency between 'for a given user' and the subsequent 'signed-in user' clarification, but given the tool name, this does not significantly impede correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The description goes beyond by providing practical guidance for the expand parameter (e.g., '$expand=skills,projects') and clarifies that select is for ordinary fields. This enriches the parameter semantics beyond what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve) and the resource (the properties and relationships of a profile object). It explicitly distinguishes itself from the sibling get-current-user by noting it is 'richer', which aids the agent in selecting the correct tool. The first sentence is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description directly compares with get-current-user ('a richer object than get-current-user') and gives concrete advice on using $expand with an example. It also points to the 'methods exposed by profile' for further reference. It lacks an explicit 'when not to use' list, but the comparison is sufficient for most selection scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context by noting the @odata.etag in the response and its necessity for updates, which is not covered by annotations. It also clarifies that the tool retrieves both properties and relationships, going beyond the minimal 'read' hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact—one concise sentence stating the purpose, followed by a bulleted tip that is directly relevant. No fluff or redundancy; the essential information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward get-single-object tool with read-only annotations and full schema coverage, the description is complete. It covers the core function, mentions the etag for subsequent update operations, and the schema handles all parameters. There is no output schema, so no return structure needs explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all six parameters are already well-documented in the schema. The description does not add new meaning to parameters beyond echoing the includeHeaders tip and the etag relevance. It adds some value by highlighting the includeHeaders parameter's purpose in the tip, but this is marginal given the schema already explains it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve the properties and relationships of plannerTask object.' This is a specific verb and resource, distinguishing it from sibling tools like list-planner-tasks or get-planner-task-details. 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip is directly actionable: it advises saving the @odata.etag from the response for later use with update-planner-task, and suggests using includeHeaders=true to capture it. This gives clear context on how to use the tool effectively and connects it to the update workflow, though it doesn't explicitly contrast with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it explains expanded recurring instances, includes seriesMasterId and type fields, warns about large payloads with fetchAllPages, and mentions Teams meeting joinWebUrl property. This goes beyond the annotations and helps the agent anticipate behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by a clearly separated tip section. While it is relatively long, each sentence provides actionable information (e.g., required params, expansion behavior, filtering options). The structure is clear and avoids redundancy, though it could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains what the response includes (expanded instances with seriesMasterId and type). It covers required parameters, pagination advice, and specific filtering for Teams meetings. Given the tool's complexity (16 params) and the openWorldHint, the description is reasonably complete, though it doesn't mention error handling or timezone defaults (which are in the schema).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema alone documents all 16 parameters. The description adds practical advice on top of the schema, such as using fetchAllPages for many events, filtering for Teams meetings, and interpreting seriesMasterId/type fields. This enhances parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List the occurrences, exceptions, and single instances of events') and the resource ('from one of the signed-in user's calendars addressed by calendar ID'). It differentiates from siblings by highlighting that it returns expanded recurring event instances (not just seriesMaster), which sets it apart from other calendar listing tools like list-specific-calendar-events or get-calendar-view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage guidance: requires startDateTime and endDateTime, suggests fetchAllPages for many events, and gives a $filter example for Teams meetings. However, it does not explicitly contrast against sibling tools (e.g., 'use this instead of get-calendar-view when you need expanded instances'), leaving some room for inference. The tip partially fills this gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds critical behavioral context: the use of @odata.deltaLink for incremental sync, the ~30-day expiration with 410 Gone handling, and the recommendation to use $select. These go beyond annotations, though it does not restate the read-only nature (already annotated) or detail pagination beyond fetchAllPages param description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the core purpose front-loaded, followed by a clearly separated tip block. It is slightly verbose but every sentence contributes value (explaining delta process, usage, and alternative). No fluff, but could be more concise by trimming the first paragraph, though it serves as an explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of delta sync, the description covers the essential aspects: initial vs incremental calls, deltaLink usage, expiration, and the alternative tool. It does not explicitly mention pagination via @odata.nextLink (though fetchAllPages is in schema), but the delta concept is thoroughly explained. Overall, adequate for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers 100% of parameters with clear descriptions. The description adds a tip about using $select to limit fields, but does not add meaningful semantics for parameters like startDateTime/endDateTime beyond the schema. Since the schema handles parameter documentation adequately, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get a set of event resources') and the resource ('calendarView of the user's primary calendar'), and explicitly distinguishes from sibling list-calendar-view-delta by noting the alternative for time-bounded views. It also explains delta semantics (added/deleted/updated), 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the delta sync workflow (initial full sync, incremental follow-ups) and provides explicit usage guidance: use $select to limit fields, handle delta expiration (~30 days) with 410 Gone, and explicitly names the sibling list-calendar-view-delta as the alternative for time-bounded views. This is thorough and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds value by stating it returns specified fields, supports $filter/$top/$orderby, and warns that contact folders are usually flat—context beyond the annotations. It does not contradict annotations, but could mention pagination behavior more explicitly, though parameters already cover that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of two sentences plus a tip. It is front-loaded with the core purpose, then adds a helpful usage tip and a note about flat folders. It is concise without unnecessary fluff, though the tip could be slightly trimmed to be even more direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 12 parameters (1 required) and no output schema, the description provides sufficient context: it tells the agent what it returns, how to traverse from top-level folders, and what OData capabilities exist. It does not explain error conditions or edge cases like empty results, but that's minor given the read-only nature and parameter documentation. It feels complete enough for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all 12 parameters, including the required contactFolderId. The description does not add parameter-level meaning beyond what the schema provides—it only mentions supported OData operators. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get a collection of child folders under the specified contact folder.' It clearly distinguishes itself from sibling list-contact-folders (top-level) and list-contact-folder-contacts (contacts, not folders) by focusing on child folders and even mentioning returned fields (id, displayName, parentFolderId).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip explicitly says to use list-contact-folders to discover top-level folders, then this tool to traverse one level deeper. This provides a clear when-to-use and routes the agent to the correct sibling. It also notes that Outlook typically keeps folders flat but Graph allows nesting, which sets expectations for when this tool is relevant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details beyond that: the return is nullable, returns empty for unsupported types, and URLs are short-lived. These are useful and not redundant with annotations. It doesn't contradict annotations and adds context about the output lifecycle.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: a definition sentence plus a tip block. It repeats some information (the definition says "Collection of thumbnailSet objects" and the tip restates "Lists thumbnail sets"), but the tip adds new practical details. It's front-loaded with the purpose and keeps guidance efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with standard OData query parameters, the description covers the essential behavior: what it returns, how to narrow results, and edge cases. It doesn't elaborate on pagination semantics, but the schema parameters (top, skip, fetchAllPages) handle that. No output schema exists, so the description's coverage of the return shape (thumbnail sizes) is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented. The description adds value by giving concrete examples for $select and $expand (e.g., $select=small,medium,large) and explains the thumbnail sizes available, which helps the agent form correct queries. This goes beyond the schema's generic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: "Lists thumbnail sets for a file" with specific details on the thumbnails (small, medium, large sizes, URL and dimensions). It distinguishes from siblings like get-drive-item by focusing exclusively on thumbnail sets, and even notes the behavior for unsupported types (text docs). This is a specific verb+resource definition, not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: how to request specific sizes via $select or $expand, and warns that URLs are short-lived. It also implicitly advises against using this for text docs by stating it returns empty. However, it doesn't explicitly name alternative tools for non-thumbnail needs or draw comparisons to siblings like list-drive-item-versions. Still, the context is sufficient for an agent to know when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value beyond annotations by disclosing that search folders are included, hidden folders are excluded by default, and only direct child folders are returned. These are meaningful behavioral traits not present in the annotations, and there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a few focused, well-structured sentences. It front-loads the core purpose, then clarifies the scope (only root children) and the hidden-folder option. It avoids redundancy and earns each sentence; only minor trimming could tighten it further.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with no output schema, the description covers the essential context: what is returned, the scope limitation, hidden folder behavior, and guidance for retrieving the full mailbox. The rich schema and annotations cover the rest, making it sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 12 parameters have rich descriptions in the schema (100% coverage), so the description carries no additional parameter-level semantics. It does not restate or supplement the schema, which is appropriate; baseline 3 applies when the schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool gets the mail folder collection directly under the root folder of the signed-in user, includes search folders, and explicitly notes that it does not return all folders—only child folders of the root. This differentiates it from sibling tools like list-mail-child-folders and provides a precise, resource-specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: mentions the includeHiddenFolders query parameter to opt into hidden folders, and states that to return all mail folders in a mailbox, the agent must traverse each child folder separately. This effectively tells when to use this tool and when to drill further, implicitly pointing to list-mail-child-folders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and non-destructive hints, so the description adds value by disclosing default behavior: returns top 20 ordered by lastModifiedTime desc, supports $filter, $top (max 100), $select, and $expand for parentNotebook and parentSection. It also notes it is a transverse (non-hierarchical) query. This goes beyond the annotations and gives the agent useful expectations, though it does not address pagination or return format explicitly (the schema already covers pagination hints).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but front-loaded with the core purpose and then adds a tip, defaults, supported operations, and a clear alternative. Each sentence conveys distinct value, but it could be tightened by folding the tip into the main guidance. The structure is reasonable for a tool with 11 parameters and a need to differentiate from siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 optional params, no output schema), the description covers the essential context: purpose, scope, default ordering, supported OData options, and when to use alternatives. It doesn't describe the exact structure of returned page objects, but that is not required without an output schema. It also does not explicitly mention pagination via nextLink, though the schema's 'top' description does. Overall, an agent has sufficient information to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a detailed description (e.g., 'top' advises small values and nextLink usage). The tool description adds context for expand (parentNotebook, parentSection) and provides filter examples, but these are brief and largely restate OData capabilities already implied by the schema. The description does not significantly enhance parameter understanding beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a list of page objects' and then specifies it lists all OneNote pages across every notebook and section, explicitly positioning it as a 'transverse alternative' to walking the hierarchy. It also names the sibling tools it replaces and gives a concrete use case ('when you have a topic in mind'). This fully distinguishes it from the hierarchical navigation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use this instead of bouncing through list-onenote-notebooks / list-all-onenote-sections / list-onenote-section-pages when you have a topic in mind.' It implies when the hierarchical tools would be preferred (walking the tree) and gives examples of filters that suit topic-oriented searches. This is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false; the description adds valuable behavioral context: $select returning 400, status value enumeration, pagination via @odata.nextLink, and the warning about $top size for context. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a main statement and a 'TIP' block, front-loading the core purpose. It is verbose but each sentence contributes practical guidance (status values, filter syntax, pagination). Slightly long but appropriately detailed for a 12-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, no output schema, and only one required param, the description plus schema provide a complete picture: how to get the list ID, how to filter, how to paginate, what to avoid, and response hints. Missing only minor aspects like potential error scenarios beyond $select, but overall comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3), but the description and per-parameter schema add significant extra semantics: the $select unsupported warning, advice to start with small $top values, and the clarification that todoTaskListId must be passed by that name, not 'id'. These go well beyond the schema's raw definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Get the todoTask resources from the tasks navigation property') and clearly distinguishes from sibling tools by naming list-todo-task-lists as the way to obtain the required ID. 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains how to find the required todoTaskListId using list-todo-task-lists, and provides crucial usage notes (e.g., $select NOT supported, recommended $filter expressions, $top guidance). Does not fully contrast with sibling get-todo-task or create-todo-task, but the context is strong enough for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and openWorldHint=true, but the description adds meaningful behavioral details: it mentions that specifying both comment and body results in HTTP 400, describes replyTo handling per RFC 2822, states that the message is saved in the Sent Items folder, and offers the draft alternative. It does not contradict annotations and provides beyond-annotation context about error conditions and delivery behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear bullet points for JSON and MIME formats, and a tip at the end. It is moderately long but each section conveys necessary information about constraints and usage. The primary purpose is front-loaded, and the alternative draft approach is mentioned early. While it could be slightly trimmed, it remains well-organized and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (two formats, many possible message properties, no output schema), the description covers essential invocation details: required parameters (messageId, body), format-specific requirements, error conditions, and the saving behavior. It does not describe the response structure, but since there is no output schema and the tool returns a message object (per typical Graph API), the lack of explicit return documentation is acceptable. The description is sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 80% of parameters with descriptions (e.g., messageId, confirm, includeHeaders). The description adds critical semantics for the 'body' object by clarifying the mutually exclusive constraint between 'Comment' and 'Message' (body) and the replyTo precedence rule. For MIME format, it specifies base64 encoding and header/content requirements, going beyond the schema's generic object definition. This helps the agent avoid common mistakes (e.g., sending both fields).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear purpose: 'Reply to all recipients of a message using either JSON or MIME format.' This is specific (replies to all recipients, not just the sender), mentions two explicit format options, and distinguishes it from sibling tools like 'reply-mail-message' (which likely replies to a single recipient) through context. The name is also descriptive, but the description adds the format dimension and clarifies the scope (all recipients).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical usage guidance by contrasting with creating a draft: 'Alternatively, create a draft to reply-all to a message and send it later.' This gives an alternative for deferred sending. It also differentiates between JSON and MIME usage scenarios, including when to use 'comment' vs 'body'. However, it does not explicitly state when to use this tool over sibling 'reply-mail-message' (single reply) or 'reply-all' vs 'reply' distinctions, relying on the tool name for that differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the action 'select as default,' which implies a persistent state change, but does not disclose side effects (e.g., whether the previous default is replaced, whether authentication is required, or if the change is reversible). For a state-modifying tool with no annotation coverage, this is a moderate gap—not misleading, but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core purpose is front-loaded, followed by accepted formats and a pointed reference to a sibling. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description covers purpose, accepted input, and a discovery path. There are no nested objects or complex edge cases to disclose, so it is complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the parameter description already states 'Email address or account ID'). The description adds a concrete example (user@outlook.com) and a discovery mechanism (use list-accounts), which goes slightly beyond the schema. It adds value by giving the agent a way to find valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Select a Microsoft account as the default.' It also specifies the accepted identifier forms (email or account ID) and provides a concrete example. This clearly differentiates it from siblings like list-accounts (which discovers) and logout (which ends a session).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use list-accounts to discover available accounts, which routes the agent to the right discovery tool. However, it does not state when not to use this tool (e.g., when needing to log in or out) or list alternatives beyond list-accounts. The guidance is clear for the typical flow but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive=true, so the description need not repeat. It adds value by disclosing the tool can set values, formulas, or number format, and clarifies it works on any range (not just tables). The constraint about inner-array count matching column count is also a behavioral detail. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise (~70 words) and well-organized: starts with purpose, then a tip, then usage patterns, then a constraint. Each sentence carries value, though a slight trim could improve. It is front-loaded with the main verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the critical aspects for invocation: what it does, how to format the body, the address format, and usage patterns. It does not explain the confirm gate, but that is documented in the schema parameter. It omits response details but that is acceptable for a mutation tool without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions for parameters are mostly generic ('Value for the address path segment'), so the description compensates by explaining the body format ({ values: [['v1','v2','v3']] }) and giving address examples. It also clarifies the column-count requirement. This adds meaningful context beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an Excel range' and expands on what updates are possible (values, formulas, number format). It explicitly notes it does NOT require a formal Excel table, distinguishing it from table-specific tools like update-excel-table-row. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage patterns: append (target next empty row), update (single cell), and prepend-style edits (read, concatenate, write back). It provides address examples like 'A172:H172' and 'H42'. However, it does not explicitly name alternative sibling tools or state when NOT to use it beyond the table implication, so it falls short of full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark destructiveHint: true and readOnlyHint: false, which the description aligns with ('change', 'save'). The description adds meaningful behavior beyond annotations: it clarifies PATCH semantics ('send only the properties to change'), and notes that only writable properties are affected. No contradiction. The confirm-gate behavior is documented in the schema, not the description, but that's acceptable given 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a well-placed tip. The main purpose is stated first, followed by practical guidance. The tip is a bit long but packed with useful info (how to get folder ID, partial updates, example). No fluff or repetition; it's efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large, detailed schema and no output schema, the description covers the essentials: what it does, how to get the folder ID, partial-update behavior, and a common scenario. It doesn't mention the confirm gate or return fidelity (excludeResponse, includeHeaders), but those are schema-level. For an update tool with a rich schema, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83% (high), so the schema already explains most parameters. The description adds value by explaining how to use the body: 'Send only the properties to change' and gives a common-use example ({ isEnabled: false }). It also reinforces the need for mailFolderId and messageRuleId via the tip. This goes beyond the schema's basic property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('change writable properties'), resource ('messageRule object'), and action ('save the changes'). It clearly distinguishes from create-mail-rule (existing rule) and delete-mail-rule, and the sibling list confirms these alternatives exist. The agent knows exactly what this tool does and when to pick it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Updates an existing message rule', 'Use the Inbox folder ID (get it from list-mail-folders) for inbox rules', 'Send only the properties to change'. It also provides a concrete example (disabling a rule). It does not explicitly name alternatives (e.g., create-mail-rule) but implies the distinction via 'existing', which is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds the crucial behavioral requirement of the If-Match header for optimistic concurrency, which is not conveyed by annotations. It does not contradict any annotations, and the ETag prerequisite is valuable for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one action sentence and a critical tip. The tip is front-loaded and clearly highlights the most important operational detail. No unnecessary words, and the use of emoji is decorative but does not hinder clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested objects, 6 parameters, and no output schema, the description is minimal. It covers the ETag requirement, which is essential, but does not explain whether the body replaces the whole bucket or is a partial update, nor what the response contains. The schema provides some context, but the description could add update semantics and expected return behavior. The lack of this info leaves some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so most parameters are described. The description enriches two parameters: If-Match (explicitly tied to the ETag from get-planner-bucket) and includeHeaders (mentioned as the means to obtain that ETag). This goes beyond the schema's generic 'ETag value' and 'Include response headers' descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update the properties of plannerbucket object', specifying the verb 'update' and the resource. It distinguishes this from sibling tools like create-planner-bucket and delete-planner-bucket by the action, and from get-planner-bucket by the mutation intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a critical usage guideline: it requires an If-Match header with an ETag from get-planner-bucket and tells the agent to use includeHeaders=true. This is practical, action-oriented guidance. However, it does not explicitly contrast this tool with alternatives, though the name and context imply it is for updating an existing bucket rather than creating or deleting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds substantial behavior: the event is moved to Deleted Items, it can cancel occurrences of recurring meetings, it sends a cancellation message, and attendees get an HTTP 400 error. These are behavioral traits not covered by annotations. While the description doesn't explicitly mention the confirm gate parameter, that is documented in the schema. It adds significant context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but somewhat verbose, with a detailed first paragraph and a separate tip. However, it is well-structured: the purpose is front-loaded, then details, then a quick-reference tip. Every sentence adds value, though there is slight repetition of the cancellation purpose between the first paragraph and the tip. Not overly long for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with organizer-only semantics, recurring event support, and error behavior, the description covers all key aspects: what it does, the move to Deleted Items, the custom message, the difference from delete, and the attendee error. No output schema exists, so explaining return values is not required. An agent has sufficient information to decide when and how to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so most parameters are documented. The description only adds a mention of the Comment field in the tip, which is already in the schema. It doesn't provide additional meaning for parameters like eventId or confirm beyond what the schema offers. The baseline for high coverage is 3, and the description doesn't elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: the organizer of a meeting can cancel an event and send a cancellation message. It specifies the resource (calendar event) and the action (cancel), and distinguishes it from delete-calendar-event and decline-calendar-event by noting the organizer-only restriction and the ability to send a custom message. This fully differentiates it from siblings without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool instead of delete-calendar-event (when attendees should see 'Canceled') and directs attendees to use decline-calendar-event instead. It also explains the error condition for attendees, giving clear guidance on when not to use the tool. No inference is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so it's a write operation. The description adds valuable behavioral context: idempotency (creates only if not exists, otherwise returns existing), inheritance of permissions from ancestors, and that it does NOT trigger OneDrive notifications. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured with a tip and clear sections. It front-loads the core purpose and then provides usage context. Minor redundancy (e.g., 'driveItem driveItem' typo) and some tangential info (inheritance) slightly reduce conciseness, but overall it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary use case and return value, but introduces potential confusion: schema includes recipients and sendNotification fields (email-related), yet the description claims this tool does NOT send email. It does not explain why those fields exist or how they interact, leaving an agent uncertain about when to use them. Also lacks error handling or auth requirements, which could be important for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), but the description adds a compact body template with enums for type and scope, plus optional fields (password, expirationDateTime, retainInheritedPermissions). It also clarifies the return value (permission with link.webUrl), which is not in the schema. This extra semantic value lifts it above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a share link for a driveItem, explains the createLink action, and describes idempotent behavior (returns existing link if type exists). It distinguishes itself from share-drive-item by contrasting link-only vs explicit access, so an agent can immediately identify which tool to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: create a link WITHOUT sending an email invitation, and explicitly contrasts with share-drive-item for when explicit access is needed. The tip section gives a concrete body example and notes it returns a webUrl, making usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive (destructiveHint: true) and openWorldHint: true. The description adds behavioral context beyond that: it explains the upsert behavior ('If an override already exists for that SMTP address, POST updates the existing override's name and classifyAs') and clarifies that classifyAs must be 'focused' or 'other'. No contradiction with annotations, and the added context is valuable for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and front-loaded with the main purpose. It includes a practical tip and important constraints (e.g., do not invent addresses). While it's slightly longer than necessary, each part adds value and the structure (description followed by tip) aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested body schema, the upsert behavior, and the need for address resolution, the description is complete. It covers the body format, permissible classifyAs values, behavior on existing overrides, and how to obtain a valid sender address. There is no output schema, but the description doesn't need to explain return values; the essential operational details are all present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 75% of parameters, and the description enriches meaning by providing a concrete body example ({ classifyAs: 'focused', senderEmailAddress: { name: 'Display Name', address: 'sender@example.com' } }) and stating that classifyAs must be one of two values. It also emphasizes resolving the sender's address reliably, which is a key semantic point beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Create an override for a sender identified by an SMTP address' and the effect ('Future messages from that SMTP address will be consistently classified'). It is specific about the resource (Focused Inbox override) and distinguishes it implicitly from sibling tools like update-focused-inbox-override and delete-focused-inbox-override by describing the create/upsert behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: it creates an override and, if one already exists, it updates it (useful for renaming a sender). It also advises resolving the sender's address using list-users or reading a mail header, and explicitly says 'do not invent SMTP addresses'. However, it does not explicitly contrast with the sibling update-focused-inbox-override, so it lacks a direct 'when not to use this' exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns an upload URL and that the caller must perform sequential PUT operations, stating 'This server does not perform the PUT.' It also mentions the error for smaller files. The annotations (readOnlyHint=false, destructiveHint=true) are not contradicted; the description supplements them with the workflow and error scenario.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but organized with a clear explanation, example, and tip. It front-loads the purpose and usage, though it could be more concise by trimming redundant references. The structure is logical but could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the entire workflow: when to use, what to include in the body, that it returns an upload URL, and that the caller performs PUTs. Given there's no output schema, it adequately explains the expected output and next steps. Some details like exact PUT range headers are not covered but are standard for this pattern.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides detailed parameter descriptions (80% coverage), and the description adds a concrete example for the body parameter, showing the structure with AttachmentItem fields. It also clarifies that messageId should be passed as 'messageId' not 'id', reinforcing the schema guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: create an upload session for attaching files to Outlook items (message or event). It explicitly distinguishes from the sibling 'add-mail-attachment' via the 3-150 MB size range, which is a specific verb+resource+scope definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (file size between 3 MB and 150 MB) and when not to (use POST on attachments for smaller files). It also notes the caller must perform PUTs, providing clear context and exclusions. The TIP reinforces the alternative 'add-mail-attachment' for under 3 MB.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations (readOnlyHint: false, destructiveHint: true) by detailing key behaviors: the 400 error when both comment and body are supplied, the note that supplying body replaces the entire draft body so quoted history is lost, the MIME base64 requirement, and that signatures are only added by the Outlook client, not via Graph. These are valuable, non-obvious details that help an agent predict behavior accurately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured with bullet points and clear formatting. It leads with the primary purpose, then details each format, and provides a tip and note. Despite its length, every sentence conveys necessary information; it is appropriately detailed for a complex tool with two distinct input formats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two complex input formats, nested schemas, and error-prone conditions, the description is extremely complete. It covers format selection, header requirements, attachments, error cases, update workflow, and the alternative single-operation reply. No output schema is needed, and the description leaves no obvious gaps for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is high (80%), the description adds meaningful semantics for the body parameter (explaining the Comment vs Message distinction and the error condition) and for messageId (instructing to pass it as 'messageId' not 'id'). It also clarifies that attachments and S/MIME properties go into the MIME content. This adds value beyond the schema's basic property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a draft to reply to the sender of a message in either JSON or MIME format.' It specifies the verb, resource, and formats, and distinguishes itself from siblings like create-forward-draft and create-reply-all-draft by its focus on replying to the sender only. The mention of 'Alternatively, reply to a message in a single operation' further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you want to create a draft rather than send immediately ('Send the draft message in a subsequent operation'), and it mentions the alternative of replying in a single operation. However, it does not explicitly name any sibling tools (e.g., create-reply-all-draft, reply-mail-message) or provide clear exclusions, so the guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description adds critical behavioral details: it deletes all events in the calendar, the default calendar is protected, and the action is irreversible. This gives the agent a complete picture of side effects and consequences, going beyond what structured metadata provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: a single sentence stating the action and constraint, followed by a brief tip with two key consequences. No filler, and the most important information is front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool, the description covers the essential: what it does, the cascade effect, the default calendar restriction, and irreversibility. It does not explicitly mention the confirmation gate or response behavior, but those are already covered in the schema and annotations. Given the moderate complexity and high annotation coverage, this is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all parameters (calendarId, confirm, If-Match, etc.) with descriptions, so the baseline is 3. The description does not add parameter-specific semantics beyond hinting that calendarId must refer to a non-default calendar. Since schema coverage is 100%, the description does not need to compensate, and it adds minimal extra value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), the resource (calendar), and a key constraint (other than the default calendar). It also mentions that it deletes all events, which adds specificity and distinguishes it from other calendar-related tools like update-calendar or delete-calendar-event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that the default calendar cannot be deleted, which tells the agent when NOT to use it. It does not name alternative tools, but this is the only tool for deleting a calendar, so that distinction is sufficient. The guidance is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, so the description carries additional behavioral disclosure. It explains that the folder 'typically lands in Deleted Items rather than being permanently removed,' and that the default folder triggers a Graph error. This goes beyond the annotation by detailing the consequence and exception, which is valuable for an agent deciding to call this tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences and a tip, all tightly packed with relevant information. It front-loads the core purpose and then adds the key caveat and workflow hint. No filler words—every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description covers the main behavioral aspects (default folder exception, Deleted Items behavior) and the prerequisite (get folder id). It doesn't mention response format, but for a delete operation that's less critical, and the schema already includes parameters for controlling the response (excludeResponse, includeHeaders). Given no output schema exists, the description is sufficiently complete for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have thorough descriptions. The tool description adds no new parameter-specific semantics beyond mentioning how to get the contactFolderId via list-contact-folders, which reinforces usage but doesn't expand on the schema. Baseline 3 is appropriate since the schema already documents parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('contactFolder'), and explicitly distinguishes it from the default folder: 'Delete contactFolder other than the default contactFolder.' It also clarifies what the tool does with 'Deletes a contact folder.' This clearly differentiates from siblings like delete-mail-folder or delete-calendar, and the tip reinforces the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it mentions the default folder cannot be deleted and that you should 'Get the folder id via list-contact-folders,' implying a prerequisite workflow. It doesn't explicitly name alternatives but gives enough guidance to avoid misuse. It also warns about the error if trying to delete the default folder, which is a useful usage note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description's 'permanently' adds extra behavioral context beyond what annotations provide. No contradictions with the readOnlyHint=false annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The action is front-loaded, and the tip is concise and directly relevant. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with no output schema, the description covers the essential action and a usage hint. It doesn't describe response format, but that is acceptable given the schema's comprehensive parameter guidance and the straightforward nature of a delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions (100% coverage), and the description adds a useful tip about sourcing mailFolderId from list-mail-folders, which complements the schema's own description without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Delete) and resource (specified messageRule object), and adds 'permanently' to clarify irreversibility. Clearly distinguishes from sibling update-mail-rule by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear that it deletes a message rule; the tip about obtaining the Inbox folder ID from list-mail-folders gives a concrete usage scenario. Does not explicitly mention alternative tools, but the delete purpose is unambiguous and the tip is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, but the description adds a specific behavioral disclosure: deleting a seriesMaster cascades to all occurrences. This is valuable operational context beyond the annotation and helps the agent anticipate side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single declarative sentence plus a succinct tip. Every word earns its place, and the most critical behavioral caveat is placed prominently after the main purpose. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description covers the main side effect (seriesMaster cascade) and points to the correct ID type. It lacks explicit guidance on when to use this vs. siblings, but the schema covers parameter detail and the annotations cover destructive intent. The tool is simple enough that the provided context is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description adds meaning by relating the eventId parameter to seriesMaster versus instance semantics, which is not fully captured in the schema's standard 'id' description. This enhances understanding of how to fill eventId correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a specific calendar event' with a clear verb and resource, and the name includes 'specific' to distinguish from general delete operations. The tip about seriesMaster further clarifies scope (deletes all occurrences when a series master is targeted), which aids selection among the many calendar siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a useful tip about seriesMaster versus instance deletion, implicitly indicating when to use a specific instance ID. However, it does not explicitly state when to choose this tool over alternatives like delete-calendar-event or cancel-calendar-event, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (it modifies) and destructiveHint=true (potentially destructive). The description adds some context by specifying the properties that are set and clarifying that font/fill/borders are excluded. However, it does not mention the confirm gate or any side effects like overwriting existing formatting. It repeats the destructive nature implicitly through the property list but adds limited new behavioral detail 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with a direct purpose, then a valuable tip with the most actionable info (required path param and body properties), and ends with exclusions pointing to siblings. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the relatively simple operation, high schema coverage, and annotations covering safety, the description is fairly complete. It tells the agent what to set, what not to set, and where to go for other formatting. It does not explain return values, but there is no output schema and the operation likely returns a simple success indicator. It omits mention of the confirm parameter (when gate enabled), but that appears in the schema and may be a general pattern across tools. Overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (88%), but the description adds crucial meaning by listing which body properties are actually applied (horizontalAlignment, verticalAlignment, wrapText, columnWidth, rowHeight) and explicitly stating that font, fill, and borders are NOT set here. The address example ('A1:E5' or 'Sheet1!A1:E5') clarifies the format required. This goes beyond the schema's generic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Format an Excel range' and specifies it applies rangeFormat properties. It explicitly lists which properties are set (horizontalAlignment, verticalAlignment, wrapText, columnWidth, rowHeight) and distinguishes it from sibling tools (format-excel-range-font, format-excel-range-fill, format-excel-range-border) by stating what it does NOT handle. This distinguishes it effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'Apply rangeFormat properties to a specific range' and lists the relevant properties. It also gives clear exclusions: 'Font, fill, and borders are NOT set here; use format-excel-range-font, format-excel-range-fill, and format-excel-range-border for those.' This provides both when and when-not guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only.' It goes beyond annotations by disclosing that font, fill, and borders are omitted by default and require the $expand parameter, and it explains why (to interpret cell meaning). This adds valuable behavioral detail not captured in 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus a tip, with the main purpose front-loaded. The tip is actionable and relevant, containing zero fluff. Every sentence earns its place, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only format getter with 9 parameters, the description covers the essential behavioral nuances: nested properties, expansion, and the interpretative value of formatting. It does not detail return format or pagination, but given the absence of an output schema and the read-only nature, it provides sufficient context for an agent to call the tool correctly. A complete picture would explicitly mention that formatting like fill/font colors may convey meaning, which it does, so it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the input schema has 100% coverage with descriptions for all parameters, the tool's description specifically instructs to add 'font, fill, and borders' to the $expand parameter, which is tool-specific and beyond the generic schema description of expand. It also lists concrete properties returned (alignment, wrapText, columnWidth, rowHeight), enriching parameter semantics beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb and resource: 'Returns a format object, encapsulating the range's font, fill, borders, alignment, and other properties.' It clearly distinguishes from sibling tools like format-excel-range (which modifies) and get-excel-range (which presumably returns values), making the purpose unambiguous. The read-only declaration further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for reading a range's format, and it gives practical guidance on expanding nested properties (font, fill, borders) and the semantic significance of cell styling. However, it does not explicitly mention when not to use it or name alternatives like get-excel-range, though the purpose is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not required to restate safety. It adds behavioral context beyond annotations by disclosing that the response includes @odata.etag and that includeHeaders=true is necessary to access it. This is useful for the agent to understand the response contents and how to retrieve the ETag, which is not covered by 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one clear sentence plus a focused tip. The main purpose is front-loaded, and the tip is directly actionable without straying into irrelevant details. There is zero fluff, and every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a read-only getter with well-documented parameters and annotations covering safety, the description is essentially complete. It covers the ETag retrieval workflow, which is the key non-obvious aspect. It doesn't mention response pagination or error scenarios, but those are less critical for a single-object getter, and the absence of an output schema is compensated by the ETag tip.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds cross-referential value by explaining why includeHeaders=true matters: it enables retrieval of the ETag needed for update-planner-task-details. This connects a parameter to a downstream workflow, which is more than the schema alone provides. It doesn't describe every parameter, but the tip reinforces the purpose of a key one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and the specific resource ('plannerTaskDetails object'). It distinguishes from sibling 'get-planner-task' by targeting the details object rather than the task itself, and the name directly reflects the purpose. The one-sentence definition is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The TIP provides actionable guidance: the response includes @odata.etag, which is required for update-planner-task-details, and recommends using includeHeaders=true to get it. This implicitly tells the agent to use this tool before updating details. However, it does not explicitly differentiate from other getter tools like get-planner-task, and it lacks a clear 'when not to use' statement. Still, the cross-reference to a sibling tool is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not required to repeat safety. It adds the key behavioral trait of 'lists all sections across all notebooks', which is valuable scope context beyond the annotations. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero wasted words. The main purpose is front-loaded, followed immediately by a concise routing tip. Highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with no output schema, the description clearly states the resource, scope, and alternative. It does not describe return format or pagination, but those are secondary and parameter-driven. The tool is complete enough for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed parameter explanations in the input schema. The description itself adds no parameter information, so it provides no additional value beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a clear verb ('Retrieve') and resource ('list of onenoteSection objects'), and the tip explicitly contrasts with list-onenote-notebook-sections, so an agent can distinguish it from the sibling without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip explicitly tells the agent when to use this tool (list all sections across all notebooks) and when to use the alternative (list-onenote-notebook-sections for a specific notebook). This provides clear when/when-not guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 valuable behavior: it lists the built-in 'Contacts' folder, mentions that user-created folders also appear, and specifies the returned properties (id, displayName, parentFolderId). This goes beyond the annotation and gives the agent a clear picture of what to expect from the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear main sentence, followed by a 💡 TIP section that enriches without being redundant. It is moderately long but every sentence earns its place—mentioning return fields, default folder identification, and sibling tools. Slight verbosity in the tip, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values, and it does: 'Returns id, displayName, and parentFolderId.' It also covers query parametrization and usage ordering. For a simple list operation, this is fully self-sufficient; an agent knows exactly what it will get and when to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description only mentions 'Supports OData query parameters' without detailing any parameter-specific meaning, relying on the schema's extensive parameter descriptions (which themselves include usage tips like 'Start small' for top). The description adds no new semantic value beyond confirming OData support.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get the contact folder collection in the default Contacts folder of the signed-in user.' It clearly distinguishes the tool from siblings like `list-contact-folder-child-folders` by emphasizing the default folder scope. It also names the return fields, which aids selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this before list-contact-folder-contacts or create-contact-in-folder to discover folder ids,' directly guiding when to select this tool over alternatives. It also explains how to identify the default folder (match displayName === 'Contacts') and notes the built-in folder, providing practical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the readOnlyHint and destructiveHint annotations: it discloses beta status, delegated-only auth (no application permissions or personal accounts), cloud limitations (global only, not GCC/DoD/21Vianet), and describes the response fields (id, content, createdBy, etc.). This is rich and does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a main sentence stating the action, followed by a tip block that packs essential details. It is front-loaded with the purpose and the tip adds valuable caveats. While the tip is dense, it is well-structured and no word is wasted. Slightly verbose due to the extensive caveat list, but acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 12 parameters and no output schema, the description provides a complete picture: response fields, beta status, auth requirements, cloud constraints, and the key distinction from legacy comments. The schema covers parameter details, so nothing critical is missing. An agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with detailed explanations for every parameter (e.g., top, skip, count, expand, filter, search, select, orderby, fetchAllPages, plannerTaskId, includeHeaders, excludeResponse). The description adds only a general tip about using $select to reduce fields, which is already implied by the schema. Since the schema carries the parameter burden, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and the resource 'list of plannerTaskChatMessage objects associated with a plannerTask'. It explicitly distinguishes itself from the legacy conversationThreadId comments, which differentiates it from sibling tools like create-planner-task-message and delete-planner-task-message. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes the distinction between the modern task chat and legacy comments, which guides when to use this tool. It also mentions beta status and auth constraints. However, it does not explicitly name alternative tools for the legacy comments path, though the context implies it. This is clear enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and non-destructive. The description adds valuable behavioral context: it specifies the return format (timeZoneInformation objects with alias and displayName), notes that TimeZoneStandard values are case-sensitive enums, and hints at the output's use for validation. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loading the core purpose and then adding a focused 'TIP' section with critical details. Every sentence adds value: the main description covers purpose and usage, and the tip provides parameter specifics and output expectations. It is concise without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, mostly standard pagination/filtering) and that annotations cover safety, the description provides sufficient context. It explains the tool's unique aspects (format options, output structure, usage validation) while relying on the schema for the standard parameters. The description is complete enough for an agent to call correctly, though it could mention that parameters like $top, $skip, etc. are standard Graph query options—but the schema already handles this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description significantly enhances the TimeZoneStandard parameter by explaining its valid values (Windows vs Iana), the PascalCase requirement, and the default behavior—far beyond the schema's generic 'Value for the path segment.' It also clarifies the output structure, aiding agent interpretation. This added meaning justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the list of time zones supported for the user's mailbox server, with a specific verb ('Get') and resource. It also explains the format options (Windows vs IANA) and the default, which fully clarifies the purpose. No sibling tool performs this action, so it stands out distinctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: to get supported time zones and to validate before updating mailbox settings via update-mailbox-settings. It also mentions that the preferred time zone can be retrieved from mailbox settings, but it does not explicitly state when not to use this tool or compare with alternative tools. The guidance is useful but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, and the description confirms the side effect by noting it 'saves the message in the Sent Items folder' and sends a reply. It also discloses the replyTo precedence rule and the HTTP 400 error condition, adding valuable 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with bullets and sections, front-loading the main purpose. Each sentence carries information; the tip at the end is practical though slightly tangential. It could be tightened, but the structure helps readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mail-reply operation with two formats, multiple constraints, and an alternative workflow, the description covers all key aspects: format selection, parameter constraints, replyTo behavior, save location, draft alternative, and a practical tip. It is complete enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 80% schema coverage, the schema already documents most parameters. The description adds essential semantics by explaining the mutual exclusivity of 'Comment' and 'body' in JSON mode, and by detailing the base64-encoded MIME format requirement—details not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reply to the sender of a message') and specifies the two output formats (JSON and MIME). It distinguishes itself from the related create-reply-draft tool by explicitly presenting the draft alternative, making the tool's unique role apparent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance on when to use JSON vs MIME, the constraint of comment vs body, and replyTo handling. It mentions the alternative of creating a draft, but doesn't explicitly compare to reply-all-mail-message or forward-mail-message, leaving some ambiguity about recipient-scope differences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and destructiveHint false, and the description doesn't contradict this. It adds useful behavioral context by specifying the return fields (id, name, webUrl, size, lastModifiedDateTime) and the drive-id prerequisite, going beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences plus a tip, front-loading the purpose and key usage guidance. No wasted words; each sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (13 parameters with detailed descriptions) and the annotations, the description covers the essential context: what it searches, scope options, return format, and a prerequisite. It doesn't explain every edge case, but it's sufficient for an agent to invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and most parameter descriptions are already detailed. The description adds semantic value for the 'q' parameter (searches file names, metadata, and content) and clarifies the return format, which helps an agent understand what the tool actually does beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for items matching a query within a hierarchy, with explicit scope options (folder, drive, shared files). This is distinct from sibling tools like list-folder-files (listing) and get-drive-item (retrieval by id).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a prerequisite (use list-drives first to get drive-id) and clarifies the q parameter semantics (searches name, metadata, content). While it doesn't explicitly say when not to use it (e.g., when you already know the path), the scope options and tip give adequate context for an agent to choose this over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description does not need to repeat these. The description adds that renewal extends expiration and warns about max limits, which is consistent with the destructive flag. It also reiterates the need to renew before expiry. No contradictions; the description complements annotations with practical timing context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized, with the main purpose in the first sentence. The second paragraph is a helpful tip that front-loads the essential information (body format and timing). The first paragraph includes somewhat generic context about permissions and expiry, which is useful but could be trimmed. Overall, well-structured and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a complex schema and no output schema, the description supplies enough context to call it correctly: it tells the agent to pass the new expirationDateTime before expiry, and to check limits. It does not cover the generic flags like confirm or includeHeaders, but these are likely consistent across tools and not essential for this purpose. The description is complete for the core operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 80% schema coverage, the description still adds significant value by explicitly stating the essential body parameter: 'Body: { expirationDateTime (ISO 8601, new expiry) }.' This clarifies that in the update operation, only the expiry field is required in the body, which is not immediately apparent from the schema that lists many optional properties. Additionally, the description highlights the subscriptionId parameter implicitly by its focus on renewal, and the schema itself clarifies the naming. This goes beyond the schema's existing documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Renew a subscription by extending its expiry time.' It specifies the verb (renew), the resource (subscription), and the action (extending expiry). This distinguishes it from sibling tools like create-subscription, delete-subscription, and reauthorize-subscription, which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: 'Call before the current expirationDateTime to avoid missing notifications.' It also advises checking maximum extension limits for each resource type. However, it does not explicitly mention exclusions or when not to use it, but the sibling set makes that obvious. This is more than implied; it gives actionable timing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true, so the description doesn't need to restate that. It adds valuable behavior details about what each applyTo value does (wipes values vs resets formatting vs both), which goes beyond the annotation. It does not contradict annotations and provides useful context for resetting worksheet sections.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core purpose ('Clear an Excel range'), and then provides a concise, high-value tip. There is no fluff; every sentence earns its place. The structure is efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive clear operation, the description covers the key behavior (what gets cleared), the options, and a typical use case. The schema handles the remaining parameters (path segments, confirm, etc.). No critical information is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 88% coverage and already documents most parameters. The description significantly enriches the body.applyTo parameter by explaining the allowed values and their exact effects, which the schema only lists as a string. This adds meaningful semantics beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Clear an Excel range') with a specific resource and intent. It also explains the three modes (Contents, Formats, All) and their effects, which distinguishes it from sibling tools like update-excel-range or format-excel-range. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tip gives concrete usage context: 'Use this to reset a worksheet section before a fresh write rather than overwriting cell-by-cell.' This explains when to apply the tool, but it does not explicitly name alternative tools or state when not to use it. Still, the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already provided, the description adds valuable behavioral context by disclosing the exact return shape ({ contentType, encoding, contentLength, contentBytes }) and warning about the base64-through-context approach for large files. This goes beyond the annotation's safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it opens with the core action, lists supported use cases, states the return format, and then provides alternative guidance. Every sentence earns its place, and the most critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return format, usage alternatives, and the parameter is fully documented in the schema. There are no missing details that an agent would need to call the tool correctly, making it complete for a single-parameter read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'target' parameter fully documented via examples. The tool description itself does not add parameter-level 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Download'), resource ('Microsoft Graph'), and return format ('base64'), and enumerates supported content types (drive files, mail attachments, profile photos, Teams content, meeting recordings). It differentiates from get-download-url by explicitly naming the alternative for large files, making the intent unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: it recommends get-download-url for large drive/SharePoint files and get-meeting-recording-content for meeting recordings. It also frames the tool as the 'single tool' for general binary reads, giving clear context for when it is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations give readOnlyHint=false and destructiveHint=true, but the description adds concrete behavioral details: 'This method saves the message in the Sent Items folder' and specifies error behaviors for invalid parameter combinations. It also clarifies that the endpoint handles everything server-side. This goes beyond annotation basics, though it could mention more peripheral effects (e.g., whether attachments are preserved automatically). Still, it provides solid transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise given the complexity, using clear bullet points for the two formats and a TIP for practical guidance. It front-loads the core action and error rules, and the TIP is a valuable addition. It is long but each segment earns its place; no redundant filler. Slight over-length could be trimmed, but it's well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested object schema, required fields, and no output schema, the description covers the essential constraints (format selection, parameter mutual exclusivity, the Sent Items behavior, and the draft alternative). It would benefit from brief mention of MIME header requirements and the confirm parameter's role, but overall it provides enough context for an agent to call the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so baseline is 3. The description adds significant semantic value: it explains mutual exclusivity of comment/body and toRecipients rules, clarifies MIME base64 encoding, and gives explicit guidance on passing messageId ('Pass it under the name messageId'). It also highlights that toRecipients is required. This compensates for the schema's gaps and enhances usability beyond the field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Forward a message using either JSON or MIME format.' It names a specific action (forward) and a resource (message), and distinguishes itself from siblings like 'create-forward-draft' by emphasizing direct sending. The TIP reinforces the core purpose and warns against manual reconstruction, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use JSON vs. MIME formats, including error conditions (e.g., specifying both comment and body returns HTTP 400). It also names the alternative approach: 'Alternatively, create a draft to forward a message, and send it later,' which points to the sibling tool. The TIP adds clear practical guidance ('toRecipients is required', 'Do NOT reconstruct the email manually'). This fully addresses tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint and destructiveHint annotations, the description discloses the critical unsupported $select behavior (with an error example), the HTML format of the body, and the inclusion of checklist items and linked resources. This is rich contextual information that prevents misuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly long but well-structured with a tip and note, and every sentence carries useful information. The warning about $select and the expand hint are front-loaded. It's not tautological and earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description mentions key return components (body content, checklist items, linked resources) and the single-task behavior. It doesn't exhaustively list all properties, but for a read operation with a well-known Graph object, the coverage is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds critical semantic value by explicitly stating $select is unsupported (contradicting the schema which lists it), and by suggesting $expand=linkedResources. This goes beyond what the schema alone conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a todoTask object, specifies it returns a single task, and mentions key return fields (body content, checklist items, linked resources). This distinguishes it from siblings like list-todo-tasks and update-todo-task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides usage guidance by warning that $select is not supported and recommending $expand=linkedResources for related data. While it doesn't explicitly contrast with list-todo-tasks, the 'single task' phrasing implies the appropriate use case. More explicit exclusions would push it to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, and the description adds the valuable context that the tool reflects accounts added mid-session via --login. This is meaningful dynamic behavior beyond what the schema or 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the core function, the second states its primary purpose and a dynamic behavior. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with readOnlyHint, the description fully covers what the agent needs: what is listed, why to call it, and that it stays current with mid-session account additions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is correspondingly empty, so there is no parameter meaning to add. The description appropriately focuses on the result, which is the full set of configured account emails.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('List all Microsoft accounts configured in this server') and immediately distinguishes this from account-management siblings like login, logout, select-account, and remove-account. The intent is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this to discover available account emails before making tool calls.' This is clear context, though it does not name alternative tools or explicitly say 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description need not re-state mutation. It adds valuable behavioral constraints: this PATCH operation cannot change senderEmailAddress, and it explains the workaround for display name and SMTP changes. It also mentions the Graph API restriction. This goes beyond annotation-provided info, though it doesn't describe side effects or confirmation requirements, which are partially covered by the confirm parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs plus a tip block, which is slightly verbose but each sentence earns its place. The primary purpose is stated first, followed by alternatives. The tip block condenses the key points. It could be tightened, but it's structured and front-loaded enough to be easily scanned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers the essential context: what field can be updated, what cannot, and how to achieve related updates. It does not mention pagination or error handling, but these are not critical for an update operation. The confirm gate is documented in the schema. Overall, an agent has enough to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so most parameters are described in the schema. The description adds concrete payload examples: "Body: { classifyAs: 'focused' } or { classifyAs: 'other' }", which clarifies the exact format expected. It also explains the meaning of inferenceClassificationOverrideId sufficiently in the schema, and the description reinforces the classification value enum. This adds value beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Change the classifyAs field of an override as specified.' It uses a specific verb (change/update) and resource (override), and distinguishes itself from siblings like create-focused-inbox-override and delete-focused-inbox-override by being the update operation. The explicit focus on classifyAs and the prohibition on changing other fields make its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: to update classifyAs. It also names alternatives for other scenarios: 'you can use POST to force an update to the name field' and 'deleting the existing override and creating a new one' for SMTP changes. This clearly routes agents to the correct tool based on the desired mutation, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds significant behavioral detail: the 400 error on truncated base64, the size threshold, and the required @odata.type in the body. It does not contradict annotations and provides extra context about failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise but has a truncated sentence: 'An attachment can be one of the following types: All these types of attachment resources are derived from the attachment resource.' This is incomplete and adds noise. However, the key tip is well-structured and front-loaded, earning points for overall efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it's a mutation tool with destructiveHint and no output schema, the description covers the critical context: size limits, body format, and alternative tool. It doesn't describe return values, but that's not expected without an output schema. It is complete enough for an agent to execute correctly, with minor gaps like not explaining other parameters (confirm, includeHeaders).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description goes beyond the schema by specifying that the body must include @odata.type with a concrete example. This is critical because the schema only lists generic fields like name and size, not the required structure. The description compensates for the schema's lack of required format, making the body parameter semantics clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'create a new Attachment' with a specific verb and resource. It distinguishes itself from the sibling create-mail-attachment-upload-session by explicitly stating it is for attachments under 3MB, making it unambiguous which tool to use for small attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage criteria: 'The only path for attachments under 3MB' and instructs to use create-mail-attachment-upload-session for 3MB and above. It also warns about truncation failure with a specific error, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false and destructiveHint=true, so the safety profile is known. The description adds behavioral context by specifying that it returns a newly created message with a new id, and it clarifies the destination folder format. It does not contradict the annotations, and it provides sufficient detail about the operation's effect and output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the first sentence states the core purpose, the tip line expands on the body and return value, and the final sentence routes the user to the sibling tool. No redundant words, front-loaded with key info, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, nested object) and no output schema, the description covers the essential usage: body structure, return value, and alternative. It does not dwell on confirm/includeHeaders/excludeResponse, but those are self-explanatory and documented in the schema. Minor gaps like permission requirements or error cases are not critical for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 80% of parameters with descriptions. The description adds meaningful semantics to the DestinationId parameter by providing concrete examples like 'inbox, archive, junkemail' and clarifying it accepts a well-known name or ID. This goes beyond the schema's generic string type and helps an agent format the request correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Copy a message to a folder within the user's mailbox.' It identifies the resource (message), the operation (copy), and the destination (folder). It also explicitly differentiates from the sibling tool by stating 'For moving instead of copying, use move-mail-message,' which disambiguates it from similar operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use this tool versus alternatives: it copies a message, and for moving, it points to move-mail-message. This explicit guidance helps the agent choose correctly. It also explains the body structure and return value, providing operational context within the same description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, covering the safety profile. The description adds meaningful behavioral context by stating that no further change notifications will be sent after deletion, which is a direct consequence beyond the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences plus a tip. No fluff, all content earns its place, and the core action is front-loaded. The tip is supplementary but highly relevant and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation with no output schema, the description covers the core function, the consequence, and how to locate the target. It omits details like idempotency or error handling, but those are not essential for an agent to invoke correctly. The permissions link offers additional context. Complete enough for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented. The description's tip ('Use list-subscriptions to find the id') adds practical guidance for the subscriptionId parameter that goes beyond the schema's purely positional description. This extra hint elevates it above the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Delete a subscription') and immediately clarifies it refers to webhook subscriptions via the tip. It is clearly distinguishable from siblings like update-subscription, get-subscription, and list-subscriptions. 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool ('clean up stale subscriptions or stop receiving notifications') and provides a concrete pointer to the sibling tool list-subscriptions for finding the target id. It gives actionable context without needing inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description aligns with these without contradiction. It adds behavioral details beyond annotations: the URL is short-lived, pre-authenticated, requires no Authorization header, and streams bytes directly. It also discloses the return shape. Minor gap: no mention of URL expiration time or caching behavior, but it covers the key behavioral aspects for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it states the core purpose, then usage guidance, then return format, then a critical caveat. Each sentence carries essential information without redundancy. It is slightly longer than necessary but is front-loaded with the purpose and uses a clear note for limitations, so it earns a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's single parameter, lack of output schema, and straightforward operation, the description is fully self-contained. It explains what the tool does, when to use it, what it returns, and what it does not support, covering all an agent needs to call it correctly. The absence of an output schema is mitigated by listing return fields in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter `target` is fully described in the schema (100% coverage), but the description adds value by specifying accepted path formats, that a trailing /content is optional and stripped, and explicitly states unsupported paths (mail attachments, meeting recordings). This goes beyond the schema's basic type and description, making the parameter semantics richer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Resolve') and resource ('short-lived, pre-authenticated download URL for Microsoft Graph binary content'), and immediately distinguishes itself from sibling tools by contrasting with download-bytes. It also clarifies the exact scope (drive/SharePoint file content) and what it returns, leaving no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to prefer this tool over download-bytes ('above a few KB or any bulk download') and lists unsupported cases (mail attachments, meeting recordings) with guidance to use download-bytes for small ones. The description also notes that the URL avoids base64 round-tripping, giving a clear use-case rationale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses the tool's scope default vs specified folder, its distinction from the sibling, and its support for key OData features like $filter, $search, $orderby, $top, and $select. This adds useful behavioral context beyond the structured annotations 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized and front-loads the core purpose before the tip and sibling comparison. However, the tip sentence 'Lists contacts inside a specific folder' partially overlaps with the first sentence, which is a minor redundancy. Overall, every other sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool, the description is complete: it names the resource, explains the two possible folder sources, points to how to discover the folder ID, and lists the supported OData query options. The schema provides the remaining parameter details and the no output schema is not a gap because the return type ('contact collection') is clearly stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with detailed explanations for all 12 parameters including expected formats, limitations, and pitfalls. The tool description itself doesn't add parameter-level detail, but that is acceptable because the schema carries the full burden and does so well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Get a contact collection' from either the default folder or a specified contact folder. It also explicitly distinguishes itself from the sibling tool list-outlook-contacts, which only returns contacts from the default folder, so an agent can immediately tell which tool to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: use this tool to read contacts from any folder instead of list-outlook-contacts when the default folder is not sufficient. It also provides the practical pairing instruction with list-contact-folders to discover the folder ID, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the key behavioral trait that this tool does NOT expand recurring events and only returns seriesMaster. This is a critical caveat not covered by annotations (which only declare readOnlyHint, openWorldHint, and destructiveHint). The warning adds significant value beyond structured fields, preventing incorrect use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, with the core purpose front-loaded and the critical warning presented clearly as a tip. Every word earns its place; there is no redundant or vague phrasing. The structure is optimally concise for an agent to quickly grasp both the function and the limitation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description implies the response contains events by saying 'List events'. The warning about recurring events gives essential context that shapes expectations. Pagination and other behaviors are covered by parameter descriptions (top, skip, fetchAllPages). The only minor gap is that it doesn't explicitly state that the response is a list of event objects with their fields, but that's inferable. Overall, it's sufficiently complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 14 parameters are already documented in the input schema. The description does not add any parameter-specific information—the recurring event warning is global, not per-parameter. Thus, the description adds minimal value beyond the schema, consistent with the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list events), the resource (events from a specific calendar), and the addressing method (by calendar ID). It distinguishes itself from sibling tools like list-calendar-events (which likely lists across all calendars) and get-specific-calendar-view (which expands recurring events). 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides an alternative: 'Use get-specific-calendar-view instead' when recurring event expansion is needed. This directly tells the agent when not to use this tool and which sibling to use instead. It also notes that this tool addresses events by calendar ID, implying that it's for a single calendar rather than all calendars.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint=true, but the description adds crucial specifics: 'Deletes a mail folder and all its contents. This action is irreversible.' This goes beyond the annotation and helps the agent set expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two crisp sentences plus a tip. Front-loads the core action, then provides essential operational details (irreversibility, how to find ID). No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description covers what is deleted (folder + contents), irreversibility, how to specify the folder, and a pointer to a sibling tool for discovery. The confirm gate is covered in the schema, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by mentioning that the folder can be specified by well-known name (not just ID), which the schema does not mention. This extra guidance pushes it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Delete') and resource ('mailFolder'), and clarifies it supports mailSearchFolder and how to specify via ID or well-known name. Clearly distinct from update/create/move siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a tip to use list-mail-folders to find the folder ID, which aids usage. Does not explicitly discuss when to avoid this tool (e.g., if a soft delete is needed) or name alternative deletion methods, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the bar is lower. The description adds valuable behavioral context beyond annotations: it states that this revokes share/delegate access, that non-removable permissions (e.g., implicit 'My Organization') will cause a Graph error, and that the permission id comes from list-my-calendar-permissions. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with zero fluff. The core action is front-loaded, followed by the practical tip and error condition. The emoji and line break aid readability without wasting space. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete tool with no output schema, the description covers all needed operational details: how to obtain the required id, likely error conditions, and the exact scope ('my'). Annotations cover the destructive nature, and the schema covers parameters. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all params, so baseline is 3. The description adds extra meaning: the tip to fetch the permission id from list-my-calendar-permissions and the note about isRemovable=false affecting deletion. This provides context beyond the schema's param descriptions, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Delete my calendar permission') and clarifies the action as revoking calendar share or delegate access. It distinguishes itself from sibling tools like list/create/update-my-calendar-permission by being the delete operation, so an agent can easily identify it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides actionable usage guidance: tells the agent to get the permission id via list-my-calendar-permissions and warns about non-removable permissions (isRemovable=false) that will cause an error. It doesn't explicitly mention alternatives but clearly implies this is for deletion, and the 'when not to use' (non-removable) is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the annotations (destructiveHint=true) by detailing behavior: no request body, optional If-Match for conditional deletion, 204 response, and clear limitations (beta, delegated work/school accounts, global cloud only). This gives the agent a solid understanding of constraints and effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact and well-structured: opens with the purpose, then a useful tip with key operational details, and closes with limitations. Every sentence adds information; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with two required path parameters and a well-documented schema, the description covers purpose, behavior, return code, and constraints. With no output schema, it doesn't need to explain return values. An agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, so the baseline is 3. The description adds value by explaining that If-Match is optional and for conditional deletion, which the schema label 'ETag' doesn't fully convey. However, it doesn't elaborate on the required path parameters beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact operation 'Delete a plannerTaskChatMessage object' and adds a clarifying tip that it deletes a message from a Planner task's chat. Clearly distinguishes from sibling tools like create and list by using the delete verb and target resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on deletion and conditional deletion with If-Match, and notes account/cloud restrictions. It doesn't explicitly name alternatives or say 'use this when you want to remove a message', but the purpose is unambiguous so an agent can infer the right time to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint true, destructiveHint false), the description discloses it returns only a body preview, not the full body, and instructs to use $select to limit fields and bodyPreview instead of body. It also documents the critical quoting requirement for $search and links to KQL reference, adding meaningful 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, a tip, critical notes, and examples. It is lengthy but every part contributes actionable guidance; front-loading the core purpose and the 'CRITICAL' for $search quoting helps an agent prioritize. Slightly verbose but justified by the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 optional parameters) and lack of an output schema, the description fully covers what is returned (metadata fields listed), the body preview limitation, and how to obtain full content via a sibling tool. It also covers pagination and advanced query requirements, making it complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already explains each parameter, but the description adds substantial value: it details KQL syntax with concrete examples for $search, recommends a default $select, clarifies that $search cannot be combined with $filter (also in schema), and explains pagination via @odata.nextLink. This goes well beyond minimal schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists, searches, and filters Outlook email messages across all folders, and enumerates the returned metadata fields plus a body preview. It distinguishes from siblings by noting that full body retrieval is via get-mail-message and that it operates across all folders, not a specific one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs users to get-mail-message for the full email body and advises using $select and bodyPreview for listings. It gives extensive guidance on when to use $search vs $filter (they cannot combine) and notes skip is unsupported with $search. It does not explicitly differentiate from list-mail-folder-messages, but the 'across all folders' phrasing implies the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as destructive and non-read-only, so the description isn't required to repeat that. It adds value by disclosing that only displayName is writable and that built-in lists fail with an API error, preventing misuse. It doesn't cover response behavior, but given the annotations, this is a solid disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core action (rename) appears early, followed by a concise tip with the exact body format and constraints. Every sentence contributes, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with only one writable field, the description covers the essential behavior, the required body format, the failure mode for built-in lists, and how to obtain the list ID. The destructive confirm gate is documented in the input schema's confirm parameter, so that omission doesn't hurt completeness. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes parameters at 80% coverage, so the baseline is 3. The description adds a concrete body example ({ displayName: 'New name' }) and clarifies that only displayName is meaningful, which is critical because the schema's body object allows many properties and additionalProperties: true. This goes beyond the schema's own parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Renames a Microsoft To Do task list') and identifies the exact writable property ('Only displayName is writable'). This clearly distinguishes it from sibling tools like update-todo-task, which operate on tasks rather than the task list itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent what this tool is for (renaming a list), what can be changed (displayName only), and what cannot be done (built-in lists return an error). It also points to the sibling tool list-todo-task-lists for obtaining list IDs, effectively guiding selection and prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already indicating destructiveHint=true and readOnlyHint=false, the description adds substantial value by disclosing the 4 MB limit, JPEG requirement, automatic HD variant generation, and the critical warning that a truncated base64 string is written without error. It also explains permission requirements and the decoding behavior, making the tool's behavior well-understood 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose, with a formal sentence followed by a detailed tip. However, each piece of information is useful and non-redundant. It is front-loaded with the purpose statement, and the tip is logically appended. While it could be condensed, the extra details (like the truncation warning and HD variant list) justify the length. It is not bloated with irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for an agent to call the tool correctly. It covers the action, format, size constraints, permission considerations, and complementary retrieval method. It also addresses potential failure modes (truncation). Given there is no output schema, the description does not need to explain return values. The only slight ambiguity between 'specified contact, group, team, or user' and 'signed-in user' is resolved in the tip, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant meaning to the `body` parameter by explaining it must be a base64-encoded string of image bytes, JPEG format, and max 4 MB, plus the truncation warning. This goes beyond the schema's simple text. It also implicitly explains the confirm parameter's role in the destructive context, adding context that helps the agent decide when to set it true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Update the photo for the specified contact, group, team, or user in a tenant.' It also specifies the resource (profile photo) and the operation (update/upload). The tip clarifies it is specifically for the signed-in user's photo, removing ambiguity. This distinguishes it from sibling tools like upload-file-content or create-upload-session, which are for drive files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical usage guidance: it specifies the required format (JPEG), size limit (4 MB), the need to encode as base64, and a warning about truncation. It also suggests using download-bytes to retrieve the current photo, which helps the agent understand complementary tools. However, it does not explicitly compare with alternative upload tools or state when NOT to use this tool, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the response structure (returns id, displayName, isOwner, isShared, wellknownListName) and the built-in list limitation. It does not mention the confirm gate or error behavior, but the schema covers the confirm parameter. It adds value beyond the annotations (readOnlyHint=false, destructiveHint=true) without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and efficiently packed. It front-loads the purpose, then provides a clarifying tip with an example and notes limitations. Every sentence adds value, with no unnecessary filler. The structure is clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no output schema, the description adequately covers purpose, minimal input example, response fields, a key limitation, and a usage pairing. It gives an agent enough to call the tool correctly without needing to inspect the full schema. The only omission is a mention of the confirm gate, but that is documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives a concrete example body { displayName: 'My new list' }, clarifying that only displayName is typically needed, and explains what the returned object includes. This adds significant meaning beyond the schema's property descriptions, which are generic. It helps an agent understand what input is essential and what output to expect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Creates a new Microsoft To Do task list' and explains what a task list is (named buckets in the sidebar). It distinguishes from siblings like create-todo-task by clarifying it creates the list itself, not tasks within it. The description also specifies the resource and the action precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it tells the agent to pair with create-todo-task to populate the list, and it notes that built-in lists ('Tasks', 'Flagged emails') already exist and cannot be re-created, which is a key prerequisite. This effectively directs the agent to when to use this tool and when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint, but the description adds substantial behavioral context: it returns a specific object shape ({path, contentType, bytesWritten}), writes to absolute paths, never overwrites existing files, and is stdio-only. It also discloses that bytes are obtained through authenticated endpoints, clarifying the tool's out-of-band nature. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by usage context and alternatives. It is somewhat lengthy (around 120 words) but each sentence carries critical information, including constraints (stdio-only, no overwrite) and sibling routing. The structure is logical: definition, use cases, limitations, and alternatives. It is not unduly verbose but could be tightened by removing a few redundant phrases (e.g., repeating 'authenticated').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two simple parameters but a wide range of supported target types (mail attachments, meeting recordings, profile photos, Teams hosted content), the description is remarkably complete. It lists common target paths, states the return format, warns about overwrite behavior, and specifies the stdio mode limitation. It also provides a clear alternative for OneDrive/SharePoint content, covering key decision points an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters already documented in detail (including common paths for target and absolute-path requirement for outputPath). The description goes beyond schema by explaining the return format and why the tool exists (authenticated bytes), but it does not add new parameter-level semantics beyond reinforcing the schema. Since the schema fully covers parameter meaning, a baseline of 3 is appropriate, and the extra context about use cases earns a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Write'), a specific resource ('authenticated Microsoft Graph byte content'), and a concrete action ('to a local file on the server'). It explicitly differentiates from sibling tools by noting it returns 'instead of base64' and names the preferred alternative for OneDrive/SharePoint (get-download-url). This makes the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance (the only out-of-band way to save mail attachments and meeting recordings) and when-not-to-use (for OneDrive/SharePoint, get-download-url is preferred). It also notes the stdio-only constraint and that the tool never overwrites files, offering clear operational boundaries and routing to an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only and non-destructive, and the description adds behavioral context beyond that: delta-link pagination, expansion of recurring events, and the fact that repeated delta calls maintain a local store incrementally. This is exactly the kind of runtime behavior an agent cannot infer from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and the tip section is scannable and concrete. There is some redundancy between the first paragraph's explanation of full/incremental synchronization and the tip's restatement of subsequent-call behavior, but every sentence otherwise earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only delta tool with no output schema, the description covers what an agent needs: required inputs, return contract (events plus @odata.deltaLink), recurrence behavior, and a concrete use case. It also routes around the most confusing sibling, so the definition is complete for reliable selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so optional parameters are already fully documented. The description adds important semantic context for the required parameters—startDateTime and endDateTime are needed on the first call and the resulting @odata.deltaLink drives subsequent calls—which is not present in the schema. Slight deduction because it does not translate these semantics to individual optional parameters, but the schema already covers their syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and resource: it returns events that were added, deleted, or updated in a calendarView of the user's primary calendar. It goes further by distinguishing itself from list-calendar-events-delta: recurring events are expanded to occurrences rather than returning the series master, so an agent can disambiguate with no schema inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains the delta sync workflow: first call is a full sync and must include startDateTime/endDateTime, subsequent calls with @odata.deltaLink return only changes. It also names the closest sibling list-calendar-events-delta and specifies a concrete use case ('calendar UIs showing a week/month view'), giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it performs a conversion, which is a read-only transformation consistent with the readOnlyHint annotation. It adds format-specific details beyond the annotation (enumerating URL types) but does not mention potential error handling or edge cases (e.g., invalid URLs), which would be the next level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no superfluous words. The core action is front-loaded, and the usage guidance is concise. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description fully covers what the tool does, when to use it, and what input forms are expected. Nothing an agent needs to correctly invoke it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema already describes the parameter as 'Teams meeting URL in any format', the description enriches this by specifying the exact format variants accepted. This additional semantic detail helps the agent understand what constitutes a valid input and goes beyond the generic schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states that the tool converts Teams meeting URLs into a standard joinWebUrl, enumerating the specific accepted formats (short /meet/, full /meetup-join/, recap ?threadId=). It clearly distinguishes its purpose from the mentioned sibling list-online-meetings by indicating when it should be used as a precursor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit usage directive: 'Use this before list-online-meetings when the user provides a recap or short URL.' This tells the agent exactly when to invoke this tool and points to the alternative, though it doesn't explicitly state when not to use it for full URLs, the implication is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and non-destructive behavior, so the description focuses on useful behavioral details: delta token state, pagination, expiration after ~30 days, and the 410 restart instruction. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed yet efficient, with a clear first sentence and a structured tip block. Every sentence earns its place, covering purpose, usage, and operational nuance without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of delta queries (pagination, token lifecycle, expiry, error handling), the description addresses all essential aspects: first call, subsequent calls, pagination, expiration, and error recovery. It also explains when to use it over a full list, making it complete for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds extra context beyond the schema, notably the mailFolderId='inbox' well-known folder suggestion and the recommendation to use nextLink instead of a large $top, which enriches parameter usage guidance without replacing the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource+scope: 'Get a set of messages added, deleted, or updated in a specified folder.' It explicitly distinguishes from a full list by saying 'Prefer this over full re-list for polling,' which makes it easy for an agent to select this over list-mail-folder-messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'Prefer this over full re-list for polling' and explains the incremental sync workflow with deltaLink/nextLink. It also covers edge cases like delta expiration and 410 handling, giving a complete operational picture.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![ms365-mcp MCP server](https://glama.ai/mcp/servers/A-Impact-Pavel/ms365-mcp/badges/card.svg)](https://glama.ai/mcp/servers/A-Impact-Pavel/ms365-mcp)

Score Badge

Copy to your README.md:

[![ms365-mcp MCP server](https://glama.ai/mcp/servers/A-Impact-Pavel/ms365-mcp/badges/score.svg)](https://glama.ai/mcp/servers/A-Impact-Pavel/ms365-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/A-Impact-Pavel/ms365-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server