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

Annotations indicate this is a destructive (destructiveHint: true) and open-world (openWorldHint: true) operation, but the description doesn't add meaningful behavioral context beyond what annotations provide. It doesn't explain what 'destructive' means in this context (does it modify existing messages?), what authentication is needed, or any rate limits. With annotations covering basic safety profile, the description adds minimal value.

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

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

The description is brief (two sentences) but the second sentence is confusing and adds little value. The first sentence states the basic purpose, but the second sentence about attachment types being 'derived from the attachment resource' is unclear and doesn't help an agent understand how to use the tool. The structure could be improved by front-loading clearer purpose information.

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

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

For a destructive tool with 4 parameters (including complex nested objects) and no output schema, the description is inadequate. It doesn't explain what happens after attachment creation, what the response looks like, error conditions, or important behavioral aspects. Given the complexity and the fact that annotations only provide basic safety hints, the description should do much more to help an agent use this tool correctly.

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

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

Schema description coverage is 75%, so the schema already documents most parameters well. The description adds no parameter-specific information beyond what's in the schema - it doesn't explain the relationship between 'body' and 'messageId', what attachment types are actually supported, or how to structure the attachment data. The baseline of 3 is appropriate when the schema does most of the work.

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

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

The description states 'Use this API to create a new Attachment' which provides a verb ('create') and resource ('Attachment'), but it's vague about what specifically is being attached to what. The second sentence about attachment types being derived from the attachment resource is confusing and doesn't clarify the actual purpose. It doesn't distinguish this from sibling tools like 'upload-file-content' or 'create-draft-email' which might also involve attachments.

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

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

The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (like needing a message to attach to), no comparison to similar tools (like 'upload-file-content' for general file uploads), and no indication of when this specific attachment creation is appropriate versus other attachment-related operations.

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

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

Annotations 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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

Annotations provide readOnlyHint=false, openWorldHint=true, and destructiveHint=true, indicating this is a mutating operation that can create new resources and may be destructive. The description 'Creates a new chart' aligns with these annotations by confirming creation behavior, but adds minimal context beyond what annotations already provide. It doesn't specify what 'destructive' means in this context (e.g., overwriting existing charts), rate limits, authentication needs, or response format. With annotations covering the basic safety profile, the description adds some value but lacks rich behavioral details.

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

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

The description is extremely concise with just three words: 'Creates a new chart.' It's front-loaded with the core action and resource, with zero wasted words or redundant information. Every word serves a purpose in communicating the basic function, though this conciseness comes at the cost of completeness.

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

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

For a tool with 6 parameters (4 required), nested objects in the body, no output schema, and annotations indicating destructive mutation, the description is severely incomplete. It doesn't explain what a 'chart' means in this Excel context, what data formats are expected for sourceData, what chart types are supported, or what the response contains. The high parameter count and complexity demand more contextual information than the minimal description provides.

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

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

Schema description coverage is 83%, with 5 out of 6 parameters having descriptions in the schema. The description 'Creates a new chart' adds no parameter-specific information beyond what's already documented in the schema. It doesn't explain the purpose of 'body' properties (type, sourceData, seriesBy) or clarify the relationship between driveId, driveItemId, and workbookWorksheetId. With high schema coverage, the baseline is 3, and the description doesn't compensate with additional semantic context.

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

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

The description 'Creates a new chart' is a tautology that restates the tool name without adding meaningful context. It specifies the verb 'creates' and resource 'chart' but lacks specificity about what kind of chart (Excel chart) or how it relates to the Excel context implied by the input schema parameters. While it distinguishes from some siblings like 'delete' or 'get' tools, it doesn't differentiate from other creation tools like 'create-calendar-event' or 'create-onenote-page' beyond the chart resource.

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

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

The description provides no guidance on when to use this tool versus alternatives. There are no explicit or implicit instructions about prerequisites, context, or comparisons with other tools. Given the sibling tools include 'format-excel-range', 'sort-excel-range', and 'get-excel-range', there's no indication of when chart creation is appropriate versus other Excel operations. The description offers zero usage guidance.

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

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

Annotations indicate this is a destructive, non-read-only, open-world operation, but the description adds no behavioral context beyond 'Create'. It doesn't mention that this is a write operation (implied by 'create'), what permissions might be needed, potential side effects, or how it interacts with planner plans/tasks. With annotations covering basic hints, the description fails to add meaningful behavioral insight.

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

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

