Microsoft 365 MCP Server
Server Quality Checklist
Latest release: v0.0.0-development
- Disambiguation3/5
Tools are generally distinct by resource and action, but there is significant overlap in email operations (e.g., create-reply-draft vs. reply-mail-message) and calendar events (e.g., create-calendar-event vs. create-specific-calendar-event), which could cause confusion. Descriptions help clarify, but the sheer number of similar tools increases ambiguity.
Naming Consistency4/5Most tools follow a consistent verb_noun pattern (e.g., create-calendar-event, delete-mail-attachment), with clear actions and resources. Minor deviations exist (e.g., login, logout, search-query are less structured), but overall naming is predictable and readable across the set.
Tool Count2/5With 78 tools, the count is excessive for a single server, making it overwhelming and difficult to navigate. While Microsoft 365 is a broad domain, this many tools suggests poor scoping, likely leading to agent confusion and inefficiency in tool selection.
Completeness5/5The tool set provides comprehensive coverage across Microsoft 365 services (e.g., Mail, Calendar, OneDrive, Planner, To-Do), including full CRUD operations, authentication, and specialized actions like search and file management. No obvious gaps are present for the domain's core workflows.
Average 2.9/5 across 78 of 78 tools scored. Lowest: 1.3/5.
See the Tool Scores section below for per-tool breakdowns.
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
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.
This repository includes a glama.json configuration file.
This server has been verified by its author.
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?
Annotations indicate destructiveHint:true and readOnlyHint:false, but the description discloses nothing about email-specific behaviors (saving drafts vs sending, attachment handling, recipient validation) or what the tool actually returns. The text describes open extension behavior instead.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and structurally concise, but every sentence discusses the wrong functionality (open extensions), making the conciseness irrelevant or harmful for the agent's understanding of this email tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely inadequate for a complex email creation tool with nested recipient/attachment objects and no output schema. The description describes a different API concept entirely (open extensions) and fails to address email draft creation, sending workflows, or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% with nested object descriptions for email fields (body content, recipient types, attachments). However, the description adds no meaning for the email context and actively misleads by implying parameters relate to open extensions. The 'body' wrapper object and flags like 'includeHeaders' are unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description describes creating 'open extensions' (openTypeExtension objects) for adding custom properties to resources, but the tool name 'create-draft-email' and input schema (containing subject, body, bccRecipients, ccRecipients, attachments, isDraft fields) clearly indicate this tool creates email draft messages. This is severely misleading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus sibling tools like 'create-forward-draft', 'create-reply-draft', or 'send-mail'. The text discusses open extension permissions and resource tables, which is irrelevant to email draft creation.
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, consistent with a creation operation, but the description provides no useful behavioral context for calendar event creation (e.g., required fields, recurrence handling, or attendee notification behavior). It focuses entirely on extended properties which is not the primary behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description contains broken structure with empty list introductions ('The following user resources are supported: The following group resources are supported:') followed by nothing. It mixes irrelevant extended properties content with a disconnected email tip, resulting in confusion rather than conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex creation operation with 40+ potential fields in the body parameter, the description provides no useful context about required fields, validation rules, or the distinction between this tool and create-specific-calendar-event. The extended properties content is completely misplaced for a calendar event creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (decent baseline), but the description adds no meaningful context for the primary calendar event parameters (subject, body, attendees, timing). It mentions extended properties which exist in the schema but represents a minor feature, not the main purpose. The description fails to explain critical semantics like date-time formats or attendee structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create one or more multi-value extended properties' which describes a completely different tool than the name 'create-calendar-event' suggests. The schema clearly defines calendar event parameters (subject, attendees, start, end), but the description focuses on extended properties, making it actively misleading about the tool's primary purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'See Extended properties overview for more information about when to use open extensions or extended properties' which is irrelevant to calendar event creation. The only relevant guidance is the tip about using list-users to find email addresses for recipients, but this is disconnected from the main content and doesn't explain when to use this tool vs siblings like create-specific-calendar-event.
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 correctly indicate this is a non-read-only (write operation), non-destructive action with open-world side effects, but the description adds no behavioral context about overwrite rules, versioning behavior, transactionality, or what 'content stream' implies for the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While brief (single sentence), the description is confusingly fragmented and appears mistakenly copied from a parameter description rather than describing tool behavior. The brevity creates ambiguity rather than clarity, failing to earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an upload operation with openWorldHint=true and no output schema, the description omits critical context about success confirmation, partial upload handling, content-type requirements, and the relationship between the body parameter and the target file.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80% (body is the only undocumented parameter in the schema). The description provides no explicit parameter mapping, though 'content stream' vaguely alludes to the body payload. With high schema coverage, baseline 3 is appropriate as the description adds minimal semantic value beyond the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'The content stream, if the item represents a file' lacks any verb indicating action (e.g., 'uploads', 'writes') and fails to state that this tool transfers data to a file. It reads as a passive data description rather than a functional purpose statement, leaving the agent unable to distinguish this from a download or metadata retrieval tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does 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 siblings like 'download-onedrive-file-content', nor does it clarify prerequisites such as existing file creation or how it handles content replacement versus appending.
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, establishing the safety profile. The description adds no behavioral context regarding deletion permanence (soft vs. hard delete), ETag concurrency requirements, or openWorldHint implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While brief (2 words), this represents under-specification rather than efficient conciseness. For a destructive 4-parameter operation, the length is inappropriately short and front-loads no critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inadequate for tool complexity. A destructive message deletion tool with conditional headers (If-Match) and response body options requires explanation of deletion semantics, idempotency, and return values—none of which are provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, establishing a baseline of 3. The description mentions no parameters and adds no semantic value regarding the If-Match precondition or response options (includeHeaders/excludeResponse).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a verb ('Delete') and resource ('eventMessage'), but 'eventMessage' conflicts with the tool name 'delete-mail-message' and introduces ambiguity without clarifying scope. It fails to distinguish from siblings like 'delete-mail-attachment' 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this versus alternatives, prerequisites (e.g., permissions), or expected outcomes. The destructive nature is only indicated by annotations, not the description text.
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 this is destructive (destructiveHint=true) and not read-only. Description adds minimal behavioral context—doesn't explain ETag concurrency control (If-Match), what constitutes success (especially with excludeResponse), side effects on the parent message, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While brief, the description wastes words on filler ('for me') and unexplained technical terms ('navigation property'). Single-sentence structure front-loads implementation detail (navigation property) rather than user value (attachment deletion).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Insufficient for a destructive operation with concurrency controls. Lacks explanation of the ETag workflow (obtain from get-mail-attachment, required for If-Match), error scenarios (already deleted attachment), or output behavior despite having no output schema defined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all 5 parameters including If-Match and the boolean flags. Description adds no parameter-specific guidance (e.g., explaining ETag usage or when to exclude responses), warranting the baseline score for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states the tool deletes attachments, but obscures this with technical jargon ('navigation property') that lacks explanation. Fails to distinguish from sibling delete-mail-message (which deletes entire messages vs. attachments). The phrase 'for me' is vague filler that doesn't clarify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives, prerequisites (e.g., needing to retrieve attachmentId first), or concurrency requirements (If-Match header). No mention of relationship to get-mail-attachment or add-mail-attachment siblings.
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?
While annotations correctly flag this as destructive (destructiveHint: true), the description adds no behavioral context beyond this safety signal. It fails to explain the If-Match parameter's role in optimistic concurrency, whether deletions are permanent, or if calendar attendees are notified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Though brief (five words), the description wastes space on technical jargon ('navigation property') and conversational filler ('for me') that convey no actionable information. The sentence does not earn its place effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with concurrency control (If-Match) and response filtering options, the description is inadequate. It fails to explain the critical 'If-Match' requirement for deletions or the impact of the boolean flags on the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all five parameters including the ETag concurrency control. The description adds no additional parameter guidance, meeting the baseline score of 3 for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses opaque OData terminology ('navigation property') that describes implementation rather than user intent. While it mentions 'Delete' and 'events', it does not clearly state that this removes a specific calendar event by ID, nor does it distinguish from the sibling 'delete-calendar-event' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does 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 the sibling 'delete-calendar-event' or what prerequisites exist (e.g., needing the event ID). The description offers no information about concurrency control requirements or recovery options.
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?
While annotations.declare readOnlyHint=true (safe read), the description adds no context about the behavioral traits: it doesn't explain that fetchAllPages automatically follows pagination, what the ETag in includeHeaders is used for, or that excludeResponse returns only metadata. The openWorldHint annotation suggests external resource handling, but the description is silent on this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is severely under-specified for a 4-parameter tool. While brief, it fails the 'every sentence earns its place' test by providing insufficient information to distinguish this from other content retrieval tools or explain the pagination behavior implied by fetchAllPages.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a Microsoft 365 integration tool with complex pagination options and response variants (HTML content vs headers only vs success indicator), the description is incomplete. It doesn't address the output format, error conditions, or prerequisites (authentication, specific permissions) despite the rich domain context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the parameter purposes are documented in the schema fields themselves. The description adds no additional semantic context (e.g., that onenotePageId typically comes from list-onenote-section-pages, or that excludeResponse is useful for validation checks without data transfer). Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does 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 fragment describing the output resource, not the tool's action. It lacks a verb (get/retrieve/fetch) and fails to clearly state that this tool extracts content from a specific OneNote page, distinguishing it from sibling tools like list-onenote-section-pages or create-onenote-page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives. There is no mention that users typically need to call list-onenote-section-pages first to obtain a page ID, nor when to use fetchAllPages versus handling pagination manually.
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?
States 'Read-only' which merely duplicates the readOnlyHint annotation. Includes 'Navigation property' (OData jargon) without explaining behavioral implications. Fails to disclose pagination behavior, rate limits, or that it returns a collection versus a single entity, despite complex query parameters like fetchAllPages and expandExtendedProperties.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Severely undersized for a 14-parameter tool with complex query capabilities. Three short fragments waste space on redundant annotation info ('Read-only') and obscure terminology ('Navigation property') that don't help an agent understand how to invoke the tool effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inadequate for tool complexity. With 14 parameters supporting OData-style queries (filter, expand, select, etc.), the description should explain the query pattern or return structure. No output schema exists, yet description doesn't hint at return format or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline applies. Description adds no parameter-specific context (e.g., no explanation of OData-style filtering, timezone handling, or when to use expandExtendedProperties), but schema compensates adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
Uses noun phrase 'The events in the calendar' instead of an action verb (e.g., 'List' or 'Retrieve'), failing to clearly state what the tool does. While it identifies the resource, it does not distinguish from sibling tools like list-calendar-events or get-specific-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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives (e.g., list-calendar-events vs list-specific-calendar-events). No mention of prerequisites (calendarId requirement) or filtering use cases despite having complex query parameters.
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 verb 'Update' aligns with readOnlyHint:false and destructiveHint:true (implying file modification), but the description fails to disclose what actually happens (e.g., whether it permanently reorders rows, requires specific permissions, or affects the workbook structure). It doesn't explain the openWorldHint implication either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is technically concise, but wastes space on implementation-specific terminology ('navigation property') rather than front-loading the user-facing action. Every word should clarify intent for the AI agent; instead it obscures the purpose behind API jargon.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation (destructiveHint:true) with nested objects and no output schema, the description inadequately explains success indicators, side effects, or the scope of modification. It doesn't clarify whether this sorts an existing named range or creates a sort configuration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, providing decent documentation for driveId, includeHeaders, etc. However, the description adds no semantic context for parameters, particularly the required 'body' object which only contains an 'id' field marked 'Read-only' in the schema—a confusing constraint left unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses technical OData jargon ('navigation property') rather than user-facing language. While it mentions 'sort' and 'drives', it fails to clearly state this sorts data within an Excel workbook/worksheet, despite the tool name 'sort-excel-range' and siblings like 'format-excel-range' suggesting Excel operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this versus format-excel-range or get-excel-range. No mention of prerequisites (e.g., requiring valid driveId/driveItemId) or that it modifies the actual spreadsheet file rather than just returning sorted data.
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?
While annotations indicate this is a destructive mutation (readOnlyHint: false, destructiveHint: true), the description fails to disclose critical behavioral specifics: the required If-Match/ETag header for optimistic concurrency control, partial update semantics (PATCH behavior), or what happens to unspecified properties.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At seven words, the description is technically concise, but this brevity is wasted on empty content. It is not front-loaded with value—every sentence fails to earn its place by providing only redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with nested objects, optimistic concurrency requirements, and specific Microsoft Graph API semantics, the description is inadequate. It omits the ETag requirement, partial update behavior, and Planner-specific context (buckets, assignments, categories) that would help an agent construct valid updates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 80% schema description coverage, the schema carries most of the semantic weight. The description adds no parameter-specific guidance, but meets the baseline expectation where the schema documents fields like 'percentComplete', 'dueDateTime', and the ETag requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update the properties of plannerTask object' is a tautology that restates the tool name with minimal expansion. It fails to distinguish this tool from sibling 'update-planner-task-details' or clarify which properties are updatable versus read-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does 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-planner-task', 'get-planner-task', or 'update-planner-task-details'. It omits critical prerequisites such as the requirement to first fetch the task to obtain an ETag before updating.
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 correctly mark this as readOnlyHint: true, but the description opens with entirely false behavioral context about retrieving open extensions. It does not disclose pagination behavior, rate limits, or return value structure for the mail listing operation. The disclosure is limited to search syntax requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is poorly structured with the first paragraph being completely irrelevant waste text. The critical search tip is useful but verbose and should be front-loaded. The structure suggests concatenation of unrelated documentation without editing for this specific tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters and no output schema, the description should explain what mail message properties are returned. Instead, it discusses open extension permissions tables that don't exist in the context. It fails to describe the actual return payload or distinguish this from folder-specific listing tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the wrong opening text, the description adds substantial value for the 'search' parameter by specifying the double-quote wrapping requirement, KQL syntax operators (from:, subject:, body:, etc.), and concrete examples. With 100% schema coverage, this elevates above the baseline 3 by providing critical formatting constraints not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description incorrectly begins with 'Get an open extension (openTypeExtension object)...' which describes a completely different tool, likely copy-pasted from Microsoft Graph API documentation. It fails to mention 'mail messages' or 'list' anywhere in the primary description, making it misleading rather than merely vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description provides detailed KQL syntax guidance for the $search parameter (valuable usage guidance), it offers no context on when to use this tool versus siblings like list-mail-folder-messages, get-mail-message, or search-query. The critical tips are buried after irrelevant text.
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?
While annotations indicate the operation is destructive and not read-only, the description adds no behavioral specifics beyond 'Creates.' It fails to disclose Excel-specific side effects, such as how the chart interacts with existing worksheet data or what occurs if the specified worksheet does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The four-word description is inappropriately concise for a six-parameter tool with nested objects and destructive side effects. The extreme brevity constitutes underspecification rather than efficient communication, failing to front-load any critical operational details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive operation, four required parameters including complex nested objects in 'body', no output schema), the description is dangerously incomplete. It omits Excel-specific context, ignores the nested body structure requirements, and provides no indication of success/failure behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, triggering a baseline score of 3. The description adds no parameter-specific information, but the schema adequately covers five of six top-level parameters (driveId, driveItemId, etc.). However, the critical 'body' parameter—containing nested chart configuration (type, sourceData, seriesBy)—lacks descriptions in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Creates a new chart' essentially restates the tool name with spaces added, constituting a tautology. It fails to specify the Excel context (despite the tool name), the target worksheet location, or distinguish meaningfully from sibling 'create-*' tools beyond the resource noun.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 other creation tools, prerequisites for the drive/workbook/worksheet IDs, or what chart types are supported. The description offers zero contextual guidance for the agent's decision-making.
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?
With readOnlyHint=true in annotations, the description adds the important constraint that this only works 'if the item represents a file' (not folders). However, it omits behavioral details about streaming large files, pagination handling via fetchAllPages, or format conversion capabilities implied by the format parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While brief (one sentence), this is under-specification masquerading as conciseness. The sentence describes output behavior rather than tool purpose, failing to front-load actionable information for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description attempts to describe the return value but misses critical context for a download operation: error conditions (file not found, permission denied), binary vs text handling, or the interaction between format conversion and the content stream.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, establishing a baseline of 3. The description adds no semantic context for parameters (e.g., explaining that driveId identifies the OneDrive drive rather than just restating 'Path parameter'). It leaves the technical schema descriptions as the sole source of truth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a noun phrase ('The content stream') rather than stating the action (download/retrieve), and describes the return value conditionally rather than the tool's purpose. It fails to distinguish this from sibling list/get operations like get-drive-root-item or list-folder-files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this versus listing files or getting metadata. No mention of prerequisites (e.g., needing file IDs from list-folder-files) or when to use flags like excludeResponse versus includeHeaders.
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 this is a destructive, non-read-only operation (destructiveHint: true). The description adds no behavioral context beyond what annotations provide—no explanation of what 'format' means, what changes occur, side effects, or mutation scope. With annotations carrying the safety profile burden, the description contributes minimal additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While brief (single sentence), the description suffers from under-specification rather than effective conciseness. The jargon-heavy phrasing ('navigation property', 'drives') obscures meaning without delivering value. Key information (Excel formatting, visual styling capabilities) is buried under technical abstraction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 6 parameters, nested object structures (borders array, fill/font objects), and no output schema, the description is inadequate. It fails to explain the tool's domain (Excel formatting), the nature of the formatting operations (visual styling), or the relationship between the path parameters and the body content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83% (>80%), establishing a baseline of 3. The description mentions no parameters, but the schema effectively documents the complex nested body properties (borders, font, fill) and path parameters without requiring additional textual support.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses technical jargon ('navigation property') from underlying API metadata that fails to clarify the actual user-facing purpose. It mentions 'drives' (the container) rather than Excel ranges/cells (the actual target resource), and doesn't clearly indicate this is for formatting Excel cells despite the tool name and sibling get-excel-range suggesting this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides no guidance on when to use this tool versus alternatives (e.g., get-excel-range for reading, sort-excel-range for sorting), nor does it mention prerequisites like obtaining driveId or workbookWorksheetId from prior calls. The single sentence only states what the tool does, not when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations declare readOnlyHint=true, the description adds no behavioral context beyond this. It does not explain what the 'range' operation returns (values, formulas, formatting), pagination behavior, or the implications of the optional flags (excludeResponse, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three words long, constituting under-specification rather than appropriate conciseness. It front-loads zero useful information and wastes the opportunity to orient the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, hierarchical resource addressing) and the presence of rich structured data (complete schema, annotations), the description is inadequate. It fails to contextualize the required parameters or explain the Excel-specific addressing scheme.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all parameters already having mechanical descriptions. The description adds no semantic value about what driveId, driveItemId, or address represent, warranting the baseline score for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Invoke function range' is a tautology that restates the tool name without clarifying what it actually does. It fails to mention that it retrieves cell values/data from an Excel worksheet or distinguish it from siblings like format-excel-range or sort-excel-range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives, nor does it explain the prerequisite hierarchy (drive → item → worksheet) required to construct a valid request.
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 'Read-only' statement merely duplicates the readOnlyHint annotation. 'Navigation property' appears to be irrelevant implementation jargon from Microsoft Graph API documentation that provides no behavioral value. No disclosure of pagination behavior, error conditions, or response format despite complex options like fetchAllPages and excludeResponse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While brief (three fragments), the structure is poor—'Navigation property' wastes space with API implementation detail irrelevant to tool selection, and 'The events in the calendar' is grammatically incomplete. Not front-loaded with the essential action/purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with complex pagination, timezone handling, and OData query options (select/expand), the description is inadequate. No output schema exists, yet the description fails to explain return values, leaving significant behavioral gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 9 parameters have descriptions), establishing a baseline of 3. The description text adds no parameter-specific context, examples, or usage notes beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'The events in the calendar' is a noun phrase that fails to specify the action (retrieve/fetch) or distinguish from siblings like get-calendar-event or list-specific-calendar-events. It does not clarify that this retrieves a single specific event by ID versus listing multiple 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this versus list-specific-calendar-events (which lists multiple) or get-calendar-event. No mention of required parameters (calendarId, eventId) or prerequisites in the description text.
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 explicitly mark this as destructive (destructiveHint: true, readOnlyHint: false), so the description does not need to establish the mutation nature. However, it adds no context about partial update behavior, idempotency, what happens if the event is not found, or required permissions 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description mixes technical implementation detail ('navigation property') with a seemingly unrelated security tip about email addresses. The structure is disjointed—one cryptic sentence followed by an emoji-led warning—rather than a coherent explanation front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation operation with deeply nested event properties (body, attendees, attachments) and no output schema, the description is insufficient. It fails to mention required identifiers (calendarId, eventId) in the text, explain what constitutes a successful update, or describe validation constraints beyond the raw schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high at 80%, with detailed descriptions for the complex nested body object (attendees, start/end times, etc.) and path parameters. The description text contributes nothing about parameters, but the high schema coverage meets the baseline without requiring compensatory description text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses obscure Graph API technical jargon ('navigation property events in me') rather than clear user-facing language. While 'Update' and 'events' are present, the phrase 'navigation property' and 'in me' (referring to the /me endpoint) create confusion without clarifying what distinguishes this tool from the sibling update-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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains one specific operational tip about not guessing email addresses and using list-users instead, which is relevant when updating attendees. However, lacks general guidance on when to use this tool versus update-calendar-event or other calendar operations, and does not explain the workflow for identifying calendarId and eventId.
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?
While not contradicting annotations (destructiveHint: true aligns with 'Create'), the description adds no behavioral context beyond the single verb. It does not disclose idempotency, required permissions, or side effects beyond what 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (single sentence), but undersized for the tool's complexity. The sentence does not earn its place by providing actionable guidance, though it is not verbose or poorly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inadequate for a complex creation tool with nested objects and destructive annotations. Missing critical context about required relationships (plan/bucket), return behavior, or how to locate created resources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-specific information, but the input schema has 67% description coverage with detailed field descriptions for the complex body object (title, dueDateTime, priority, etc.), meeting minimum viability without descriptive assistance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description tautologically restates the tool name with minimal variation ('Create a new plannerTask'). It fails to distinguish from sibling tools like create-todo-task or explain what constitutes a Planner task versus other task types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives, prerequisites such as requiring an existing planId/bucketId, or specific contexts where Planner tasks are 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?
While annotations correctly mark this as destructive, the description adds no behavioral context about deletion mechanics (permanent vs. recycle bin, concurrency control with If-Match, or what occurs upon success). It merely repeats the technical operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is terse but inefficient—it uses obscure technical terminology ('navigation property') that obscures rather than clarifies, failing to front-load the actual resource being manipulated (OneDrive files).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive file operation with 5 parameters and no output schema, the description is inadequate. It omits response behavior, error conditions, and the significance of the ETag parameter for optimistic concurrency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, parameters are well-documented in the schema itself. The description mentions neither specific parameters nor their semantics, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses technical Graph API jargon ('navigation property items') instead of clear user-oriented language. It fails to explicitly state this deletes files/folders from OneDrive, making it vague despite the clear tool 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this versus other deletion siblings (delete-mail-attachment, delete-calendar-event, etc.) or prerequisites like required permissions for OneDrive operations.
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?
While annotations correctly mark destructiveHint=true, the description adds no behavioral context beyond this. It fails to mention the ETag/optimistic concurrency behavior (critical for the If-Match parameter), whether deletion is permanent/recoverable, or side effects (openWorldHint=true).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely brief (3 words) but underspecified rather than efficiently concise. The single sentence does not earn its place as it provides no actionable information beyond the tool name itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with conditional deletion support (If-Match) and response control flags, the description is inadequate. It omits permanence implications, error conditions (409 conflicts requiring ETag), and the relationship between includeHeaders/excludeResponse and the missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage (properties include 'ETag', 'Path parameter: contactId', etc.), so the baseline is 3. The description adds no parameter semantics, failing to explain that If-Match enables conditional deletes or that contactId must be obtained from list/get operations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a contact.' restates the tool name (tautology) and fails to specify the Outlook context or distinguish from other contact systems. Sibling tools like 'delete-todo-task' and 'delete-mail-message' share the delete verb, but the description doesn't clarify this targets Outlook contacts specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use versus alternatives (e.g., update-outlook-contact to clear fields), prerequisites (needing contactId from list-outlook-contacts), or conditions requiring If-Match for concurrency control.
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 openWorldHint: true, yet the description mentions neither the destructive nature (unusual for search) nor the external/open-world access. The description carries the burden of explaining this non-obvious behavior but provides only generic 'search results are provided' text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two brief sentences containing no redundancy. However, for a tool with 20+ nested configuration fields and destructive annotations, this brevity represents under-specification rather than effective conciseness, failing the 'appropriately sized' criterion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex input schema (nested requests, aggregations, collapse properties), destructive annotations, lack of output schema, and 80+ sibling tools, the two-sentence description is grossly incomplete. It omits pagination behavior, supported entity types, and the significance of the 'from' and 'size' parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with extensive descriptions for nested fields like aggregationFilters and entityTypes. The description mentions 'request body' corresponding to the body parameter but adds no semantic value for the top-level includeHeaders/excludeResponse flags or the complex nested request structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Runs the query' which is vague and nearly tautological with the tool name 'search-query'. It fails to specify that this searches across Microsoft 365 entities (messages, events, drive items, etc.) as revealed in the schema's entityTypes enum, leaving the agent uncertain about the tool's 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/5Does 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 the numerous specific retrieval siblings (e.g., list-mail-messages, get-calendar-view). Given the complex Graph Search API capabilities (aggregations, collapsing, content sources), the absence of usage criteria leaves the agent without 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?
Although annotations declare destructiveHint=true, the description adds no context about what the destructive update entails (e.g., whether attendees are notified, if the update is partial or full replacement). The email tip is input validation guidance, not behavioral transparency 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise at two sentences, but wastes the first sentence on tautology. The critical tip about recipient emails is present but poorly structured as the primary description content rather than supplementary guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inadequate for a complex destructive operation with nested objects. Lacks essential context about attendee notification behavior, idempotency, organizer permissions, and return values (no output schema exists to compensate).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, adequately documenting the complex nested body structure. The description adds no semantic meaning for parameters like eventId or the body contents, meeting the baseline for decent schema coverage without providing additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update the properties of the event object' restates the tool name (tautology) and fails to distinguish this from sibling tool update-specific-calendar-event or specify which properties are modifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides one constraint about using list-users for email lookups, but lacks guidance on when to select this tool versus alternatives like update-specific-calendar-event or create-calendar-event. Notably, list-users does not appear in the sibling tool list, creating potential confusion.
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 mark this as destructive (destructiveHint:true). Description confirms it creates resources, adding no additional behavioral context about side effects, rate limits, or failure modes (e.g., message not found). The truncated sentence about attachment types adds confusion rather than transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
First sentence front-loads purpose efficiently, but the description ends with an incomplete thought ('All these types...') that appears truncated. This structural breakage creates ambiguity about attachment polymorphism without delivering useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with nested object parameters and no output schema, the description lacks critical context: error scenarios, size limits (despite size field in schema), or the relationship between messageId and the attachment operation. The incoherent trailing sentence wastes space without adding value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (high), with body properties and flags adequately documented in schema. Description adds no parameter semantics, but baseline 3 is appropriate given schema carries the load. No compensation needed for the well-described messageId and body parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
States basic verb ('create') and resource ('Attachment') but lacks scope clarity on whether this attaches to existing messages or drafts. The trailing sentence about 'types derived from attachment resource' is incoherent/fragmented, detracting from clarity. Does not differentiate from siblings like get-mail-attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus creating a draft with attachment, or prerequisites like message existence. No mention of inline vs regular attachment use cases despite schema supporting isInline flag.
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 'Read-only' statement aligns with readOnlyHint=true annotation but adds no behavioral context beyond annotations. It fails to explain pagination behavior (fetchAllPages parameter), OData query options (select/expand), or what constitutes the 'root' in this 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely brief (6 words) with no redundancy, but structured as disjointed fragments rather than cohesive sentences. While concise, the extreme brevity leads to under-specification of tool behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with OData query options and pagination controls, two fragments provide insufficient context. No output schema exists, yet the description doesn't hint at return value structure or the significance of the root folder as a navigation anchor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, establishing baseline 3. The description mentions no parameters and provides no semantic guidance beyond the schema (e.g., explaining that select/expand follow OData conventions or that driveId comes from list-drives).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses noun phrases ('The root folder') rather than action verbs, failing to clearly state the tool retrieves/obtains the resource. It does not differentiate from siblings like list-drives or list-folder-files, nor does it explain this is the entry point for drive navigation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus list-drives, list-folder-files, or other drive-related operations. The required driveId parameter and its relationship to list-drives output is not explained.
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?
While annotations correctly indicate readOnlyHint=true, the description adds useful context about targeting the 'default contacts folder' specifically. However, the trailing incomplete sentence creates ambiguity about cross-user access capabilities, and the description omits details about pagination behavior, rate limits, or the structure of returned contact objects that would help agents predict outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences, but the second is an incomplete fragment ending with a colon that serves no communicative purpose and creates confusion. This structural defect means not every element earns its place, as the fragment promises information it never delivers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex read operation with 11 optional parameters and no output schema, the description inadequately explains what constitutes a 'contact collection' (field names, structure) or how pagination behaves with the fetchAllPages option. The incomplete cross-user scenario mention further gaps the coverage of capabilities an agent needs to invoke this effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage across all 11 parameters, the schema sufficiently documents individual fields like filter, search, and fetchAllPages. The description provides no additional parameter semantics beyond the schema, which is acceptable given the high coverage, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states 'Get a contact collection from the default contacts folder of the signed-in user,' providing specific verb and resource. However, the description ends with an incomplete sentence fragment ('There are two scenarios...') that introduces confusion about whether the tool supports accessing other users' contacts without explaining how, and it fails to distinguish from sibling get-outlook-contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this list operation versus the singular get-outlook-contact, nor when to apply filter versus search parameters. The incomplete mention of 'two scenarios' for accessing other users' contacts suggests additional usage patterns but fails to articulate them, leaving agents without actionable 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 already indicate this is a destructive write operation (destructiveHint: true, readOnlyHint: false). The description adds no behavioral context beyond the schema, such as whether this performs partial (PATCH) or full (PUT) updates, validation constraints, or the impact of updating read-only fields like 'id' or 'createdDateTime'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is efficiently structured and front-loaded, but is arguably too terse for a complex operation involving 4 parameters and deep nesting. No wasted words, though minimal content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested objects for recipients, attachments, flags, extended properties) and lack of output schema, the description is inadequate. It should clarify what 'eventMessage' means vis-à-vis regular messages and explain updatable versus read-only properties.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high at 75%, with detailed field descriptions in the nested 'body' object. The description provides no additional parameter guidance, but the baseline score of 3 is appropriate given the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('eventMessage object'), but creates confusion by referencing 'eventMessage' while the tool name is 'update-mail-message'. It fails to distinguish from sibling mail operations like forward-mail-message, reply-mail-message, or 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives like send-draft-message or reply-mail-message. No mention of prerequisites (e.g., requiring a message ID) or whether this applies to drafts, sent items, or received messages.
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, establishing it as a mutation. The description adds no behavioral context beyond this—no mention of PATCH semantics, what happens to unspecified fields, required permissions, or effects on linked resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is underspecified for a complex nested-object API with 40+ fields, masquerading as conciseness. For a tool with this parameter depth, the description fails to front-load critical usage patterns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inadequate for the complexity: handles task recurrence, attachments, and checklist items via nested objects, yet the description offers no hints about these capabilities or typical update workflows.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 80% schema coverage, the input schema already documents most fields (title, status, dueDateTime, etc.). The description adds no parameter-specific guidance, meeting the baseline for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb (Update) and resource (todoTask object), but remains generic by saying 'properties' without examples or scope. It fails to distinguish from siblings like 'create-todo-task' or 'delete-todo-task' beyond the obvious verb difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this versus 'create-todo-task' or other task management tools. No mention of prerequisites (e.g., needing IDs from list-todo-tasks) or partial vs full update semantics.
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?
While the description aligns with annotations (destructiveHint: true) by stating 'Delete,' it adds no behavioral context beyond what annotations provide. It fails to disclose that deletion is permanent, explain the optimistic concurrency control (ETag/If-Match requirement), or describe what happens if the ETag check fails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The four-word description contains no verbosity, but it is under-specified for a tool with five parameters including concurrency controls. It front-loads the action but misses critical context that should accompany a destructive operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of destructive annotations, ETag-based concurrency parameters, and hierarchical resource identification (list + task ID), the description is insufficient. It neither explains the permanent nature of deletion nor the purpose of the If-Match header for conflict prevention.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the structured data adequately documents parameters including the If-Match ETag header and response control flags. The description adds no parameter-specific semantics, but the baseline score of 3 applies when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb (Delete) and resource (todoTask object), satisfying baseline clarity. However, it fails to distinguish from sibling delete operations (e.g., delete-planner-task) or indicate that this requires both a task list ID and task ID to locate the resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 prerequisites (e.g., needing to know the todoTaskListId) or whether to use update-todo-task to mark complete versus permanent deletion.
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 'Read-only' statement duplicates the readOnlyHint annotation without adding behavioral context (e.g., pagination behavior via fetchAllPages, OData query options like $filter/$search, or what properties are returned). With annotations covering safety profiles, the description fails to exploit the lowered bar to explain query capabilities or return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences), but 'Represents a collection' is weakly front-loaded and wastes space on static resource description rather than actionable guidance. The second sentence merely echoes the readOnlyHint annotation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters supporting complex OData-style queries (filter, search, expand, orderby, select) and no output schema, the description is insufficient. It fails to explain the query capabilities, pagination behavior, or the nature of returned worksheet metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents all 13 parameters including pagination (top/skip), filtering, and projection options. The description adds no parameter-specific guidance, but the high schema coverage establishes a baseline score of 3 per the rubric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource ('worksheets associated with the workbook') but uses the passive verb 'Represents' instead of active verbs like 'Lists' or 'Retrieves'. It adequately identifies the scope but lacks clarity on the action being performed, requiring inference from the tool 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus related Excel siblings like 'get-excel-range' or workflow prerequisites (e.g., that driveId/driveItemId must be obtained from 'list-folder-files' or 'get-drive-root-item'). The description stands isolated without contextual usage hints.
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, confirming the safe read-only nature. The description adds no behavioral context beyond 'Retrieve', failing to explain pagination behavior (top/skip/fetchAllPages), OData query patterns (filter/select/expand), or that it returns metadata rather than binary content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at six words, but inadequately sized for the tool's complexity. While no words are wasted, the single sentence fails to earn its place by providing sufficient value for a 12-parameter tool with OData-style querying capabilities.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Severely incomplete given the complexity: 12 parameters including pagination, projection (select/expand), search/filter, and response control (excludeResponse). With no output schema and minimal description, agents lack context for the attachment object structure and query capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 12 parameters documented in the schema (top, skip, filter, messageId, etc.). The description mentions no parameters, but the baseline score of 3 applies since the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('attachment objects'), but fails to specify these are email attachments (omitting 'mail' from the name) and lacks scope clarification regarding the required messageId parameter. It does not distinguish from sibling get-mail-attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this versus get-mail-attachment (which retrieves content) versus add-mail-attachment. The critical dependency on messageId (required parameter) is not mentioned in the description.
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?
While annotations confirm readOnly/destructive status, the description adds no behavioral context about pagination defaults, what 'openWorldHint' implies for scope, or how the OData query parameters (filter, expand) behave. Fails to disclose return structure given no output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely brief (4 words) which avoids verbosity, but inappropriately minimal given the tool's complexity (11 parameters including OData query options). Front-loaded with the core action but wastes no words because there are no words to waste—undersized for the functionality described.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inadequate for a complex OData-enabled listing tool with 11 parameters and no output schema. Lacks explanation of what defines a 'notebook object', expected return values, or how to construct valid filter/search queries. Relies entirely on structured metadata without supplemental narrative context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, establishing a baseline of 3. The description adds no parameter-specific guidance (e.g., explaining that 'filter' supports OData syntax or how 'fetchAllPages' interacts with 'top'), but meets minimum expectations given comprehensive schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
States the basic verb (Retrieve) and resource (notebook objects) but lacks specificity regarding OneNote notebook hierarchy (top-level vs sections/pages) and does not distinguish from sibling tools like 'list-onenote-notebook-sections'. Adequate but generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives, when to use pagination parameters versus fetchAllPages, or prerequisites such as user authentication. Zero usage context 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?
No annotations provided, so description carries full burden. Fails to disclose whether selection is persistent across sessions, affects subsequent tool calls, requires prior authentication, or what happens if the accountId is invalid. 'Select' implies state mutation but lacks essential 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is not verbose, but for a tool managing authentication state with zero annotations, this constitutes underspecification rather than efficient communication. Front-loaded but insufficiently detailed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is an authentication management tool with no annotations, no output schema, and unclear relationship to the broader auth lifecycle (login/logout/remove), the description fails to provide adequate context for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage ('The account ID to select'), so the parameter is documented. The description adds no additional semantics about the format of accountId or how to obtain it, meeting baseline expectations for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
States the verb (select) and resource (Microsoft account) but uses vague phrasing 'to use' without clarifying whether this sets a session default, switches context for subsequent calls, or validates the account exists. Does not distinguish from sibling `login` or `list-accounts`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to invoke this tool versus `login`, `logout`, or `list-accounts`. Missing prerequisite information (e.g., that `list-accounts` should be called first to obtain valid IDs) and no mention of when selection is necessary.
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 and openWorldHint, but the description adds no behavioral context beyond this. Missing crucial disclosure that checklist and references parameters require specifically formatted object structures, and lacks explanation of the ETag concurrency behavior implied by the If-Match requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is not wasteful, but is excessively terse for the complexity of the operation. Fails the 'every sentence earns its place' test by providing insufficient information to distinguish this from similar tools or explain critical prerequisites.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested object schema, destructive nature, ETag requirement, and lack of output schema, the description is incomplete. Should explain the relationship between plannerTask and plannerTaskDetails, and the consequences of the update.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 80% schema coverage at the top level, the structural documentation is adequate. However, the description adds no semantic value regarding the complex nested body structure or the special handling required for the empty checklist/references objects (additionalProperties: false).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
States the action (Update) and resource (plannerTaskDetails object) but uses API jargon without plain-English explanation. Fails to distinguish from sibling 'update-planner-task' (which updates the task entity vs its details entity), leaving ambiguity about which 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus 'update-planner-task'. Critically omits that the If-Match/ETag parameter is required for optimistic concurrency control, which is essential for successful invocation of this Microsoft Graph API.
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, establishing this as a safe read operation. The description adds minimal behavioral context beyond this, though the mention of 'another user's contact folder' hints at delegated permissions without explaining authentication requirements or the promised scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While brief at two sentences, the structure is defective due to the incomplete second sentence ending with a colon. This appears to be truncated content rather than intentional conciseness, leaving the reader expecting a list of scenarios that never arrives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters including OData query options (select/expand) and no output schema, the description lacks explanation of pagination behavior (relevant to fetchAllPages), return format, or authentication requirements for the promised cross-user access scenarios. The incomplete sentence significantly undermines completeness for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage (select, expand, fetchAllPages, etc.), establishing baseline understanding. The description mentions 'properties and relationships' which conceptually maps to select/expand parameters, but provides no additional syntax guidance, format details, or examples beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb (Retrieve) and resource (contact object), specifying both properties and relationships. However, the trailing incomplete sentence ('There are two scenarios where an app can get a contact in another user's contact folder:') creates confusion about scope and fails to differentiate from the sibling list-outlook-contacts tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description attempts to provide usage context by mentioning 'two scenarios' for accessing another user's contact folder, but the sentence is incomplete (ends with a colon), leaving the actual guidance absent. No explicit alternatives, prerequisites, or when-not-to-use 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?
Annotations correctly mark this as destructive. The description adds that messages are 'saved in the Sent Items folder,' which is valuable behavioral context. However, it fails to clarify what happens to the original draft (presumably deleted) or acknowledge that the claimed 'send new message' capability is unsupported by 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences are appropriate length, but the final sentence 'Alternatively, send a new message...' does not earn its place—it describes unsupported functionality and sows confusion. Structure is logical but undermined by this factual error.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers draft types and destination folder (Sent Items), providing reasonable context for a send operation. However, it lacks return value description (no output schema exists) and leaves the false 'new message' claim uncorrected, creating a significant gap in accurate behavioral understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, establishing a baseline of 3. The description adds crucial semantic context by specifying the messageId refers to an 'existing draft message' (which could be new/reply/forward types), clarifying the parameter's purpose beyond the generic schema description 'Path parameter: messageId'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The primary purpose 'Send an existing draft message' is clear, but the final sentence 'Alternatively, send a new message in a single operation' is misleading. The input schema only accepts a messageId string, confirming this tool cannot send new message content inline, contradicting the claimed alternative functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this versus sibling send-mail. The 'alternatively' clause conflates this tool's scope with send-mail, potentially causing the agent to incorrectly select this tool when creating a new message from scratch (which requires send-mail). No mention that drafts must be created first using create-*-draft 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?
The description implies mutation (consistent with destructiveHint:true and readOnlyHint:false), but adds no behavioral details beyond annotations. It doesn't clarify whether this is a partial update (PATCH semantics) or requires the full object, nor what happens to omitted fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is not verbose, but at 6 words it is underspecified rather than truly concise. It fails to earn its place by providing specific, actionable information beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters with nested objects containing 30+ fields) and lack of output schema, the description is inadequate. It provides no guidance on the update semantics, required permissions, or how to construct the body payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (high), establishing a baseline of 3. The description mentions 'properties' which vaguely maps to the body parameter, but adds no clarification for contactId path parameter or the includeHeaders/excludeResponse options beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Update' and mentions 'contact object', but fails to specify this is specifically for Outlook (the name implies it, but the description doesn't). It also doesn't distinguish from sibling tools like create-outlook-contact or delete-outlook-contact, and is close to a tautology of the tool 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives (e.g., create-outlook-contact for new contacts), nor prerequisites like obtaining a contactId from list-outlook-contacts first.
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. The description adds minimal behavioral context beyond confirming the read operation, failing to explain OData filtering capabilities, pagination behavior (despite fetchAllPages parameter), or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is efficient, but 'from the tasks navigation property' is verbose technical cruft that adds no actionable meaning for tool selection. Front-loading is acceptable but jargon reduces clarity per word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters including complex OData options and no output schema, the description is minimal but technically sufficient given strong schema coverage. However, it omits functionally important context like 'use filter parameter to narrow large task lists'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 mentions 'specified todoTaskList' which loosely maps to the required todoTaskListId parameter but adds no semantic value for the 11 optional OData query parameters (filter, expand, etc.).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action (Get) and resource (todoTask resources) but obscures clarity with Graph API jargon ('navigation property'). It fails to distinguish from sibling 'get-todo-task' (likely single-item retrieval) or clarify that this returns a collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this versus 'get-todo-task' for retrieving a specific task, nor when to use 'list-todo-task-lists' to find the list ID first. No prerequisites or filtering recommendations are mentioned despite 12 query parameters being available.
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?
Description aligns with annotations (readOnlyHint=true, destructiveHint=false) by using 'Retrieve'. However, it fails to elaborate on 'openWorldHint' implications, rate limits, or what specific 'relationships' are available (tasks, buckets, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single 9-word sentence with no filler. Front-loaded with action verb. However, extreme brevity leaves significant conceptual gaps unexplored for a 6-parameter OData endpoint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Mentions 'properties and relationships' hinting at OData capabilities, but lacks output format details, pagination behavior explanations (despite fetchAllPages param), or Microsoft Planner domain context. Adequate but minimal for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, establishing baseline 3. Description mentions 'properties and relationships' which loosely maps to 'select' and 'expand' parameters, but adds no syntax details, format guidance, or explanations for flags like 'fetchAllPages' or 'excludeResponse'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
States basic purpose with clear verb ('Retrieve') and resource ('plannerplan object'), but fails to distinguish from siblings like 'get-planner-task' or 'list-plan-tasks'. Uses 'plannerplan' as one word while tool name uses 'planner-plan', creating mild confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this versus 'list-plan-tasks' or prerequisites like requiring a valid plan ID. No discussion of alternatives or selection criteria.
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, establishing this is a safe read operation. The description adds marginal value by mentioning 'relationships', which provides context for the 'expand' parameter, but does not disclose rate limits, pagination behavior for expanded relationships, or cache semantics despite openWorldHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is admirably compact with no redundant text, though it may be overly minimal. It does not waste words, but also misses the opportunity to front-load the critical distinction (single task retrieval by ID) in the first clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple get-by-ID pattern and absence of an output schema, the description adequately (if minimally) indicates what data is returned (properties and relationships). However, it omits error handling behavior and doesn't leverage the conciseness to explain the Microsoft Graph API conventions used by this tool family.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds semantic context by mentioning 'properties' and 'relationships', which maps to OData-style querying implied by 'select' and 'expand' parameters, but does not explain the boolean flags (fetchAllPages, excludeResponse) or their interaction with the single-item retrieval pattern.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and identifies the resource ('plannerTask object'), but fails to distinguish this from sibling 'list-planner-tasks'. It doesn't clarify that this retrieves a single specific task by ID versus a collection, which is critical given the required 'plannerTaskId' parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus 'list-planner-tasks' or 'get-planner-plan'. There is no mention of prerequisites (e.g., needing a valid task ID) or error conditions (e.g., task not found).
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 annotations declaring readOnlyHint=true and destructiveHint=false, the safety profile is covered. However, the description adds no behavioral context regarding the OData query capabilities (filter, expand, select), pagination behavior (top/skip/fetchAllPages), or what occurs if the notebookId is invalid. Fails to disclose that this supports complex querying despite having 12 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at 9 words. Front-loaded with the core action. No redundancy. However, for a tool with 12 parameters supporting complex OData operations, this brevity may be insufficient rather than optimally concise—it leaves significant gaps that force the agent to infer behavior from parameter names alone.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high schema richness (100% coverage, 12 params) and annotations covering safety hints, the description provides the minimum viable context: what object is returned and the required parent resource (notebook). However, it omits guidance on the query pattern (OData), pagination strategy, and relationships between parameters like top/skip vs fetchAllPages.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage (top, skip, search, filter, etc. all documented), establishing baseline 3. The description mentions none of these parameters specifically and doesn't add semantic meaning beyond what the schema provides (e.g., doesn't explain that 'search' queries section names or that 'expand' retrieves related entities).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (Retrieve) and resource (onenoteSection objects) with scope (from the specified notebook). Uses API terminology 'onenoteSection' which distinguishes it from sibling tools like list-onenote-notebooks (notebooks vs sections) and list-onenote-section-pages (pages vs sections), though it doesn't explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives (e.g., when to use standard query parameters vs simply fetching all), nor does it mention prerequisites like needing a valid notebookId from list-onenote-notebooks. Single sentence offers no contextual hints.
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, covering safety profile. However, the description adds no behavioral context regarding pagination behavior (despite fetchAllPages parameter), OData query capabilities, or what the response contains. No mention of openWorldHint implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence (9 words) is front-loaded with the action verb. However, given the tool's complexity (12 parameters including OData support), the description may be overly terse rather than appropriately concise—missing opportunity to signal advanced query capabilities.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite rich input schema with OData support and lack of output schema, description provides only minimal context ('page objects'). Missing: return value structure, pagination behavior explanation, or guidance on leveraging the rich filtering/selection capabilities implied by the parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage, establishing baseline of 3. The description only adds semantic mapping for 'specified section' referencing the required onenoteSectionId, but provides no context for the OData query parameters (top, skip, filter, expand) or the fetchAllPages flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Uses specific verb 'Retrieve' and identifies resource 'page objects' and scope 'from the specified section'. Clear distinction from sibling tools like create-onenote-page (creation vs retrieval) and list-onenote-notebook-sections (pages vs sections), though could more explicitly contrast with get-onenote-page-content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives (e.g., when to enumerate pages vs retrieving content of a specific page). No mention of prerequisites beyond the implicit requirement of having a section ID.
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?
Mentions POST operation and default notebook constraint. Annotations indicate destructive and open-world behavior; the description adds context about the default notebook scope but omits details about auth requirements, rate limits, or error behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with reasonable information density, though the URL example ('../onenote/pages?sectionName...') is confusing in a tool context since MCP tools don't use URL query parameters directly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested body object with many read-only fields and no output schema, the description provides insufficient guidance on required fields or expected response structure. It does not explain how to populate the required 'body' parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Misleadingly references 'sectionName query parameter' which does not exist in the input schema (only body, includeHeaders, excludeResponse are present). With 67% schema coverage, the description fails to compensate for the complex nested body structure and instead adds confusing API-specific details that don't map to the tool interface.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific action (Create) and resource (OneNote page) with clear scope constraints (default section of default notebook). Mentions limitation of targeting only default notebooks, implicitly distinguishing from sibling `create-onenote-section-page`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on using sectionName parameter for different sections and notes the default notebook limitation. However, fails to explicitly name the sibling tool (`create-onenote-section-page`) for targeting other notebooks, leaving ambiguity about the alternative.
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; the description confirms this with 'Create.' However, it adds no context about side effects, idempotency, or the 'openWorldHint' indicating external system interaction. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no wasted words. However, given the complex nested input schema and destructive nature, the brevity may underserve the agent; it is appropriately front-loaded with the action verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inadequate for the tool's complexity. The schema contains deeply nested objects (body with parentNotebook, parentSection, etc.), 4 parameters, and destructive annotations, yet the description lacks details on return values, required body fields, or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, establishing a baseline understanding. The description 'specified section' adds semantic meaning to the 'onenoteSectionId' parameter, but offers no guidance on the complex nested 'body' structure required for page content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Create) and resource (page) with scope (in the specified section). It implies the target container via 'specified section,' which aligns with the onenoteSectionId parameter, but does not explicitly differentiate from the sibling tool 'create-onenote-page'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus 'create-onenote-page' or other alternatives. No mention of prerequisites (e.g., obtaining the section ID first) 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 readOnlyHint=true and destructiveHint=false, covering the safety profile. The description mentions 'and their properties' which loosely hints at the select/expand parameters, but provides no details on pagination behavior, OData query syntax, or the return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 11-word sentence with no redundancy. While efficient, it is arguably under-communicating given the 11-parameter complexity. The phrase 'and their properties' earns its place by hinting at projection capabilities.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with complex OData-style querying (filter, select, expand, orderby), the description is inadequate. With no output schema provided, the description should explain what constitutes a 'todoTaskList' and how it relates to tasks, or clarify the OData query pattern. It does neither.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, establishing a baseline of 3. The description mentions 'properties' which indirectly references the select/expand capabilities, but provides no parameter-specific guidance, examples, or syntax details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource as 'todoTaskList objects', distinguishing it from sibling 'list-todo-tasks' (which lists individual tasks). However, it relies on API jargon ('todoTaskList objects') rather than plain language explaining these are task list containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 siblings, nor does it mention prerequisite steps (e.g., selecting an account) or that task list IDs are required to subsequently call list-todo-tasks.
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 provided, so description carries full burden. Fails to disclose that this terminates the current session, invalidates tokens, or that subsequent API calls will fail until re-authentication. No mention of side effects or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at 5 words with no filler. Efficiently front-loaded. However, given zero annotations and the stateful nature of authentication, it is slightly too terse to be maximally useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a session management tool with no output schema and numerous account-related siblings (login, select-account, verify-login), the description is minimally adequate but lacks critical context about session termination and authentication state changes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0 parameters (empty object), establishing baseline 4. Description appropriately does not mention parameters since none exist, and no additional parameter context is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb 'Log out' and resource 'Microsoft account'. However, it does not differentiate from sibling 'remove-account', which may imply deleting stored credentials vs. terminating a session. Clarity is good but not exhaustive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus 'login', 'select-account', or 'remove-account'. No mention of prerequisites (e.g., being logged in) or consequences for subsequent tool calls.
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 explicitly mark this as destructive (destructiveHint: true) and not read-only. The description confirms the creation behavior and mentions folder targeting. However, it lacks disclosure of conflict handling (e.g., duplicate IDs), rate limits, or implications of openWorldHint: true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is front-loaded and efficient, with no redundant content. However, for a complex tool with a large nested body schema and behavioral nuances, this brevity approaches under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation adequately but lacks critical context for a mutation tool: error handling behavior, return value structure (no output schema exists), and folder targeting mechanics. Given the rich input schema, this minimalism leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 67% schema description coverage, the schema documents most body properties. The description mentions 'another contact folder' but fails to explain HOW to specify the target folder (no folderId parameter is visible) or the purpose of includeHeaders/excludeResponse flags.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Add') and resource ('contact'), and distinguishes scope by specifying root folder vs. other contact folders. However, 'Add' is slightly less precise than 'Create', and it lacks explicit differentiation from siblings like update-outlook-contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains WHERE the contact can be added (root or other folders) but provides no guidance on WHEN to use this tool versus alternatives like update-outlook-contact, or prerequisites needed to target a specific folder.
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. Description adds mention of 'relationships' (hinting at expand capability) but doesn't address the fetchAllPages behavior for single objects, error cases (404), or ETag handling implied by includeHeaders.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single efficient sentence with no waste. Slightly boilerplate ('object') but appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple read operation given strong annotations and schema, but lacks mention of Microsoft Graph/Todo context and doesn't hint at the OData-style query parameters (select/expand) behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 7 params documented). Description provides no parameter-specific guidance, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Read') and resource ('todoTask object'), but lacks explicit distinction from sibling 'list-todo-tasks' (collection vs. single instance) and doesn't mention the ID-based lookup nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus 'list-todo-tasks' or prerequisites like obtaining task IDs from a list first. Simply states what it does, not when to choose it.
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 must carry the full burden. It does not clarify what 'available' means (cached vs. authenticated), whether this requires prior authentication, or what the return structure contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of five words with no redundancy. Appropriate front-loaded brevity for a zero-parameter list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimally adequate for a simple list tool with no parameters, but given the lack of annotations and output schema, it should mention the relationship to account selection or the expected return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema contains zero parameters. With no parameters to describe, this meets the baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('Microsoft accounts'), and the term 'available' hints at scope. However, it does not explicitly differentiate from sibling 'select-account' or 'get-current-user' in terms of when to list versus select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives like 'select-account', 'login', or 'verify-login'. The account management workflow (list → select → remove) is not articulated.
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 clearly mark this as read-only and non-destructive. The description adds technical context via the '/calendars navigation property' reference and explains that results can be scoped to calendar groups. Does not address pagination behavior, throttling, or the fact that all parameters are optional OData query options.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence structure that front-loads the primary action. Slightly repetitive phrasing ('get..., get...') and comma splice structure could be tighter, but no extraneous content or marketing language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 optional parameters and no output schema, the description covers the basic retrieval purpose but lacks richness expected for a complex OData endpoint. Does not explain common query patterns, pagination (despite fetchAllPages parameter), or response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for all 11 OData-style parameters (top, skip, filter, etc.). The description adds no parameter-specific guidance, but with comprehensive schema coverage, baseline 3 is appropriate. Description mentions 'specific calendar group' functionality without indicating which parameter controls this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb (Get) and resource (user's calendars) and mentions the underlying Graph API navigation property. Clarifies scope includes default or specific calendar groups. However, does not explicitly distinguish from related siblings like 'list-calendar-events' or 'get-calendar-view', which is important given the dense set of calendar-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes internal variants (all calendars vs specific group) but provides no guidance on when to choose this tool versus the many sibling alternatives (e.g., list-calendar-events vs list-calendars). No mention of prerequisites or constraints.
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 this as readOnly (true) and non-destructive (false), covering the safety profile. The description doesn't add behavioral context beyond this, such as pagination behavior, default page sizes, or Microsoft Graph API specifics implied by the OData-style parameters (filter, expand, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy. However, given the richness of the query interface (11 parameters), an additional sentence mentioning OData query support would improve utility without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately identifies the return type (plannertask objects) and user-assigned scope. However, for a tool with complex querying capabilities (search, filter, expand), it lacks completeness regarding how to leverage these options or what the response structure entails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, documenting all 11 parameters including OData query options (filter, orderby, expand). The description adds no parameter-specific guidance, but with complete schema coverage, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Retrieve), resource (plannertask objects), and scope (assigned to a User). The phrase 'assigned to a User' effectively distinguishes this from sibling tools like list-plan-tasks (likely scoped to a plan) and get-planner-task (singular 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this versus alternatives like get-planner-task (for specific task lookup) or create-planner-task. With 11 query parameters available, there is no direction on how to construct effective queries.
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 and destructiveHint=false, establishing safety. The description adds the scoping context (tasks associated with a plan) but omits behavioral details like pagination behavior (despite the fetchAllPages parameter), rate limits, or error conditions (e.g., invalid plan ID). 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is front-loaded with the action and resource, and contains no wasted words or redundancy. However, it is undersized for the tool's complexity (12 parameters including pagination controls), though this is a completeness issue rather than a conciseness failure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (12 parameters with OData query capabilities) and lack of output schema, the description is minimally adequate. It identifies the return type implicitly ('plannerTask objects') but should explain pagination behavior, the effect of 'fetchAllPages', or provide guidance on the query options available.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds semantic context for the required 'plannerPlanId' parameter by explaining the association with a 'plannerPlan object', but does not elaborate on the OData query parameters (top, skip, filter) or custom parameters like 'fetchAllPages' beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Retrieve') and resources ('plannerTask objects') and clarifies the scope ('associated with a plannerPlan object'), which correctly implies the required plannerPlanId parameter. However, it fails to explicitly distinguish this from the sibling tool 'list-planner-tasks', leaving ambiguity about which list operation 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but provides no guidance on when to use it versus alternatives like 'list-planner-tasks' or 'get-planner-task'. It does not mention prerequisites (e.g., needing a valid plan ID) or when to use the OData query parameters (filter, search) versus fetching all results.
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?
Without annotations, the description carries full burden. It adds critical behavioral context that this only affects local cache, not server-side account deletion. However, it omits side effects (impact on current session, whether re-authentication is required), idempotency, and error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely terse at 7 words, with no wasted language. However, given zero annotations and the tool's destructive nature, additional behavioral context would be warranted without adding verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimum viable for a cache-removal tool. Lacks output description (though none exists) and behavioral depth, but the single-parameter schema is fully documented. Adequate but would benefit from explicit mention of relationship to login/logout workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage ('The account ID to remove'), establishing baseline 3. The description implies the parameter by referencing 'account' but adds no syntax details, format constraints, or examples beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Remove') and resource ('Microsoft account') with scope constraint ('from the cache'), distinguishing it from server-side deletion tools like 'delete-outlook-contact'. However, it fails to differentiate from sibling 'logout' or explain when to prefer removal over logout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus 'logout' or 'select-account', nor prerequisites (e.g., whether the account must not be currently selected). No mention of post-removal steps needed.
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 destructive/write behavior, which the description confirms. It adds valuable context not in annotations: the scope (user vs group calendars) and the critical prerequisite about email resolution workflow. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a clearly demarcated tip. No wasted words. Front-loaded with the core action. The emoji and 'CRITICAL' label effectively highlight the important prerequisite. Could be improved by removing 'Use this API to' boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential action and a critical prerequisite (email lookup), but given the complex nested body parameter (4 params, deep nesting) and lack of output schema, it lacks guidance on typical usage patterns, required sub-fields in the body, or what constitutes a successful creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, the baseline is 3. The description implies usage of calendarId through the calendar type explanation, and the tip hints at the attendees parameter structure, but offers no additional semantic clarity for the complex nested body object which has dozens of properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new event in user or Microsoft 365 group calendars, but fails to distinguish from sibling tool 'create-calendar-event' (likely the default calendar variant). Without explicit comparison, agents cannot confidently select between the two creation 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides excellent specific guidance via the CRITICAL tip to use 'list-users' rather than guessing email addresses, which is a clear prerequisite. However, it lacks guidance on when to use this tool versus the sibling 'create-calendar-event' or other alternatives.
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?
Description confirms write operation ('Create') consistent with destructiveHint=true, but adds no details about return values, side effects, idempotency, or specific behavioral traits beyond what annotations and schema structure 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single efficient sentence with no redundancy. Information is front-loaded and every word contributes to understanding the operation scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for the tool's complexity given high schema coverage and present annotations, but minimal. Lacks guidance on handling the response (no output schema) and explicit prerequisite guidance for obtaining the required list ID.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, baseline is 3. Description adds semantic mapping that 'body' contains the task object and implies 'todoTaskListId' is the target container, but does not elaborate on complex nested body structure or the purpose of optional flags.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb (Create) and resource (task object) with specific container context (todoTaskList), effectively distinguishing from planner tasks and other creation tools. Lacks explicit Microsoft To Do branding but uses domain-specific terminology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus create-planner-task or prerequisite steps (e.g., obtaining todoTaskListId from list-todo-task-lists). While 'specified' implies a required parameter, it does not explain preconditions or sibling 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?
Adds valuable behavioral details beyond annotations: specifies HTML-only format for bodies, and explains extension/custom property support (relevant to openWorldHint). Annotations cover safety profile (readOnly).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
First two sentences are efficient. Contains a structural defect: incomplete sentence fragment about 'two scenarios' ending with a colon. Final sentence is slightly verbose ('you can also use the GET operation').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers output format (HTML) and extensions adequately for a read operation with good annotations and parameter documentation, but the incomplete delegation scenarios leave a gap regarding cross-user permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage so baseline is 3. Description provides context for expandExtendedProperties by mentioning custom properties and sync metadata, but does not elaborate on other parameters like timezone or select/expand patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb (Get) and resource (calendar event properties/relationships), but fails to distinguish from siblings like get-specific-calendar-event 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this versus list-calendar-events or get-calendar-view. Begins to mention cross-user calendar access scenarios but leaves the sentence incomplete after the colon.
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?
Beyond annotations (readOnlyHint), the description adds valuable behavioral context: it specifies retrieval can return 'properties, relationships, or raw contents' (distinguishing metadata vs binary content) and clarifies polymorphic attachment targets (events, messages, posts).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
First sentence is efficient and front-loaded with key information. Second sentence contains a dangling colon ('following types:') suggesting missing enumerated content, wasting space without adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers polymorphic attachment targets and hints at return types (properties vs raw contents), but lacks output schema documentation and guidance on parameter dependencies (messageId/attachmentId hierarchy) given the complexity of 7 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, baseline is 3. The description mentions 'properties' and 'relationships' which loosely maps to select/expand parameters but does not add specific semantics for individual parameters like fetchAllPages or the hierarchical relationship between messageId and attachmentId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb (Read) and resource (attachment) with scope clarification (attached to user event, message, or group post). Distinguishes from mutation siblings (add/delete) by stating read-only intent, though could more explicitly contrast with list-mail-attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this specific tool versus alternatives. It never states that you need specific messageId/attachmentId values (likely obtained from list-mail-attachments or get-mail-message) nor when to prefer this over listing 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?
Annotations declare readOnly=true and destructive=false. Description adds scope context (User/Group/Site targets) but omits pagination behavior (fetchAllPages), OData query pattern explanations, or rate limit details expected for a read-heavy list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is front-loaded and efficient. However, brevity is excessive for a tool with 11 optional query parameters; a second sentence noting all parameters are optional or describing pagination would improve structure without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Critical gap: description mentions targeting User/Group/Site but schema provides no explicit target parameters (e.g., user_id), leaving ambiguity. Also fails to contextualize the OData query pattern (filter, select, expand) for a Microsoft Graph API tool with complex querying capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, documenting all 11 OData-style parameters (filter, select, expand, etc.). Description adds no parameter-specific guidance, earning baseline 3. No contradictions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Retrieve' and resource 'Drive resources' identifies the tool lists drive containers (not contents). Mentions scope 'User, Group, or Site' but doesn't distinguish from sibling 'get-drive-root-item' or clarify how targets are specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage by stating the tool retrieves drives 'for a target User, Group, or Site', indicating scope. However, lacks explicit when-to-use vs. alternatives and omits how to specify the target entity given the schema lacks explicit user/group/site parameters.
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, establishing the safety profile. The description adds that this retrieves children of a DriveItem, providing API-specific context. However, it omits behavioral details about pagination despite the presence of fetchAllPages, top, and skip parameters, and doesn't mention error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. Information is front-loaded with the core operation in the first sentence, and scope clarification in the second. Minor deduction for using technical API jargon ('facet,' 'children relationship') where simpler language ('folders containing files') could improve agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters including OData-style query options (filter, select, expand, orderby) and pagination controls (fetchAllPages), the tool is operationally complex. While annotations cover safety traits and the schema documents parameters, the description lacks domain context (OneDrive/SharePoint) and fails to address pagination behavior despite dedicated parameters for it. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description provides high-level context that parameters operate on DriveItem children relationships, but does not elaborate on specific parameter semantics (e.g., explaining that driveId/driveItemId identify the parent folder, or how filter/search differ).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns a collection of DriveItems in the 'children relationship,' specifying the verb (return) and resource (child DriveItems). However, it relies heavily on Microsoft Graph terminology ('DriveItems,' 'facets') without clarifying this lists files/folders in a OneDrive/SharePoint folder, which slightly hinders accessibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence implies when the tool applies ('DriveItems with a non-null folder or package facet can have one or more child DriveItems'), hinting that this works on folders. However, it lacks explicit guidance distinguishing this from siblings like get-drive-root-item or other file operations, and provides no '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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. The verb 'Check' appropriately signals a read-only status inspection operation, but lacks details on return format (boolean vs. object), error handling when unauthenticated, or whether it triggers interactive login flows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at five words. Front-loaded with action verb 'Check'. No redundant or wasted language; every word serves the purpose statement directly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a zero-parameter diagnostic tool, but incomplete given the absence of an output schema. The description should ideally disclose what information the status check returns (e.g., account identifier, expiration time, or boolean logged-in state) to inform downstream tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema contains zero parameters, establishing a baseline score of 4 per evaluation rules. No parameter documentation is required in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Check' and resource 'Microsoft authentication status' effectively communicate the tool's function. However, it does not explicitly distinguish from the sibling 'login' tool (which likely initiates authentication), which would help the agent understand when to verify status versus establish new credentials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance provided on when to invoke this tool versus alternatives. Given the sibling 'login' tool exists, the description should specify that this is for verification of existing sessions rather than authentication initiation, and ideally note that it should be used before operations requiring valid credentials.
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 destructive/write behavior (destructiveHint:true). Description adds that MIME format saves to Sent Items folder and mentions backend delivery process (though with broken 'see here' reference). Does not disclose failure modes, rate limits, or size constraints for attachments.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Length is appropriate for the tool's complexity. The CRITICAL TIP is usefully highlighted with emoji. However, contains dangling reference ('see here') and slightly repetitive structure ('When using JSON... When using MIME...'). Could be more tightly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers primary workflows (immediate send vs draft, format options, attachments) and prerequisites (email lookup). Lacks coverage of return values (no output schema exists), error conditions, success indicators, or message size limits expected for an email sending operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, providing decent baseline documentation. Description adds context about JSON vs MIME format options for the body parameter and attachment handling behavior. However, completely ignores includeHeaders and excludeResponse parameters, offering no guidance on when to use these boolean flags.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Send') and resource ('message') with specific format options (JSON/MIME). Partially distinguishes from sibling create-draft-email by mentioning draft creation as an alternative workflow, though fails to differentiate from send-draft-message which sends existing drafts versus this tool which sends new messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Strong explicit guidance with the CRITICAL tip mandating use of list-users tool to find recipient addresses rather than guessing. Mentions draft creation as alternative for later sending, implying when NOT to use this tool. Could clarify distinction from send-draft-message for drafts already created.
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?
While annotations establish readOnlyHint=true, the description adds valuable behavioral context: it explains that only a default subset of properties is returned, describes how to access custom properties and extensions (aligning with openWorldHint), and clarifies the OData query pattern. 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informationally dense but contains unnecessary verbosity: references to a 'Properties section' (unavailable to the agent), 'do a GET operation' (implementation detail), and Microsoft Graph-specific jargon. The logical flow is sound but could be more front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description adequately characterizes the return value by explaining the default property subset behavior, extension support, and relationship expansion. Given the 6 parameters and OData complexity, this provides sufficient context for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 meaningful semantic context by explaining that '$select' is used for non-default properties (OData pattern) and referencing 'relationships' (mapping to the expand parameter). It could better explain ConsistencyLevel or pagination behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Retrieve') and resource ('properties and relationships of user object'), but it fails to explicitly specify that this targets the *current* or *authenticated* user, relying instead on the tool name to convey this. It distinguishes from siblings like 'get-outlook-contact' by focusing on the user identity itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful guidance on when to use the '$select' parameter versus default properties, and identifies the Microsoft Entra ID for customers use case. However, it lacks explicit guidance on when to use this tool versus 'list-accounts' or 'select-account' for account management 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, confirming safe read semantics. The description adds the HTML-only format constraint ('returns event message bodies in only HTML format'), which is critical behavioral context not in annotations. Also clarifies the specific entity type (eventMessage) being retrieved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly constructed sentences: purpose statement, expand parameter guidance, and format limitation. Zero redundancy. Information is front-loaded with the core operation first, followed by specific usage notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Appropriate for a read operation with full schema coverage. Covers the core operation, return format limitation (HTML only), and a specific use case (calendar event expansion). Missing only error handling details or explicit mention of the required messageId parameter in the prose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, documenting all six parameters. The description adds significant semantic value by explaining specific usage of the 'expand' parameter ('on the event navigation property'), transforming the generic schema description into actionable guidance for calendar integration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies getting 'eventMessage object' properties, which is precise about the resource type, but creates ambiguity since the tool name is 'get-mail-message' (suggesting general mail). It doesn't clarify if this works for all messages or only calendar event messages, nor does it distinguish from sibling list-mail-messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides specific guidance on using the $expand parameter to retrieve associated calendar events, which is valuable. However, it lacks explicit when-to-use guidance versus list-mail-messages (for bulk) or get-mail-attachment (for content), and doesn't mention prerequisites like messageId format.
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 context beyond the readOnlyHint annotation by explaining that the tool returns 'expanded recurring event instances (not just seriesMaster)' and includes linkage fields like 'seriesMasterId and type.' It also explains the pagination behavior for large result sets. This disclosure of instance expansion behavior is crucial for agents to understand the difference between this and listing raw calendar events.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description suffers from a poor opening with tautological sentences ('The calendar view for the calendar') that should be removed, but the TIP section is efficiently written with high information density. The emoji and 'TIP' label slightly detract from professional conciseness but the content is valuable. Overall, the structure is inverted with API jargon preceding practical guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description adequately explains return values by noting 'Each instance includes seriesMasterId and type fields' and describing the expanded recurring event format. It covers pagination, timezone handling (via parameter), and extended properties options. For a 16-parameter read operation, it successfully highlights the key functional behaviors agents need to understand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline documentation is complete, but the description adds practical usage guidance by emphasizing the ISO 8601 format for date parameters and specifically advising when to use fetchAllPages. The reinforcement of the date format requirements adds clarity beyond the schema examples. This compensates for the high parameter count by highlighting the most critical configuration options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The TIP section clearly states the tool 'Returns expanded recurring event instances... within a date range for a specific calendar,' providing a specific verb, resource, and scope. However, the opening sentence 'The calendar view for the calendar' is tautological and wastes space. The description successfully distinguishes this from generic calendar views by emphasizing the specific calendar ID requirement and expanded recurring event behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear prerequisites stating it 'Requires startDateTime and endDateTime query parameters' and offers pagination guidance ('Use fetchAllPages=true... when there are many events'). While it differentiates implicitly by describing 'expanded recurring event instances' (likely distinct from list-specific-calendar-events), it lacks explicit when-to-use guidance comparing against sibling tools like get-calendar-view. The required parameter emphasis helps agents understand prerequisites.
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?
Beyond the readOnlyHint annotation, the description adds valuable behavioral specifics: it includes modified exceptions but excludes canceled occurrences, and mentions nullable returns. This discloses important domain-specific filtering behavior that annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The first paragraph contains API-documentation cruft ('Navigation property. Read-only. Nullable.') that wastes space without helping tool selection. However, the 💡 TIP section is well-structured and front-loaded with practical guidance, partially redeeming the structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 17-parameter tool with complex recurrence logic, the description adequately covers the critical behavioral edge cases (exceptions vs cancellations) and required query parameters. No output schema exists, but the description sufficiently characterizes the return set composition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage (baseline 3), the description adds meaningful context by specifying ISO 8601 date format requirements and providing concrete examples (e.g., 2024-01-01T00:00:00Z), which helps the agent understand the temporal query constraints better than the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'The occurrences of a recurring series...' which ambiguously describes an API property rather than stating the tool's action, but the TIP section clarifies with 'Expand a recurring event into individual instances.' It distinguishes from siblings like get-calendar-event by focusing on recurrence expansion, though the opening syntax is confusing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The TIP explicitly states when to use this tool: 'Expand a recurring event into individual instances within a date range' and identifies required parameters (startDateTime, endDateTime) with format specification (ISO 8601). Clear prerequisite guidance for targeting recurring series masters.
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 significant behavioral detail not present in annotations, specifically that the `$search` parameter MUST be wrapped in double quotes and accepts KQL operators (from:, subject:, etc.). This critical usage constraint prevents invocation errors. However, it omits other behavioral traits like pagination defaults or rate limiting despite the `readOnlyHint` and `openWorldHint` annotations being present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose statement, followed by the detailed search syntax guide. While the search tip is lengthy (containing examples and a URL), the formatting uses visual cues (💡 TIP: CRITICAL) effectively. However, the verbosity of the examples could be condensed without losing the critical 'double quotes' requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 12 parameters and no output schema, the description adequately covers the complex input requirements (particularly the search DSL) which compensates partially for missing return value documentation. It does not address the `fetchAllPages` behavior or what the tool returns, but the schema coverage is complete for inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3, but the description substantially enriches the `search` parameter semantics beyond the schema's generic 'Search items by search phrases'. It details the mandatory double-quote wrapping, valid KQL operators, and concrete examples, providing essential syntax guidance that raw JSON schema cannot express.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the core purpose (getting messages) and mentions the folder context, distinguishing it from the sibling `list-mail-messages`. However, the phrasing 'Get all the messages in the specified user's mailbox, or those messages in a specified folder' ambiguously suggests the folder parameter is optional when the schema requires `mailFolderId`, creating potential confusion 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive guidance on how to format the `$search` parameter (KQL syntax, double quote requirements), but offers no guidance on when to select this tool versus sibling alternatives like `list-mail-messages` or `get-mail-message`. It does not state prerequisites or when-not-to-use 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?
No annotations provided, so description carries full disclosure burden. Mentions 'device code flow' which hints at user-interactive behavior, but fails to disclose what happens upon invocation (returns verification URL? code? requires polling?), side effects (token storage), or completion 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action verb, zero redundancy. Every word serves a purpose despite extreme brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex auth lifecycle with 5 sibling account/auth tools and no output schema, description lacks guidance on flow completion, return values, or state management. However, it minimally covers the essential authentication intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (force parameter fully described). Description adds no parameter context, but baseline 3 applies since schema adequately documents the single optional boolean flag without additional semantic nuance needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb 'Authenticate', explicit resource 'Microsoft', and precise mechanism 'device code flow'. Distinguishes from siblings like verify-login, logout, and select-account by specifying this initiates the authentication flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage as prerequisite for other Microsoft API operations, but provides no explicit guidance on when to use login vs verify-login or select-account siblings, nor mentions prerequisite conditions (e.g., required before other 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 indicate this is a write operation (destructiveHint=true, readOnlyHint=false). The description adds valuable behavioral context beyond annotations: it explains the two-step workflow (create draft now, send later), details the base64 encoding requirement for MIME format, and notes that drafts can be updated later. 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
While information-dense, the formatting is messy with inconsistent bullet points (using dashes without clear line separation) and the final sentence about single-operation replies is awkwardly appended. The content earns its place, but the structure hinders readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested input schema (Message object with 20+ properties), the description covers the critical format-specific constraints well. However, no output schema exists, and the description fails to indicate what the tool returns (e.g., the created draft object or ID), which is necessary for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (baseline 3). The description significantly adds value by clarifying the mutual exclusivity between the Comment and Message body properties, explaining the base64 encoding requirement for MIME format, and detailing the RFC 2822 logic for recipient handling—none of which are inferable from the schema structure alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a draft reply to a message sender in JSON or MIME format. It mentions the sender specifically, which implicitly distinguishes it from a 'reply-all' operation, though it could explicitly differentiate from siblings like create-reply-all-draft or create-forward-draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not-to-use guidance by mentioning the alternative to 'reply to a message in a single operation' (referring to reply-mail-message). Details specific error conditions (HTTP 400 when both comment and body are specified) and RFC 2822 requirements for replyTo handling, giving clear operational constraints.
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, but the description adds crucial behavioral context not in the structured data: deleting a meeting as organizer sends cancellation messages to attendees. It also notes the event is removed 'from the containing calendar', clarifying scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place. The first states the core operation; the second explains the critical side effect for meetings. No redundancy, appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with 100% schema coverage and clear annotations, the description covers the essential business logic (removal + cancellation behavior). No output schema exists, but the description appropriately focuses on the mutation side effects rather than return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema adequately documents all four parameters including the ETag concurrency control (If-Match). The description correctly relies on the structured schema and does not duplicate parameter documentation, meeting the baseline for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core action ('Removes the specified event') and resource ('containing calendar'). However, it does not explicitly differentiate from the sibling tool 'delete-specific-calendar-event', leaving ambiguity about which deletion tool to select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides valuable behavioral guidance about meeting cancellation side effects, but lacks explicit when-to-use guidance versus alternatives like 'delete-specific-calendar-event' or 'update-calendar-event' (for cancellations).
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?
Beyond the readOnlyHint annotation, the description adds valuable behavioral context: it discloses that 'this operation returns event bodies in only HTML format' (format limitation) and clarifies the distinction between series masters and expanded instances. It attempts to explain cross-user access patterns (relevant to openWorldHint: true) but cuts off mid-sentence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description contains relevant information in the first three sentences, but has a significant structural defect: it ends with an incomplete sentence ('There are two scenarios where an app can get events in another user's calendar:'). This truncation suggests missing content and leaves the description technically incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters with full schema coverage and no output schema, the description adequately covers the core purpose and behavioral constraints (HTML-only, masters vs instances). However, the incomplete final sentence creates a gap regarding delegated access permissions, and there's no mention of pagination behavior despite the presence of pagination parameters (top, skip, fetchAllPages).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage across 13 parameters, the schema definitions carry the full semantic burden. The description does not add parameter-specific guidance (e.g., that 'timezone' accepts IANA names), but at this coverage level, the baseline 3 is appropriate as the schema documentation is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a list of event objects in the user's mailbox' with specific verb and resource. It distinguishes its scope by specifying it returns 'single instance meetings and series masters' (not expanded instances), and explicitly contrasts itself with sibling tools by mentioning 'To get expanded event instances, you can get the calendar view' (referencing get-calendar-view) and 'get the instances of an event' (referencing list-calendar-event-instances).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when not to use this tool ('To get expanded event instances') and alternatives to use instead ('get the calendar view, or get the instances of an event'). However, it contains an incomplete sentence cut off ('There are two scenarios where an app can get events in another user's calendar:') that would have explained delegated access patterns, slightly reducing the guidance quality.
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?
Adds valuable behavioral details beyond annotations: confirms message is saved to 'Sent Items' (immediate send), explains RFC 2822 replyTo handling logic, warns of HTTP 400 errors for invalid input, and clarifies attachment handling differs by format. No contradictions with destructiveHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Contains necessary information but suffers from inconsistent formatting (mixing asterisks and dashes for bullets) and includes emoji. The structure separates format instructions clearly but could be more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex dual-format messaging tool with nested objects and no output schema, the description covers format selection, error conditions, replyTo behavior, draft alternatives, and Sent Items persistence. Missing explicit description of the 'messageId' parameter requirement in text.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, the description adds crucial semantic context: explains 'comment' field purpose, mutual exclusivity with 'body' property, and MIME encoding requirements. The tip clarifies intended use of the comment field for HTML preservation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific action 'Reply to the sender' with format options (JSON/MIME). Implicitly distinguishes from 'reply-all' by specifying 'sender,' but could be more explicit about differences from siblings like 'reply-all-mail-message' and 'create-reply-draft'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on choosing between JSON and MIME formats with constraint details (comment vs body mutual exclusivity, base64 encoding). Mentions 'Alternatively, create a draft...' which guides users toward the draft creation sibling tool when immediate sending isn't desired.
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?
Excellent disclosure beyond annotations: explains the internal mechanics (creates new copy + removes original) which clarifies the destructive behavior declared in annotations. However, misses side effects like message ID changes, rate limits, or destination folder validation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with zero waste. Front-loads the action, follows with implementation mechanics. Every word earns its place; no redundancy with title or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a destructive operation with nested parameters. Explains the atomicity semantics (copy-then-delete) which is critical for understanding data integrity. Does not need to explain return values (no output schema), though could mention error conditions or permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 75%, the description adds crucial semantic context for the undocumented 'body.DestinationId' parameter by specifying 'another folder', indicating the destination is a folder reference. Could further clarify messageId format requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Crystal clear: specific verb (Move) + resource (message) + scope (within mailbox). Distinguishes from copy semantics by clarifying it creates a new copy AND removes the original, differentiating from other mail operations like delete or reply in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus alternatives (e.g., delete-mail-message for permanent removal) or prerequisites (e.g., that messageId must be obtained first). No mention of user permissions or when to prefer move over other organization methods.
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?
Beyond the destructiveHint annotation indicating mutation, the description adds valuable behavioral context: it discloses HTTP 400 error conditions, RFC 2822 compliance requirements for replyTo handling, the ability to update the draft later, and that sending requires a subsequent operation. This helps the agent understand the draft lifecycle and constraint violations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The content is information-dense and necessary for the tool's complexity, but the structure suffers from informal dash-bullet formatting and a grammatically incomplete final sentence fragment ('Alternatively, reply-all to a message in a single action.'). The JSON vs MIME instructions could be more clearly delineated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex dual-format operation with nested object parameters, the description adequately covers input constraints and draft lifecycle. However, lacking an output schema, it should briefly mention what the tool returns (e.g., the created draft object) to be complete. It does not address the 'includeHeaders' or 'excludeResponse' parameters visible in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema has 75% coverage, the description adds critical semantic constraints not captured in the schema structure—specifically the mutual exclusivity rule between 'comment' and 'body' properties within the message parameter, and the base64 encoding requirement for MIME content. This prevents invalid invocations that the schema alone would allow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the specific action (create draft), scope (reply-all to sender and recipients), and supported formats (JSON/MIME). The phrase 'reply to the sender and all recipients' effectively distinguishes this from the sibling 'create-reply-draft' tool which targets only the sender.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed format-specific constraints (e.g., mutual exclusivity of 'comment' vs 'body' properties causing HTTP 400 errors). Mentions 'Alternatively, reply-all to a message in a single action,' implicitly referencing the sibling 'reply-all-mail-message' tool as an alternative, though it could be more explicit about when to choose between creating a draft versus sending immediately.
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?
Strong. Adds critical behavioral details beyond annotations: HTTP 400 error conditions for parameter conflicts, lifecycle notes (can update draft later, send subsequently), and MIME encoding requirements (base64). destructiveHint=true is complemented by 'does not send' clarification. Minor gap: doesn't detail side effects on failure or specific storage location.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Information-dense but slightly verbose. Bullet points effectively organize JSON vs MIME requirements. The 💡 TIP at end repeats the 'does not send' concept mentioned earlier. Front-loading is good (purpose first), but API-level error documentation (HTTP 400 specifics) could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a complex 4-parameter tool with nested objects. Covers both invocation formats (JSON/MIME), validation rules, lifecycle (create → update → send), and alternatives. No output schema exists, and description appropriately doesn't attempt to document return values per scoring rules.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Highly valuable additions. With 75% schema coverage, description compensates for complex 'body' parameter by documenting mutual exclusivity rules (comment vs body, toRecipients param vs property) that schema cannot express, plus MIME-specific encoding instructions. Schema covers basic types; description covers constraint semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Excellent. Opens with specific verb (Create), resource (draft to forward existing message), and format options (JSON/MIME). Explicitly distinguishes from sibling 'forward-mail-message' by noting single-operation forwarding as an alternative, and distinguishes from reply drafts by specifying 'forward'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: bullet points detail JSON vs MIME selection criteria, validation constraints (HTTP 400 triggers), and the TIP explicitly states 'Useful when user wants to review before sending.' Mentions single-operation alternative. Minor gap: could explicitly name the sibling tool (forward-mail-message) for clarity.
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, establishing the read-only safety profile. The description adds valuable behavioral context that the operation excludes hidden folders by default and documents the navigation pattern for folder hierarchies, though it omits pagination or rate limit details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four well-structured sentences with zero waste: purpose statement first, navigation hint second, and hidden folder behavior last. Every sentence delivers distinct value without redundancy. Appropriate length for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (13 parameters with 100% coverage) and readOnly annotations, the description covers the essential behavioral quirks (hidden folders, hierarchy navigation). No output schema exists, but the description adequately addresses the non-obvious aspects of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema handles basic parameter documentation. The description adds crucial semantic meaning beyond the schema for 'includeHiddenFolders' by explaining the default exclusion behavior (schema only states 'Include Hidden Folders'), compensating for the mechanical schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly defines the tool's purpose with specific verb ('Get') and resource ('folder collection under the specified folder'). It effectively distinguishes from sibling 'list-mail-folders' by explaining the '/me/mailFolders' shortcut for top-level folders, implying this tool is for nested/child 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use this tool versus top-level folder listing by referencing the shortcut path. Explains default behavior regarding hidden folders and how to override it. Could be more explicit by explicitly naming the sibling tool for top-level folders, but the guidance 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?
Adds substantial behavioral context beyond annotations: RFC 2822 replyTo handling logic, Sent Items folder side effect, HTTP 400 error condition for invalid parameter combinations, and base64 encoding requirements for MIME. Aligns with destructiveHint=true (mutation) by describing the sending action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Contains valuable information but is somewhat verbose with multiple sections (JSON rules, MIME rules, alternatives, TIP). Structure is logical but could be more front-loaded; the TIP section at the end repeats information from earlier bullets. Every sentence provides value, but tighter integration would improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex dual-format operation with nested parameters and no output schema, description adequately covers format selection, validation constraints, RFC-compliant routing behavior, and storage side effects. Missing explicit description of return values or success indicators, but annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 75% coverage with complex nesting. Description adds critical constraint that 'comment' and 'body' are mutually exclusive in JSON mode (HTTP 400 if both provided), and clarifies that 'comment' represents the reply text. Compensates for complexity of the nested Message object structure within the body parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with specific verb ('Reply to all recipients') and resource ('message'), explicitly distinguishing from sibling 'reply-mail-message' by emphasizing 'all recipients'. Also distinguishes from 'create-reply-all-draft' by noting immediate sending to Sent Items vs. draft creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly references sibling alternative 'create a draft to reply-all... and send it later'. Details when to use JSON vs. MIME format and warns about HTTP 400 error conditions. Could more explicitly contrast with 'forward-mail-message' or single-reply 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 declare readOnly/openWorld traits. Description adds valuable behavioral context: hidden folders are excluded by default, search folders are included in the collection, and the operation is non-recursive (root-only). 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four well-structured sentences front-loaded with primary purpose. Each sentence earns its place: defines scope, clarifies search folder behavior, documents hidden folder defaults, and states recursion limitations. Slight verbosity but logically organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a read-only list tool with 12 query parameters. Covers critical domain-specific behavior (root-only view, hidden folder handling) that prevents misuse. Could optionally mention pagination patterns (top/skip/fetchAllPages) given the traversal complexity discussed, but schema handles standard OData parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage (baseline 3), description adds semantic value by integrating 'includeHiddenFolders' into the narrative and explaining the default behavior (excluded by default) and when to use it, which augments the bare schema description 'Include Hidden Folders'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'Get' paired with resource 'mail folder collection' and precise scope 'directly under the root folder'. Explicitly distinguishes from siblings by clarifying it returns only root children, not all folders in the mailbox, and specifically mentions inclusion of search 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear scope limitation ('only the child folders of the root folder') and explicit guidance that traversal is required for all folders ('each child folder must be traversed separately'). Mentions specific parameter usage for hidden folders. Lacks explicit naming of sibling tool (list-mail-child-folders) for traversal.
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?
Reveals behavioral traits beyond annotations: states message is 'saved in the Sent Items folder', describes HTTP 400 error responses for validation failures, notes base64 encoding requirement for MIME format, and clarifies server-side handling of attachments/HTML. Annotations indicate destructiveness but description adds operational 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear JSON vs MIME sections and bullet points, but contains redundancy between main description and TIP section (repeats comment field behavior and toRecipients requirement). The dual-format explanation is necessary complexity, though the TIP could integrate more smoothly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage for a complex dual-mode tool with nested objects. Addresses both JSON and MIME formats, error conditions, destination folder behavior, and distinguishes from draft creation. No output schema present, but description adequately covers input complexity and behavioral outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, description adds critical mutual exclusivity constraints not captured in schema: conflict between comment vs body property, and between toRecipients parameter vs toRecipients property within message. Also clarifies base64 encoding requirement for MIME body and that toRecipients is effectively required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb ('Forward') + resource ('message') + scope ('using either JSON or MIME format'). Explicitly distinguishes from sibling tool create-forward-draft by stating 'Alternatively, create a draft to forward a message, and send it later', clarifying this sends immediately while the sibling creates a draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names alternative workflow ('create a draft to forward a message, and send it later'). Provides detailed when-to-use constraints: mutual exclusivity rules for comment/body and toRecipients locations, HTTP 400 error conditions for invalid combinations, and format-specific requirements (base64 for MIME).
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. Description adds crucial behavioral context not in annotations: 'Returns expanded recurring event instances (not just seriesMaster)' and clarifies timezone handling via the timezone parameter description in 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with core purpose, followed by 💡 TIP section containing usage guidance. Slightly redundant phrasing 'default calendar, or from some other calendar' could be tighter, but overall efficient with no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 15 parameters, 100% schema coverage, and annotations present, description sufficiently covers behavioral nuances (event expansion) and sibling routing without needing to document return values (no output schema provided).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage (baseline 3). Description adds value by emphasizing 'Requires startDateTime and endDateTime' and providing additional ISO 8601 example '2024-01-01T00:00:00Z', reinforcing the format requirement beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' with clear resource 'occurrences, exceptions, and single instances of events in a calendar view'. The tip explicitly distinguishes from sibling 'get-specific-calendar-view' by stating when to use each (default vs non-default calendar), eliminating 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states alternative: 'Use get-specific-calendar-view if you need a non-default calendar'. Also clarifies this returns 'expanded recurring event instances (not just seriesMaster)', guiding when to use this over list-calendar-events.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/alfredo-ia/ms-365-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server