The description is extremely concise with a single sentence. It's front-loaded and wastes no words, though this brevity contributes to its lack of helpfulness. For conciseness alone, it scores perfectly.

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

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

Given the complexity (3 parameters, nested objects, no output schema) and annotations, the description is inadequate. It doesn't explain the tool's role in a planner context, required inputs like 'planId' or 'bucketId', or what 'create' entails operationally. For a destructive creation tool with rich schema, more context is needed.

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

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

Schema description coverage is 67%, and the description provides no parameter information. The schema documents parameters like 'body' (with nested properties), 'includeHeaders', and 'excludeResponse' in detail. Since schema coverage is moderate, the baseline is 3, as the description doesn't compensate for the 33% gap but doesn't detract either.

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

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

The description 'Create a new plannerTask' is a tautology that restates the tool name without adding specificity. It doesn't distinguish this tool from sibling tools like 'create-todo-task' or 'create-calendar-event', nor does it clarify what a 'plannerTask' entails beyond the obvious.

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

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

The description provides no guidance on when to use this tool versus alternatives. There are multiple sibling creation tools (e.g., create-todo-task, create-calendar-event), but no indication of when this specific planner task creation is appropriate, what prerequisites exist, or when to choose other tools.

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

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

Annotations indicate this is a destructive (destructiveHint: true), non-read-only (readOnlyHint: false), open-world operation. The description adds no behavioral context beyond this—it doesn't explain what 'destructive' means here (e.g., data persistence, side effects), rate limits, authentication needs, or error handling. With annotations covering basic traits, the description adds minimal value but lacks depth.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.

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

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

Given the tool's complexity (4 parameters, nested objects, no output schema) and annotations that only hint at behavior, the description is inadequate. It doesn't explain the response format, error conditions, or how to interpret the 'body' parameter's extensive structure, leaving significant gaps for a creation tool.

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

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

Schema description coverage is 75%, with detailed docs for most parameters. The description adds no parameter-specific semantics beyond implying a 'body' and 'todoTaskListId' are needed. It doesn't clarify parameter relationships, defaults, or usage examples, so it relies on the schema without compensating for the 25% coverage gap.

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

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

The description clearly states the verb ('Create') and resource ('a new task object in a specified todoTaskList'), making the purpose evident. However, it doesn't differentiate this tool from sibling tools like 'create-planner-task' or 'update-todo-task', which would require more specificity about what makes this todo-task creation unique.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing todoTaskList), exclusions, or comparisons to sibling tools like 'create-planner-task' or 'update-todo-task', leaving the agent without contextual usage cues.

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

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

Annotations 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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description simply repeats 'delete' without additional context (e.g., permanence, authorization needs, side effects).

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

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

Extremely short but vague and uninformative. Not genuinely concise because it omits critical information.

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

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

With 5 parameters (2 required), no output schema, and no explanation of response behavior or error conditions, the description is woefully incomplete for a deletion tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds no extra meaning to parameters; it merely restates the tool's action.

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

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

Description says 'Delete navigation property attachments for me' which is unclear; 'navigation property' is jargon not explained. It does state the verb and generally the resource, but lacks specificity compared to sibling tools like 'add-mail-attachment'.

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

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

No guidance on when to use this tool over siblings like delete-mail-message or delete-excel-table-row. No prerequisites or context provided.

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

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

Annotations provide destructiveHint=true and readOnlyHint=false, clearly indicating a destructive write operation. The description adds no behavioral details beyond this, but since annotations cover the critical safety profile, the bar is lower. No contradiction with annotations.

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

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

The description is a single, efficient sentence with no wasted words. However, it's overly terse and could benefit from slightly more context without losing conciseness.

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

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

Given the destructive nature (annotations cover this), 100% schema coverage, and no output schema, the description is minimally adequate. It lacks details on what 'eventMessage' means or confirmation behavior, but annotations provide critical context.

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

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

Schema description coverage is 100%, with clear parameter documentation in the schema. The description adds no parameter semantics beyond what the schema provides, so it meets the baseline of 3 without adding value.

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

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

The description 'Delete eventMessage' states the action (delete) and resource (eventMessage), but it's vague about what 'eventMessage' refers to in this mail context. It doesn't distinguish from sibling tools like delete-mail-attachment or delete-specific-calendar-event, leaving ambiguity about scope.

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

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

No guidance on when to use this tool versus alternatives like delete-mail-attachment or delete-specific-calendar-event. The description lacks context about prerequisites (e.g., needing messageId) or exclusions, leaving usage unclear.

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

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

Annotations already indicate destructiveness (destructiveHint=true). The description adds no further behavioral context, which is minimal but not contradictory. With annotations present, baseline score is appropriate.

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

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

The description is short but unclear due to jargon. It could be more concise and meaningful, e.g., 'Deletes a OneDrive file.'

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

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

Given the many similar sibling tools and the lack of an output schema, the description should specify the exact resource and any side effects. It fails to differentiate or complete the context, making it inadequate.

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

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

Schema coverage is 100% with adequate descriptions for each parameter. The tool description adds no additional meaning beyond what the schema provides, achieving the baseline.

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

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

The description 'Delete navigation property items for drives' is vague and uses Graph API terminology not clearly indicating deletion of a OneDrive file. It does not align well with the tool name 'delete-onedrive-file' compared to clearer sibling descriptions.

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

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

No guidance is provided on when to use this tool over other delete tools such as delete-drive-item-permission or delete-mail-message. The description lacks context for appropriate invocation.

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

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

Annotations already indicate destructiveHint=true, but the description adds no further behavioral context (e.g., permanence, side effects). It merely repeats the verb from the tool name.

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

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

The description is extremely concise (one sentence) and front-loaded. However, for a tool with multiple parameters and important side effects, a bit more detail could be justified without losing conciseness.

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

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

Given no output schema and 4 parameters with important flags like If-Match and excludeResponse, the description fails to explain usage patterns or outcomes. It is insufficient for an agent to invoke correctly without additional context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for parameters like contactId and If-Match.

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

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

The description 'Delete a contact.' clearly states the action and resource. However, it does not differentiate from sibling tools like delete-contact-folder or delete-mail-message, missing a chance to specify scope.

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

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

No guidance is provided on when to use this tool vs alternatives like update-outlook-contact or other delete tools. The description lacks any context on prerequisites or exclusions.

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

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

The description doesn't contradict the annotations, which already indicate this is a destructive, non-read-only operation with open-world semantics. While the annotations cover the core behavioral traits, the description adds some context by mentioning 'navigation property events,' though this is more confusing than helpful. No additional behavioral details like authentication needs, rate limits, or error conditions are provided.

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

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

While the description is brief (one phrase), it's not effectively concise because it uses confusing terminology ('navigation property events') that doesn't clearly communicate purpose. The structure is poor as it doesn't front-load essential information about what the tool actually does. It's under-specified rather than efficiently concise.

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

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

For a destructive tool with no output schema, the description is inadequate. It doesn't explain what happens after deletion, whether the action is reversible, what the response contains, or how it differs from the sibling 'delete-calendar-event' tool. The annotations provide safety information, but the description fails to add necessary context for proper tool selection and invocation.

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

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

With 100% schema description coverage, the input schema already documents all 5 parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema. The baseline score of 3 reflects adequate parameter documentation through the schema alone, with no additional value from the description.

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

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

The description 'Delete navigation property events for me' is vague and confusing. It doesn't clearly state that this tool deletes a specific calendar event, nor does it distinguish it from the sibling 'delete-calendar-event' tool. The phrase 'navigation property events' is technical jargon that doesn't clearly communicate the tool's function to an AI agent.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling 'delete-calendar-event' tool or explain why this specific version exists. There's no information about prerequisites, context, or when this tool should be selected over other deletion tools.

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

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

Annotations already indicate destructiveHint=true, and the description merely restates the action without adding behavioral traits (e.g., irreversibility, side effects, authorization needs). No additional value beyond annotations.

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

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

The description is a single, efficient sentence with no wasted words. It is appropriately sized for a simple delete operation.

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

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

The description covers the basic purpose but lacks details on return behavior, error handling, or idempotency. It is adequate but not comprehensive for a delete tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema's parameter descriptions, which are already informative.

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

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

The description clearly states the action ('Delete') and the resource ('todoTask object'), making the tool's purpose immediately obvious. It distinguishes itself from sibling tools like delete-todo-task-list or delete-planner-task.

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

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

No guidance is provided on when to use this tool versus alternatives, prerequisites, or when not to use it. The description lacks any usage context.

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

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

Annotations indicate readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering safety and scope. The description adds minimal context by implying it fetches file content, but does not disclose rate limits, authentication needs, or response behavior (e.g., streaming vs. full download). No contradiction with annotations exists.

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

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

The description is a single vague sentence that fails to convey essential information, making it under-specified rather than concise. It lacks front-loaded clarity and does not efficiently communicate the tool's function or usage.

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

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

Given the tool's complexity (6 parameters, no output schema) and rich annotations, the description is insufficient. It does not explain return values, error handling, or practical use cases, leaving gaps in understanding how to effectively invoke the tool.

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

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

Schema description coverage is 100%, so parameters like 'driveId', 'driveItemId', and options such as 'fetchAllPages' are documented in the schema. The description adds no additional meaning beyond the schema, but since coverage is high, the baseline score of 3 is appropriate.

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

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

The description 'The content stream, if the item represents a file' is tautological—it restates the tool name 'download-onedrive-file-content' without specifying the action or resource clearly. It fails to distinguish this tool from siblings like 'get-onenote-page-content' or 'upload-file-content', leaving the purpose vague.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., authentication), context for file retrieval, or differences from other content-fetching tools like 'get-mail-attachment' or 'get-onenote-page-content', making usage unclear.

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

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

Annotations indicate this is a destructive, non-read-only operation, but the description doesn't disclose any behavioral traits beyond what annotations provide. It doesn't mention that this modifies Excel file formatting, potential side effects, authentication requirements, or rate limits. The description adds no meaningful context about the tool's behavior.

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

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

The description is a single sentence, which is appropriately concise. However, it's poorly structured and front-loaded with confusing terminology ('navigation property format') that doesn't clearly communicate the tool's purpose. While brief, it fails to efficiently convey essential information.

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

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

For a complex destructive tool with 6 parameters, nested objects, and no output schema, the description is severely inadequate. It doesn't explain what the tool actually does (format Excel ranges), what resources it affects, what the expected outcome is, or any error conditions. The description fails to provide necessary context for proper tool invocation.

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

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

With 83% schema description coverage, the input schema already documents most parameters well. The description adds no additional meaning about parameters beyond what's in the schema. It doesn't explain the relationship between parameters or provide usage examples. The baseline score of 3 reflects adequate schema coverage without description enhancement.

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

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

The description 'Update the navigation property format in drives' is vague and confusing. It doesn't clearly state that this tool formats Excel ranges (as suggested by the tool name), nor does it specify what 'navigation property format' means. It's essentially a tautology that restates the tool name without clarifying the actual purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (like needing an Excel file in OneDrive), when formatting is appropriate, or how this differs from sibling tools like 'sort-excel-range' or 'get-excel-range'.

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

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

Annotations indicate readOnlyHint=true and destructiveHint=false, covering safety aspects. The description adds valuable context beyond this: it specifies that only a subset of properties is returned by default, explains how to retrieve additional properties via $select, and mentions support for extensions and Microsoft Entra ID customers. This enriches behavioral understanding without contradicting annotations.

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

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

The description is moderately concise but could be more front-loaded; it starts with the core purpose but includes detailed operational notes that might be better structured. Sentences earn their place by explaining defaults, customization, and customer use, but it feels slightly verbose for a simple retrieval tool, reducing efficiency.

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

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

Given the tool's moderate complexity (6 parameters, no output schema), the description is fairly complete. It covers purpose, behavioral nuances like default properties and extensions, and usage hints. With annotations providing safety info and schema covering parameters, the description adds sufficient context, though it could benefit from more explicit guidance on parameter interactions.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds some semantic context by mentioning $select for retrieving non-default properties, which relates to the 'select' parameter, but doesn't elaborate on other parameters like 'ConsistencyLevel' or 'expand'. This meets the baseline of 3 since the schema does the heavy lifting.

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

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

The description clearly states the tool retrieves properties and relationships of the user object, specifying it returns a default subset of properties. It distinguishes itself from siblings by focusing on the current user rather than listing or searching for users. However, it doesn't explicitly contrast with sibling tools like 'list-accounts' or 'search-query' for user retrieval, keeping it at a 4 instead of a 5.

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

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

The description implies usage by mentioning how to get non-default properties via $select and extensions, but it doesn't explicitly state when to use this tool versus alternatives like 'list-accounts' or general search tools. It provides some context on customization options but lacks clear when/when-not guidance or named alternatives, resulting in an implied usage score.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds 'Read-only' which is redundant but not contradictory, and mentions it's for the 'root folder', providing some context. However, it lacks details on rate limits, authentication needs, or response format that would enhance transparency beyond annotations.

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

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

The description is extremely concise with two short phrases, front-loading the core purpose ('The root folder of the drive') and a key behavioral trait ('Read-only'). Every word earns its place without redundancy or fluff.

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

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

Given the tool's moderate complexity (6 parameters, 1 required) and rich annotations (readOnlyHint, openWorldHint), the description is minimally adequate. However, with no output schema, it doesn't explain return values like folder structure or error cases, and it lacks usage context, leaving gaps for an agent to infer proper invocation.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds no parameter-specific information beyond what's in the schema, such as explaining how 'select' or 'expand' work in this context. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool retrieves 'the root folder of the drive' with a 'Read-only' operation, providing specific verb+resource. However, it doesn't differentiate from sibling tools like 'list-drives' or 'list-folder-files', which could also retrieve drive-related information, so it misses full sibling distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites like needing a valid driveId, nor does it compare to sibling tools such as 'list-drives' for broader drive listings or 'list-folder-files' for non-root items.

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

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

Annotations provide readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds no behavioral context beyond what annotations already declare - no information about what gets returned, rate limits, authentication needs, or Excel-specific behaviors. However, it doesn't contradict annotations, so it meets the lower bar when annotations are present but adds minimal value.

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

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

While technically concise with only three words, this is under-specification rather than effective conciseness. The description fails to front-load essential information about what the tool does. Every word should earn its place, but 'Invoke function range' provides almost no value beyond the tool name itself, making it inefficient despite its brevity.

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

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

For a tool with 7 parameters (4 required), no output schema, and operating on Excel data, the description is severely inadequate. While annotations cover safety, the description fails to explain what Excel range data gets returned, format considerations, or how this fits within the broader Excel tool ecosystem. The agent would struggle to use this effectively without extensive trial and error.

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

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

With 100% schema description coverage, all 7 parameters are documented in the schema itself. The description adds zero parameter information - it doesn't explain the hierarchical relationship between driveId, driveItemId, workbookWorksheetId, and address, or provide Excel-specific context about address format. The baseline of 3 is appropriate when the schema does all the heavy lifting.

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

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

The description 'Invoke function range' is a tautology that restates the tool name 'get-excel-range' without adding meaningful context. It doesn't specify what resource is being retrieved (Excel range data), what the verb actually does (retrieve/read), or how it differs from sibling Excel tools like 'format-excel-range' or 'sort-excel-range'. The purpose remains vague despite the clear naming convention.

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

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

The description provides absolutely no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (like needing an Excel file), comparison to sibling tools (like 'list-excel-worksheets' or other Excel manipulation tools), or appropriate contexts for invocation. The agent receives zero usage direction beyond what can be inferred from the tool name.

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

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

Annotations provide readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering safety and flexibility. The description adds context about attachment types and the scope of what can be read (properties, relationships, raw contents), which is useful beyond annotations. However, it doesn't disclose behavioral traits like rate limits, auth needs, or response format details that would enhance transparency.

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

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

The description is two sentences that efficiently state the purpose and attachment types. It's front-loaded with the core action and avoids unnecessary details. However, the second sentence is slightly redundant ('All these types...') and could be tighter, but overall it's appropriately sized with minimal waste.

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

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

Given 7 parameters, 100% schema coverage, and annotations covering safety, the description is adequate but has gaps. It lacks output schema, so return values aren't explained, and it doesn't address usage context or error handling. For a read tool with rich annotations, it's minimally complete but could better integrate with the structured data.

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

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

Schema description coverage is 100%, with all 7 parameters well-documented in the schema. The description adds no parameter-specific information beyond the general scope of reading attachments. This meets the baseline of 3 since the schema carries the full burden, but the description doesn't compensate with additional semantic context (e.g., how 'select' interacts with attachment types).

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

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

The description clearly states the verb ('Read') and resource ('properties, relationships, or raw contents of an attachment') with specific context ('attached to a user event, message, or group post'). It distinguishes from siblings like 'list-mail-attachments' (which lists) and 'add-mail-attachment'/'delete-mail-attachment' (which modify), but doesn't explicitly name these alternatives. The purpose is specific but could be more differentiated.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It mentions attachment types but doesn't clarify when to choose this over 'list-mail-attachments' for discovery or other get-* tools for different resources. There's implied context (reading specific attachments), but no when/when-not statements or named alternatives.

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

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

Annotations already declare 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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

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

The description 'The page's HTML content' is a noun 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering safety and flexibility. The description adds minimal behavioral context beyond this, such as mentioning 'properties and relationships' which hints at the data structure, but doesn't detail pagination behavior, authentication needs, or rate limits. With annotations providing core safety info, a baseline 3 is appropriate as the description adds some value but not rich behavioral disclosure.

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

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

The description is a single, efficient sentence that gets straight to the point without unnecessary words. It's appropriately sized for a simple retrieval tool, though it could be slightly more informative without losing conciseness. Every word earns its place, but it's borderline minimal.

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

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

Given the tool's moderate complexity (6 parameters, 1 required) and rich annotations (readOnlyHint, openWorldHint), the description is adequate but has clear gaps. It lacks output details (no output schema provided), usage context relative to siblings, and deeper parameter guidance. For a retrieval tool with good annotation coverage, it meets minimum viability but doesn't fully leverage the opportunity to be more helpful.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds no parameter-specific semantics beyond what's in the schema, such as explaining what 'select' or 'expand' mean in the context of a planner plan. Baseline 3 is correct when the schema does the heavy lifting, though the description could have added context like example usage or common parameter combinations.

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

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

The description clearly states the verb ('Retrieve') and resource ('plannerplan object'), making the purpose understandable. However, it doesn't distinguish this tool from similar read operations like 'get-planner-task' or 'get-calendar-event' in the sibling list, which would require mentioning it specifically fetches plan-level data rather than task-level or other entity data.

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

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

The description provides no guidance on when to use this tool versus alternatives. With siblings like 'list-planner-tasks' and 'get-planner-task', there's no indication whether this is for fetching a single plan by ID versus listing plans or tasks, or how it relates to other planner tools. This leaves usage context entirely implicit.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds minimal behavioral context beyond this, such as mentioning 'properties and relationships', but doesn't detail response format, pagination, or error handling. With annotations covering safety, a 3 is appropriate as the description adds some value but not rich behavioral insights.

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

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

The description is a single, efficient sentence with no wasted words, clearly stating the action and object. It's appropriately sized and front-loaded, making it easy to parse quickly.

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

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

Given the tool's complexity (6 parameters, no output schema) and rich annotations, the description is adequate but lacks completeness. It doesn't explain return values, error cases, or how parameters like 'select' and 'expand' affect the response, leaving gaps for an agent to infer behavior.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any parameter-specific details beyond what the schema provides, such as examples or usage tips. Baseline 3 is correct when the schema handles parameter documentation fully.

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

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

The description clearly states the verb ('Retrieve') and resource ('plannerTask object'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get-planner-plan' or 'list-planner-tasks' beyond the object type, missing explicit scope comparison.

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

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

No guidance is provided on when to use this tool versus alternatives like 'list-planner-tasks' or 'update-planner-task'. The description lacks context about prerequisites, such as needing a valid plannerTaskId, or exclusions for usage.

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

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering safety and scope. The description adds minimal behavioral context beyond this, confirming it's a read operation but not detailing aspects like error handling, authentication needs, or rate limits. No contradiction with annotations exists.

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

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

The description is a single, efficient sentence that front-loads the core purpose without unnecessary details. Every word earns its place, making it easy to parse quickly while avoiding redundancy.

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

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

Given the tool's moderate complexity (7 parameters, no output schema) and rich annotations, the description is minimally adequate. It covers the basic operation but lacks details on return values, error cases, or integration with sibling tools, leaving gaps for an agent to infer usage in context.

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

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

Schema description coverage is 100%, so the schema fully documents all 7 parameters. The description adds no additional meaning about parameters beyond implying the tool reads properties and relationships, which aligns with 'select' and 'expand' parameters. Baseline 3 is appropriate as the schema handles parameter documentation.

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

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

The description clearly states the verb ('Read') and resource ('todoTask object'), specifying it reads properties and relationships. It distinguishes from siblings like 'create-todo-task' and 'update-todo-task' by focusing on reading rather than modifying, but doesn't explicitly differentiate from other read tools like 'list-todo-tasks' beyond scope differences.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage for reading a specific task, but doesn't mention when to choose this over 'list-todo-tasks' for multiple tasks or other read operations. There's no context about prerequisites or exclusions.

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

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

With no annotations provided, the description carries full burden but only states the action without disclosing behavioral traits such as whether it requires authentication, returns paginated results, or includes inactive accounts. It's a basic statement that leaves critical operational details unspecified.

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

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

The description is a single, efficient sentence that directly states the tool's function without any unnecessary words. It's front-loaded and wastes no space, making it highly concise and well-structured for its purpose.

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

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

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate but lacks context on authentication needs, return format, or sibling differentiation. It meets basic requirements but doesn't fully compensate for the absence of structured data.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't add parameter details, aligning with the schema's completeness, though it could hint at implicit context like authentication requirements.

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

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

The description clearly states the verb ('List') and resource ('all available Microsoft accounts'), making the purpose unambiguous. It doesn't differentiate from siblings like 'select-account' or 'remove-account', which would require more specific scope or filtering details.

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

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

No guidance is provided on when to use this tool versus alternatives like 'select-account' for choosing a specific account or 'verify-login' for authentication checks. The description implies a general listing function but lacks explicit context or exclusions.

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

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

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, indicating a safe, read-only operation with potentially large result sets. The description adds minimal behavioral context beyond this, mentioning the target scope but not detailing pagination behavior, rate limits, or authentication requirements. It doesn't contradict annotations, but adds limited value given the annotation coverage.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Retrieve the list of Drive resources') without unnecessary details. It avoids redundancy with the tool name ('list-drives') and schema, making every word count. The structure is clear and direct, with no wasted verbiage.

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

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

Given the tool's complexity (11 parameters, no output schema) and rich annotations, the description is minimally adequate. It covers the basic purpose but lacks context on result format, error handling, or integration with sibling tools. The annotations provide safety and scope hints, but the description doesn't fully compensate for the missing output schema or parameter guidance, leaving gaps for the agent.

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

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

Schema description coverage is 100%, with all 11 parameters well-documented in the schema (e.g., 'top' for limiting items, 'filter' for property-based filtering). The description adds no parameter-specific semantics beyond implying a target scope ('User, Group, or Site'), which isn't reflected in the parameters. This meets the baseline for high schema coverage but doesn't enhance understanding of parameter use.

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

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

The description clearly states the verb ('Retrieve') and resource ('list of Drive resources'), specifying the target scope ('for a target User, Group, or Site'). It distinguishes from siblings like 'list-folder-files' or 'get-drive-root-item' by focusing on Drive resources rather than specific files or root items. However, it doesn't explicitly differentiate from other list tools like 'list-accounts' or 'list-calendars' beyond the resource type.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., authentication state), compare with similar tools (e.g., 'search-query' for filtered searches), or specify use cases (e.g., browsing vs. filtered retrieval). The agent must infer usage from the tool name and parameters alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds 'Read-only,' which is redundant, and 'Represents a collection,' which implies listing but lacks details on pagination, error handling, or response format. It doesn't contradict annotations, but adds little behavioral context beyond what annotations provide.

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

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

The description is extremely concise with just one sentence: 'Represents a collection of worksheets associated with the workbook. Read-only.' It's front-loaded and wastes no words, making it easy to parse quickly. Every part contributes, though it could be more informative.

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

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

Given the tool's complexity (13 parameters, no output schema) and rich annotations (readOnlyHint, openWorldHint), the description is minimally adequate. It states the purpose but lacks details on usage, behavior, or output. With annotations covering safety, it's not incomplete, but doesn't fully compensate for the missing output schema or parameter guidance.

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

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

Schema description coverage is 100%, so the schema fully documents all 13 parameters. The description adds no parameter-specific information beyond the general 'collection' context. This meets the baseline of 3, as the schema handles the heavy lifting, but the description doesn't enhance parameter understanding.

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

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

The description clearly states the tool's purpose: 'Represents a collection of worksheets associated with the workbook. Read-only.' It specifies the verb 'represents' (though 'lists' would be more precise) and resource 'worksheets associated with the workbook,' distinguishing it from siblings like 'get-excel-range' or 'format-excel-range.' However, it doesn't explicitly differentiate from other list tools (e.g., 'list-folder-files'), so it's not a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing driveId and driveItemId), compare to other list tools, or specify use cases. The only hint is 'Read-only,' which is covered by annotations, leaving the agent with minimal usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering safety and openness. The description adds some behavioral context by explaining that it returns 'children' of a DriveItem and that only items with 'folder or package facet' can have children, which clarifies scope. However, it doesn't disclose pagination behavior (implied by 'top'/'skip' params), rate limits, authentication needs, or error conditions. With annotations providing core safety info, the description adds moderate value but lacks rich behavioral details.

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

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

The description is concise with two sentences: the first states the core purpose, and the second adds clarifying scope. There's no wasted text or redundancy. However, it could be more front-loaded by explicitly naming key parameters or usage context, and the second sentence is somewhat technical ('non-null folder or package facet'), which slightly reduces clarity.

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

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

Given the tool's complexity (13 parameters, no output schema), the description is minimally adequate. Annotations cover safety (readOnly, non-destructive, openWorld), and the schema fully documents parameters. The description adds basic purpose and scope but lacks details on return format (e.g., structure of DriveItems), error handling, or pagination behavior. For a list tool with many parameters, more contextual guidance would improve completeness.

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

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

Schema description coverage is 100%, with all 13 parameters well-documented in the schema (e.g., 'top' for limiting items, 'search' for filtering). The description adds no parameter-specific information beyond the schema. It mentions 'DriveItems' and 'children relationship,' which loosely relates to 'driveId' and 'driveItemId,' but doesn't explain parameter usage or interactions. Given high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but doesn't need to.

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

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

The description clearly states the tool's purpose: 'Return a collection of DriveItems in the children relationship of a DriveItem.' It specifies the verb ('Return'), resource ('DriveItems'), and scope ('children relationship of a DriveItem'), and distinguishes it from siblings like 'list-drives' or 'list-excel-worksheets' by focusing on folder contents. However, it doesn't explicitly differentiate from similar list tools (e.g., 'list-mail-folder-messages') beyond the resource type.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions that 'DriveItems with a non-null folder or package facet can have one or more child DriveItems,' which implies usage for folders/packages, but doesn't specify prerequisites (e.g., needing driveId and driveItemId) or contrast with other list tools (e.g., 'search-query' for broader searches). No explicit when/when-not instructions or named alternatives are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering safety and flexibility. The description adds minimal behavioral context ('retrieve a list'), which doesn't contradict annotations. However, it misses opportunities to explain pagination behavior (implied by 'top'/'skip'), search/filter capabilities, or that it returns a list rather than details—though these are somewhat inferable from parameters.

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

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

The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action ('retrieve'), though it could be more specific. Every word earns its place, making it highly concise and well-structured for quick scanning.

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

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

Given the tool's complexity (12 parameters, no output schema) and rich annotations, the description is minimally adequate. It states the basic purpose but lacks context on output format, error handling, or integration with siblings. The schema and annotations cover safety and parameters, but the description doesn't fully compensate for the missing output schema or provide holistic guidance.

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

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

Schema description coverage is 100%, with all 12 parameters well-documented in the schema (e.g., 'top' for limiting items, 'search' for phrases). The description adds no parameter-specific information beyond the generic 'list of attachment objects,' so it doesn't enhance understanding of individual parameters. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

The description 'Retrieve a list of attachment objects' clearly states the verb ('retrieve') and resource ('attachment objects'), but it's vague about scope and doesn't distinguish from sibling tools like 'get-mail-attachment' (which retrieves a single attachment) or 'list-mail-messages' (which lists messages rather than attachments). It lacks specificity about what 'attachment objects' means in this context.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a messageId), differentiate from 'get-mail-attachment' for single attachments, or explain when filtering/pagination parameters are appropriate. The agent must infer usage from the schema alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the 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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.