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

Annotations already declare readOnlyHint/idempotentHint, but the description adds substantial behavior beyond them: the browser opens locally, the tool returns immediately, repeat calls reuse a pending attempt rather than spawning another window, consent is incremental, and no token is ever returned. It even adds a safety directive (never ask the user to paste credentials or an authorization code).

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

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

Front-loaded with the mechanism before routing guidance, and most sentences carry distinct information. It is on the long side, with the incremental-consent point restated in both the description and the `scopes` guidance, but no sentence is filler.

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

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

No output schema exists, yet the description covers the async result path by pointing to auth_login_status, explicitly states no token is returned, and explains the consent scope semantics for both parameters. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic framing beyond the schema: a bare call asks only for the minimal set, each repeat consents to just what was added, and `full` avoids consenting to admin-only/tenant-blocked scopes. This goes slightly beyond the schema text even though the two overlap on the `scopes` guidance.

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?

Names a specific verb and resource (starts OAuth 2.0 browser sign-in to Microsoft 365 using authorization code + PKCE) and distinguishes itself from the sibling auth_login_status by explaining that it returns immediately while the status tool reports completion. An agent can tell it apart from session_status and graph_request without opening schemas.

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

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

Explicitly states when to call it (a tool reports no session), when to call again with `scopes` (a tool reports missing consent), the incremental nature of consent, and what `mode: "full"` does instead. It also names the follow-up tool auth_login_status and the alternative of a bare call for minimal consent. Nothing is left to inference.

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

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

Annotations already establish the safe read-only/idempotent profile, and the description adds substantial context beyond them: the fallback to a cached account when no browser sign-in occurred, the guarantee that no token is ever returned, and the fact that the call returns immediately (non-blocking). These are behavioral traits an agent could not infer from the structured fields.

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?

Every sentence earns its place: the return-state enumeration, the cached-account edge case, the no-token guarantee, and the polling instruction. The purpose is front-loaded and there is no filler.

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

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

There is no output schema, but the description enumerates all return states and their meanings, so an agent knows exactly what to expect. Combined with the fallback and no-token notes, nothing needed to call or interpret this tool is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; there are no parameter semantics for the description to clarify. The description does not need to compensate for anything here.

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 concrete verb and resource (reports the state of the browser sign-in started by auth_begin_login) and enumerates the exact values it can return. It clearly distinguishes itself from its sibling auth_begin_login, which starts the flow rather than reporting on it.

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

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

It gives explicit usage direction ('Poll it rather than waiting') and ties itself to the prerequisite auth_begin_login, which is clear context for when to call it. It stops short of naming alternatives or stating when not to use it, e.g. versus the sibling session_status, so it falls just short of a 5.

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

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

Beyond the annotations, the description discloses critical behavioral details: the side effect of immediately sending invitations to attendees, the return of the created event, and the timezone interpretation for naive start/end values. This is exactly the kind of context an agent needs for a mutating tool.

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

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

Three sentences, each earning its place: purpose/return, side-effect warning, and timezone behavior. The most important operational warning is front-loaded after the purpose, and there is no redundant or filler text.

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

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

For a 10-parameter mutation tool with no output schema and minimal annotations, the description covers the non-obvious essentials: target calendar, return value, immediate invitation side effect, and ambiguous timezone handling. The remaining parameter details are already fully documented 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?

Schema coverage is 100%, so the baseline is 3. The description adds one meaningful clarification beyond the schema: when timeZone is omitted, naive times default to UTC. It does not repeat parameter docs, which is appropriate.

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

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

The description states a specific verb and resource: 'Creates an event on the primary calendar' and adds that it returns the created event. This clearly distinguishes it from update, delete, respond, and list tools in the sibling set.

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

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

The description gives clear context for when to use the tool: creating a new calendar event on the primary calendar. It also provides explicit pre-call guidance by warning that attendees will receive invitations immediately and telling the agent to confirm details first. It does not explicitly name alternatives, but the usage context is clear.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond that. It discloses that the event is moved to Deleted Items, that attendees receive cancellations when the user organized, and that the invitee-only case removes it without notifying the organizer. It also explains series master behavior. This is rich behavioral context that annotations alone do not convey.

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

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

The description is three sentences, each carrying distinct and essential information: the primary action and its outcome, the attendee vs organizer behavior, and the series master handling. It is front-loaded with the core action and has zero filler, making it efficient for an agent to parse.

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

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

Given the complexity of the delete operation (different behavior for organizer vs invitee, series handling), the description covers all critical decision points an agent needs to invoke the tool correctly. There is no output schema, but a delete typically returns a standard success/failure, so no return format is necessary. The description is complete for safe and correct usage.

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

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

The schema has a single 'id' parameter with full 100% coverage, and the description references the series master case, which gives additional meaning to that id: it may represent a series master and then all occurrences are deleted. While the description does not explicitly say 'if the id is a series master,' it implies it, adding value beyond the schema's minimal 'Event id to delete.' This warrants a 4 rather than the baseline 3.

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

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

The description clearly states the action: 'Deletes an event, moving it to Deleted Items.' It specifies the resource (calendar event) and the immediate effect. It also distinguishes itself from the sibling calendar_respond_event by explaining the attendee vs organizer scenario, which prevents an agent from confusing the two 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?

The description explicitly states when to use this tool versus the alternative: 'use calendar_respond_event with decline for that.' It also covers the series master case, clarifying that deleting a series master deletes all occurrences. This gives clear usage boundaries and eliminates guesswork about which tool fits the situation.

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 meaningful behavioral context beyond the annotations: it notes the tool is 'Read-only despite being an HTTP POST' and explains that empty results include an 'emptySuggestionsReason' such as 'AttendeesUnavailable' or a too-narrow window. This discloses behavior that annotations alone do not convey.

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

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

The description is three concise, front-loaded sentences. It opens with the core function, then adds key behavioral details 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 parameter schema and annotations, the description covers the main operational aspects: ranking, default count, required attendees, and empty-result behavior. With no output schema, it appropriately mentions the emptySuggestionsReason that callers would need to interpret results, though it could slightly expand on the shape of successful suggestions.

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 input schema already documents all parameters. The description adds minor clarifications (default of 10 suggestions, all attendees required) but does not substantially enrich parameter meaning beyond the schema.

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

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

The description uses a specific verb and resource: 'Suggests meeting slots that work for the signed-in user and the given attendees, ranked by confidence.' It clearly distinguishes this from sibling tools like calendar_get_schedule by focusing on proposing available times rather than reading existing events.

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

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

The description implies usage: use this when you need to find meeting slots for a set of attendees. However, it does not explicitly state when to use this tool versus alternatives such as calendar_get_schedule or calendar_list_events, nor does it provide exclusion criteria.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavioral details beyond annotations: the description body is HTML-converted to text and capped (a truncation limit), and it mentions recurrence summary and the Outlook web link. This gives the agent a good sense of the return shape and transformation applied, going beyond the basic read-only nature.

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

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

Two sentences with no redundancy. The first sentence enumerates the return fields in a compact list, and the second gives the essential usage instruction. All content earns its place; nothing extraneous.

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

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

For a simple read tool with one required parameter, the description is quite complete. It lists all major return fields, explains the prerequisite, and the schema covers timezone handling. It doesn't mention error behavior (e.g., event not found) but that is standard and not critical for an agent to invoke correctly. Overall, an agent has enough to call it properly.

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

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

Schema coverage is 100%: both id and timeZone are fully described in the schema. The description does not add new parameter semantics, though it reiterates the id source ('from calendar_list_events') which is already in the schema. Baseline of 3 is appropriate given the schema carries the parameter documentation burden.

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

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

The description clearly states the tool's purpose: returns one event in full, listing the specific fields (subject, start, end, location, organizer, attendees, description, recurrence, link). This distinguishes it from sibling tools like calendar_list_events (which lists events) and calendar_get_schedule (which gets availability) by focusing on a single event's complete 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?

Provides explicit guidance to use calendar_list_events first to find the id, which is the key prerequisite. It clearly implies this tool is for retrieving a single event after identifying it. Does not explicitly contrast with alternatives like calendar_get_schedule, but the usage context is clear from the instruction.

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/idempotentHint annotations, the description adds genuinely useful behavioral detail: it is read-only despite being an HTTP POST, the availabilityView character encoding (0-4), the inclusion of working hours and busy blocks, and the visibility caveat for subject/location. This is substantial context an agent would not get from annotations alone.

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

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

Three sentences, front-loaded with the core purposematic and then adding the encoding details and caveat. Every sentence carries essential information and there is no redundancy or filler.

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

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

With no output schema, the description compensates by explaining the availabilityView encoding, working-hours return, busy blocks, and visibility behavior. It is slightly vague about the exact structure of 'visible busy blocks' but is otherwise sufficient for an agent to invoke and interpret the result.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description reinforces some constraints (20 people, time window, interval characters) but does not add significant new parameter-level meaning beyond what the schema provides.

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

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

The description uses a specific verb ('returns') and clearly names the resource: free/busy availability for up to 20 people or rooms over a time window. It also details the output format, making it easy to distinguish from calendar_list_events or calendar_get_event.

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

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

The description clearly establishes its context: checking free/busy availability for multiple people/rooms over a time window. It does not explicitly name sibling alternatives or exclusion conditions, but the purpose is distinct enough that an agent can infer when to use it, particularly against calendar_find_meeting_times.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it 'Returns 50 by default' (pagination limit) and further explains the return payload fields. These are behavioral traits not in the annotations, adding value beyond the structured metadata. No contradictions found.

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

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

The description is only two sentences, with the core purpose front-loaded and the default behavior and chaining guidance included in the second sentence. No fluff, no redundant repetition of schema or annotations. Every sentence earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It tells the agent what it returns (fields), the default page size, how to use the results (via calendarId), and implicitly that it operates on the signed-in user's calendars. Nothing essential is missing.

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

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

The schema description coverage is 100%, and the only parameter `top` is fully documented in the schema (maximum, default, meaning). The description repeats the default of 50 but does not add any new meaning beyond the schema. Per the rubric, a baseline of 3 is appropriate when the schema already covers parameter semantics.

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

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

The description clearly states the verb 'Lists' and the resource 'the signed-in user's calendars', enumerating the fields returned (id, name, colour, owner, edit/share flags). This is specific and distinguishes it from sibling tools like calendar_get_event (which fetches a single calendar) and calendar_list_events (which lists events). The scope is unambiguous.

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

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

The description provides clear usage context by saying 'Use the returned id as calendarId in calendar_list_events', which tells the agent a common workflow. It does not explicitly contrast with alternatives like calendar_get_event, nor state when not to use it, but the chaining instruction gives a definite purpose. This merits a 4 (clear context, but no exclusions).

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

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

Annotations already indicate a safe read-only operation, and the description adds valuable non-obvious behaviors: default page size of 25, nextLink pagination, calendarView expansion of recurring meetings, and UTC interpretation of naive times with timeZone rendering control. This goes well beyond the structured 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?

Three sentences, each earning its place: the first states output payload, the second states pagination default, the third explains the critical start/end and timeZone behavior. Information is front-loaded and dense without being verbose.

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

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

Given the tool's complexity (7 optional params, no output schema, read-only safe annotations), the description covers return fields, pagination, recurring behavior, defaults, and timezone handling. An agent has enough to invoke it correctly without further research.

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?

Although the input schema covers all 7 parameters with descriptions, the tool description adds crucial cross-parameter semantics: start and end must be used together to trigger calendarView, and timeZone affects interpretation of naive values and rendering. This meaning is not present in the schema and materially improves correct invocation.

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

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

The description uses a specific verb ('Lists events') and details the exact output fields (subject, start, end, location, organizer, attendee count, nextLink), making the tool's purpose unmistakable. It is clearly distinct from siblings like calendar_get_event (single event) and calendar_list_calendars (calendar list).

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

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

The description provides clear, explicit guidance on how to use the start/end parameters to switch between raw event list and calendarView, including the behavioral difference for recurring series. While it does not name alternative tools, the usage context is unambiguous and the parameter-level when/when-not guidance is strong enough for an agent to call it correctly.

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

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

Annotations already flag destructiveHint=true nhận readOnlyHint=false, but the description adds meaningful behavior beyond that: 'Graph returns no content on success,' the attendee-only constraint, response failure for organizer-created events, and the inability to propose a new time. This gives an agent a realistic picture of side effects and limitations.

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

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

Three sentences with no wasted words. The main action is front-loaded, followed by the success return behavior awaited then the critical constraints. Every sentence earns its place.

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

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

For a mutation tool with no output schema, this description covers the essential facts: what the reply does, the success response (empty content), attendee precondition, and unsupported proposal flow. An agent has enough to decide when and how to call the tool without encountering surprises.

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

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

Schema description coverage is 100%, and each parameter (id, comment, response, sendResponse) already has a clear schema description. The tool description adds little parameter-specific meaning beyond restating the response options and the optional comment, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Accepts, declines, or tentatively accepts a meeting invitation...' This clearly distinguishes the tool from siblings like calendar_create_event or calendar_update_event. The additional note that proposing a new time is not supported further sharpens its 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?

The description gives clear context: responding only works when the signed-in user is an attendee, and it explicitly fails for events the user organized. It also names the unsupported 'propose new time' flow. However, it does not explicitly point to alternatives or say 'use calendar_update_event for edits,' so the when-not-to-use guidance is not fully explicit.

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

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

Annotations already indicate idempotentHint=true (safe to retry), readOnlyHint=false and destructiveHint=false (mutation but not destructive). The description adds behavioral context beyond annotations: it explicitly warns about side effects (emails to attendees, impact on series), and states that omitted fields are left alone, which clarifies idempotency and partial update behavior. It doesn't mention auth requirements, but that's likely covered elsewhere. 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 compact: three sentences, front-loaded with the core patch semantics, followed by the most critical traps. Every sentence carries operational weight. It avoids boilerplate and directly addresses the highest-risk aspects of the tool. No 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 complexity (14 params, many with nuanced behavior), the description covers the most critical operational details: partial update semantics, the attendees replacement issue, and notification side effects. It does not cover every parameter (e.g., timeZone interpretation, isOnlineMeeting removal limitation), but the schema descriptions provide that. With annotations covering idempotency, and high schema coverage, the description is sufficiently complete for correct invocation. It could mention recurring series implications more explicitly, but the warning about updating the series master covers it.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by highlighting the 'attendees' replacement trap, which is not fully captured in the schema description (schema says 'replaces the entire attendee list' but description reinforces it with the 'uninvited' consequence). It also adds the context that changing start/end triggers notifications. For a complex tool with 14 params, this extra guidance is valuable beyond the schema.

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

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

The description clearly states that it patches given fields on an event and returns the updated event, with a clear verb ('patches') and resource ('event'). It distinguishes itself from sibling tools like calendar_create_event (creates new) and calendar_delete_event (removes), and from read-only tools like calendar_get_event. The description also emphasizes partial update semantics, which is key for an update 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 explicitly warns about common pitfalls: sending 'attendees' replaces the whole list (so users must send the full list), changing time/attendees sends updates to invitees, and updating a recurring series master affects all occurrences. It doesn't explicitly name alternatives, but given the unrelated sibling set (files, mail, todo), the context is clear. The warnings provide critical when-to-be-careful guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds crucial behavior: displayName is derived from givenName/surname, max 3 emails, and no de-duplication. These are non-obvious and critical for correct invocation, going well beyond the annotation hints.

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

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

Three sentences with zero fluff. The primary action and return value are front-loaded, followed by two essential constraints (displayName construction, email limit, de-duplication warning). Every sentence earns its place.

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

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

For a creation tool with 6 parameters, no output schema, and critical platform-specific behaviors, the description covers all essential context: what it does, what it returns, and pitfalls (de-duplication, displayName, email limits). An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: explains that givenName and surname together form displayName, and that emailAddresses is capped at 3 due to Outlook's slot limitation. This adds semantic relationships not present in the schema.

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

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

States a specific verb (creates), resource (personal contact in signed-in user's default Contacts folder), and the return value (stored contact with new id). It clearly distinguishes from sibling tools like contacts_update or contacts_delete by focusing on creation and explicitly naming the de-duplication caveat.

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 describes when to use the tool (create a contact) and when not to (search first if contact may exist, due to lack of de-duplication). This provides clear guidance for an agent to choose correctly among contact-related 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 annotations (destructiveHint=true, idempotentHint=false), the description adds critical behavior: the contact moves to Deleted Items, recovery is only via Outlook, Graph returns no body, and deleting an already-gone id yields 404. This enriches the agent's understanding of side effects and error handling without contradicting any annotation.

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

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

Three tight sentences that front-load the primary action, then cover side effects, response, and error behavior. No redundant phrasing; every sentence contributes value.

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

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

For a simple one-parameter delete tool, the description covers the outcome, recoverability, response shape, and failure mode. No output schema exists, but the response is described. It is fully sufficient for an agent to call correctly.

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

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

Schema description coverage is 100% and already specifies the id must come from contacts_list or contacts_search and be the opaque Outlook item id. The description adds nothing beyond that, so it does not improve parameter understanding beyond the schema's 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 opens with 'Deletes one personal contact,' a specific verb and resource that clearly differentiates it from the other contact tools (list, get, search, create, update). It leaves no ambiguity about what action the tool performs.

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 context by stating the id must come from contacts_list or contacts_search and clarifying that deletion is permanent within these tools (recoverable only via Outlook). It does not explicitly name alternatives, but it's the sole contact-deletion tool among siblings, so the guidance is adequate though not exhaustive.

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 and idempotentHint, but the description adds valuable behavioral context: personal notes are truncated to 1000 characters, empty properties are omitted, a missing key means the field is not set, and wrong-mailbox/deleted ids fail with 404 ErrorItemNotFound. 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?

Four sentences, each earning its place: return-field list, truncation behavior, omission semantics, and failure mode. The core purpose is front-loaded, and there is no filler or repetition of annotations.

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 one-parameter, read-only getter with no output schema, the description covers the returned fields, important data-shaping behavior, and error semantics. An agent has enough information to invoke the tool and interpret its response 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?

The input schema has 100% description coverage for the single id parameter, including its source and what it is not. The description only restates that the operation is by id and adds no additional parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Returns') and resource ('one personal contact by id'), and enumerates the exact fields returned. This clearly distinguishes it from collection-returning siblings like contacts_list and contacts_search and from mutating siblings like contacts_create or contacts_delete.

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 and parameter schema imply that the agent must already have an opaque contact id from contacts_list or contacts_search, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. The usage context is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the tool's safety profile is covered. The description adds valuable behavior beyond annotations: default page size, the default row projection, nextLink-based paging with skip, and the exclusion of custom contact folders.

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

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

The description is front-loaded with the core purpose and then efficiently covers output shape, pagination, and scope limitations. Every sentence earns its place without unnecessary padding.

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

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

With no output schema, the description still tells the agent what fields each row carries and how to request different properties. Pagination is fully explained, and the custom-folder exclusion prevents misuse, making the tool callable without hidden assumptions.

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

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

Schema description coverage is 100%, and the schema already documents top, skip, filter, select, and orderby in detail. The description restates the default page size, select behavior, and nextLink skip pattern, but adds little parameter-level meaning beyond the custom-folder scope caveat.

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 first sentence names a specific verb and resource: it lists personal contacts from the signed-in user's default Outlook Contacts folder. The final sentence also clarifies what is not included, which helps distinguish it from tools that search across custom 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?

The description explicitly tells the agent to use contacts_search when filtering on emailAddresses is needed, and it flags that custom contact folders are out of scope. This gives clear when-to-use and when-not-to-use guidance relative to 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 establish readOnlyHint, idempotentHint, and non-destructiveness, but the description goes well beyond them. It discloses default pagination (25 per page), relevance ranking, the inability to combine search with $filter/$orderby, and exact matching semantics. This is substantial behavioral context that annotations alone would not convey.

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

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

The description is dense but every clause earns its place: purpose, output shape, defaults, ranking rationale, alternative tool, and limitations. The key differentiators are front-loaded before the more detailed caveats. No filler or repetition.

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

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

For a search tool with three parameters, no output schema, and rich annotations, the description covers the essential behavior needed to invoke it correctly: scope, ranking, pagination defaults, return shape, and matching limitations. The schema fills in the remaining parameter details. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is a 3. The top-level description adds meaningful query semantics beyond the schema by explaining whole-word/prefix matching, ranking behavior, and unsupported conditions. It does not add extra detail about top/skip, but the schema already documents those 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 a specific action ('full-text search') and resource ('default Contacts folder'), and also specifies the output format ('same compact rows as contacts_list'). It differentiates itself from contacts_list by explicitly saying that $filter and $orderby are not available here. An agent can immediately tell this apart from sibling tools.

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

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

The description gives concrete when-to-use guidance: relevance-ranked full-text search, and it explicitly names the alternative for filtered/sorted results ('use contacts_list'). It also states hard limitations up front—no date ranges, mid-term wildcards, or 'not equal' conditions—helping an agent avoid calling this tool for queries it cannot satisfy.

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 goes far beyond the annotations by disclosing patch semantics (omitted fields left alone), the replacement behavior of emailAddresses, and the lack of optimistic concurrency checking with silent overwrites. These are critical behavioral traits that the annotations alone do not convey.

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

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

The description is three sentences, each earning its place: the main purpose, the critical emailAddresses replacement warning, and the concurrency caveat. It is front-loaded and free of redundant phrasing.

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 no output schema, the description adequately notes that it returns the stored result and covers the most important behavioral pitfalls. It does not mention error cases (e.g., contact not found) or provide details about the return structure, but given the schema richness and clear warnings, it is substantially complete.

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

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

Schema coverage is 100% and each parameter has a rich description. The overall description adds collective semantic value: 'Omitted fields are left alone' and 'At least one field besides id is required' are not stated in the schema and provide crucial update semantics beyond the individual property descriptions.

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

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

The description states a specific verb ('Updates') and resource ('one personal contact'), making the tool's purpose unmistakable. It naturally distinguishes itself from sibling tools like contacts_create, contacts_delete, contacts_get, and contacts_list by focusing on partial modification of existing contacts.

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

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

The description gives clear usage context, including the requirement that at least one field besides id be provided, and warns about emailAddresses replacement behavior. It does not explicitly mention when NOT to use this tool versus alternatives, but the update semantics are evident from the description and 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 indicate a mutating, non-idempotent operation. The description adds valuable context by disclosing collision behavior (numeric suffix rename) and that the created item is returned, which goes 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?

Two sentences with no fluff. Purpose is front-loaded, followed by parameter guidance and a key behavioral warning. Every sentence earns its place.

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

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

The description covers essential behaviors: what it creates, parent specification, collision handling, and return of the created item. Given full schema coverage and no output schema, it is sufficiently complete, though return fields could be specified.

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

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

Schema coverage is 100%, so all three parameters are already described. The description repeats mutual exclusivity and root omission but does not add new meaning beyond the schema. Baseline of 3 applies.

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

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

The description clearly states the verb 'Creates' and the resource 'folder in the signed-in user's OneDrive', making the purpose unambiguous. It doesn't explicitly contrast with sibling file tools, but the folder-specific action is distinct enough to differentiate.

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 how to specify the parent (parentItemId or parentPath, omit both for root), which is parameter usage, but it does not provide guidance on when to choose this tool over alternatives like files_upload_text or files_create_link. Usage context is implied rather than explicit.

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

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

Beyond the annotations, the description reveals meaningful behavior: call outcomes, defaults, a 403 failure mode for anonymous links, and the fact that duplicate calls return the existing link rather than creating a second one. This adds substantial practical context that annotations alone do not convey.

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

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

Three sentences, each earning its place: purpose and return value, defaults, then the two important behavioral caveats. The most actionable information is front-loaded, and there is no filler.

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

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

For a three-parameter tool with no output schema, the description is complete: it explains what is returned, the safe default behavior, and the error/retry path. The annotations cover mutation and non-destructiveness, so nothing essential is missing for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by tying scope to a concrete error/retry pattern and by explaining repeated-call behavior for type and scope, which is not present in the schema. It does not add new semantics for itemId, but the schema already defines it clearly.

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

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

The description states a specific verb and resource: it creates a sharing link for a OneDrive file or folder and explicitly lists the returned data (URL, permission type, scope). This distinguishes it clearly from sibling file tools like files_get_item or files_create_folder, and from the broader graph_request fallback.

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

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

The description gives clear operational context: defaults, a policy-related failure mode with a recommended retry scope, and idempotent behavior for repeated calls with the same type and scope. It does not explicitly enumerate when-not-to-use alternatives, but the tool's unique purpose makes that less necessary.

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 mark this as destructive and non-idempotent, and the description adds valuable behavior beyond that: folder deletion removes contents, items go to the recycle bin, and no restore tool exists. There is no contradiction with the annotations.

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

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

Three dense, purposeful sentences: the core action first, then the folder caveat, then the safety and recovery warning. Every sentence earns its place with no redundant wording.

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

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

For a simple one-parameter destructive tool, the description covers what is deleted, the scope of deletion, the recycle-bin behavior, the lack of restore capability, and the recommended pre-check. No critical information is missing.

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

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

The schema already documents itemId at 100% coverage, so the baseline is 3. The description adds extra meaning by advising the agent to confirm the id with files_get_item first, which helps the agent supply a valid parameter value.

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

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

The description clearly states the verb 'Deletes' and the resource 'file or folder from the signed-in user's OneDrive'. It also calls out the folder-recursion consequence, which helps distinguish this tool from other delete tools among the siblings.

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

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

It gives explicit pre-use guidance: confirm the id with files_get_item first and be aware there is no restore tool. This is strong practical context, though it doesn't explicitly list alternatives or conditions 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 already establish readOnly/idempotent/non-destructive, but the description adds a genuinely useful behavioral fact not in the structured data: it requires the Files.Read.All scope and that a user can consent without an administrator. It stops short of describing errors, throttling, or permission-denied 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?

Two sentences, front-loaded with the core capability (any drive, metadata) before the sourcing details. Dense but each clause carries information; minor compression could still be gained in the list of sibling sources.

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

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

No output schema exists, but the description compensates by stating the return matches files_get_item, and it covers scope and auth consent. Complete enough for a two-parameter read tool, with only edge-case/error behavior left undocumented.

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

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

Schema description coverage is 100%, and the schema already documents driveId and itemId with the same remoteDriveId/remoteItemId examples. The description reinforces the multi-drive semantics but adds no format or syntax detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource (reads metadata of one file or folder) and a differentiated scope (ANY drive the user can reach, not just their own OneDrive). It explicitly contrasts itself with the sibling files_get_item by saying it returns the same detail, so an agent can tell the two apart without opening schemas.

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

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

Gives concrete context for when this tool is the right one: resolving remoteDriveId/remoteItemId stubs from files_list_shared and files_list_recent, and driveId/itemId from teams_get_channel_files_folder. It implies files_get_item handles the own-drive case but never states the exclusion or 'when not to use' explicitly.

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

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

Annotations already establish the safety profile (readOnly=true, idempotent=true, destructive=false). The description adds meaningful behavioral context beyond that by disclosing that the pre-authenticated download URL is deliberately not returned and listing the metadata fields that are. It could still say more about error cases or permission expectations, but the read-only annotations lower the bar.

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 written sentences: the first establishes what and which fields, the second covers addressing mode, and the third handles an important caveat plus alternatives. There is no filler or redundant restating of the title.

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

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

For a simple read-only metadata tool with only two optional parameters and no output schema, the description is sufficient: it lists the return fields, explains how to address the item, and clarifies the notable missing field (download URL) with fallback tools. An agent can call this tool correctly without needing 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?

Schema description coverage is 100%, so the parameters are already well documented. The description reinforces the mutual exclusivity of itemId and path, but that constraint is already present in the schema. No new parameter-level meaning is added, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Reads the metadata of one OneDrive file or folder' and enumerates exactly which fields are returned. It also distinguishes itself from content/download tools by noting the download URL is intentionally absent and pointing to files_read_text and files_create_link.

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

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

It states the tool is for reading metadata of a single item, explains the addressing constraint ('by itemId or by path, not both'), and explicitly names alternatives when the pre-authenticated download URL is expected: files_read_text for contents and files_create_link for sharing. This gives an agent clear when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context: non-recursive nature, pagination via nextLink, default page size, and the fact that it returns multiple entries. It also notes that SharePoint-backed drives may ignore some sorts, which is a useful caveat. The only minor gap is lack of detail on error handling or rate limits, but with strong annotations, this is above baseline.

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: the first is information-dense, covering return fields, addressing, and pagination; the second clarifies non-recursion and points to the alternative. It is concise, front-loaded with the primary purpose, and every sentence earns its place without 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 (4 params, no required params, decisive annotations), the description is complete: it explains return fields, pagination, default page size, non-recursion, and alternate addressing. No output schema exists, but the description lists all return fields, making it self-sufficient. There is no missing guidance for an agent to call this correctly.

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

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

Schema description coverage is 100%, so all parameters are fully described in the schema. The description adds context by explicitly mentioning the mutual exclusivity of itemId and path, and the omission for root, which reinforces but does not extend the schema. Since coverage is high, baseline 3 is appropriate; no significant added meaning.

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 it lists direct children of a folder in OneDrive, enumerates the exact fields returned, and distinguishes it from recursive search by naming files_search as the non-recursive alternative. This is a specific verb+resource with sufficient detail to differentiate from siblings.

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

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

The description explicitly states when to use this tool (list direct children) and when not to (use files_search for whole-drive search). It also clarifies how to address the folder (by itemId, by path, or omit for root), which serves as usage guidance. No exclusions are needed beyond that.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavior beyond this: results include count and nextLink, default to 25 items, and may include remote items from other drives or SharePoint with an important caveat about remote IDs not resolving against the user's own drive.

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

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

Three sentences with no filler, front-loading the core action and output, then providing the default limit and the remote-item caveat. Every sentence contributes necessary information for correct invocation.

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 one-parameter read-only listing tool with no output schema, the description is complete: it states what is returned (items, count, nextLink), the sort order, the default count, and a non-obvious remote-item edge case. An agent has enough to call it correctly without further inference.

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

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

Schema coverage is 100% for the single 'top' parameter, so the schema already documents its meaning, default, and bounds. The description adds context like 'most recent first' and 'defaults to 25 items,' but the latter is already in the schema, so the added parameter-specific value is minimal.

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

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

The description uses a specific verb and resource: 'Lists files the signed-in user recently opened or edited.' It clearly distinguishes this from sibling tools like files_search (search-based), files_list_shared (shared items), and files_list_children (folder contents) by focusing on recency and the user's own activity.

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

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

The usage context is implied rather than explicit: the tool is for retrieving recently opened or edited files. However, it does not explicitly state when to prefer this tool over files_list_shared or files_search, nor does it mention any exclusions or alternative conditions.

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

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

Annotations already cover read-only/idempotent safety, so the description adds real value by disclosing the default 25-item limit, the count/nextLink return shape, that entries are stubs pointing into the owner's drive, and the required Files.Read.All scope with non-admin consent. Doesn't mention pagination mechanics beyond nextLink or error behavior, but this is well above the annotation baseline.

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-loads the core purpose, then layers return shape, default, usage routing, and auth scope in a compact multi-sentence block. Dense but each sentence contributes; no filler or restatement of the name.

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

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

For a one-parameter read-only listing tool with no output schema, the description supplies purpose, default/limit behavior, return shape hint (count and nextLink), how to consume the stubs, and required auth scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single parameter 'top' is fully documented, including the caveat that sharedWithMe applies the limit loosely. The description repeats the default but adds no syntax or format detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Lists files and folders other people have shared with the signed-in user') and distinguishes itself from sibling tools by noting that most files_* tools address only the user's own OneDrive. An agent can tell this apart from files_list_children or files_search without opening a schema.

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

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

Clearly frames when to use this tool: to find items shared by others, and points to files_get_drive_item and files_parse_document as consumers of the returned remote ids. No explicit when-not-to-use statement, but the alternative context is strong.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: formula values are saved not evaluated, friendly errors for password/IRM, scanned PDFs, legacy formats, and files over 16 MiB, plus hard caps of 50 PDF pages and 100k spreadsheet rows.

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?

Dense but front-loaded: the core behavior (unit rows + manifest) leads, followed by source selection and then limits/errors. It is a long single block, but nearly every clause carries operational value rather than filler.

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

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

With no output schema, the description fully carries the return contract (unitCount, per-unit truncated flags, returnedRange, reason codes 'complete'/'maxItems', cursor). Combined with source rules, error exclusions, and caps, an agent has everything needed to invoke and continue correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter; the description adds meaning on top, notably the 'exactly one source' rule, that cursor carries source and paging, and the truncation behavior tied to maxCharsPerUnit.

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

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

States a precise verb and resource: extracts text from .docx/.xlsx/.pptx/.pdf as unit ROWS (sections, sheets, slides, pages) plus a manifest. This clearly differentiates it from the sibling files_read_text by specifying multi-format parsing and unit-based output.

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

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

Gives explicit source-selection rules ('exactly one source: shareUrl, driveId+itemId, or messageId+attachmentId') and names where ids come from (files_list_shared, teams_get_channel_files_folder). However, it never explicitly tells the agent when to prefer this over siblings like files_read_text or files_get_attachment_content.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real behavioral detail beyond them: metadata is read before the content, binary formats are rejected with an explanation rather than failing opaquely, and content is truncated with a marker. That is exactly the value-add expected when annotations carry the safety signal.

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

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

Three sentences, each load-bearing: what it returns, the refusal rule, and the alternative for unsupported formats. Return behavior is front-loaded and the routing hint closes the paragraph with no filler.

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

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

With no output schema, the description carries the return contract itself and does so ('as a string, truncated to maxChars'), plus the failure mode for binary input and the downstream alternative. An agent has everything needed to call it correctly and to recover from a refusal.

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 both itemId and maxChars are already documented, including the 20000 default and the truncation marker. The description restates the maxChars default but adds no new syntax, format, or edge-case meaning, so the baseline 3 applies.

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

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

Names a specific verb and resource ('Returns the contents of a text-like OneDrive file') and enumerates the exact formats covered (plain text, Markdown, CSV, JSON, XML, source code, config). It also carves out the boundary against files_parse_document, so an agent can distinguish it from siblings without opening any schema.

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

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

Explicitly states when-not to use it (binary formats — PDFs, images, Office documents, archives, media — are refused) and names the correct alternative for those cases (files_parse_document for .docx/.xlsx/.pptx/.pdf). Both the routing condition and the destination tool are given, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful non-schema context: the required Files.Read.All scope and that a user can consent without an administrator. It does not describe error or failure behavior (e.g. invalid/expired links), which keeps it short of a 5.

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

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

Two tightly written sentences that are front-loaded with the outcome and then the routing guidance; every clause carries information. The em-dash aside is slightly dense but does not waste words.

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

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

There is no output schema, so the description compensates by naming the returned fields, and it covers auth scope, the link sources, and the alternative tool. An agent has everything required to call it correctly.

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

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

Schema description coverage is 100% for the single shareUrl parameter, and the schema already explains it is a OneDrive/SharePoint link resolvable to a drive address. The description's example sources (Teams contentUrl, mail reference attachment) mirror the schema text rather than adding new semantics, so baseline 3 applies.

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

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

States a specific verb ('resolves') and resource ('OneDrive/SharePoint sharing link') and explicitly enumerates what it returns (driveId, itemId, name, kind, size, mime type, webUrl). It is clearly distinguishable from the sibling files_parse_document, which it names.

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

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

Explicitly states when to use it (first step from a Teams contentUrl or mail sourceUrl sharing link to the file) and offers the alternative path ('skip it and pass the link straight to files_parse_document as shareUrl'). Both the use case and the alternative are named.

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 and idempotentHint, and the description adds behavioral detail beyond that: the default page size, the compact return fields plus count and nextLink, the index-lag behavior for recently uploaded files, and the lack of filtering. This gives the agent a realistic model of what the call returns and what it may miss.

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, each earning its place: purpose and return shape, page size, explicit limitations and routing to an alternative, and a material freshness caveat. The most important scoping information is front-loaded before the caveats, and there is no filler or redundancy beyond the intentional schema reinforcement.

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?

Even without an output schema or rich sibling descriptions, the description tells the agent what to expect by referencing the compact fields of files_list_children plus count and nextLink. It covers pagination default, filtering limitations, when to use an alternative, and the indexing lag that affects result completeness. Nothing needed to call and interpret this tool correctly is missing.

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

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

Schema description coverage is 100% and both parameters are already documented with meaningful descriptions in the schema. The description reinforces the 'accepts only a search term' constraint and the page-size default, but it does not add substantial new meaning beyond the schema. Baseline 3 is appropriate given the schema already carries the full 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?

States a specific action ('Searches the whole of the signed-in user's OneDrive') and a specific matching behavior ('file names and indexed file contents'). It also differentiates from siblings by naming the return shape relative to files_list_children and by noting the endpoint accepts only a search term. This lets an agent distinguish it from files_list_children and search_query without opening the schema.

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

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

Explicitly states what the endpoint does not support ('no date range, no file-type filter and no sort order') and routes the agent to an alternative ('list a folder with files_list_children instead'). The indexing-lag caveat also tells the agent when results may be incomplete, which is directly useful for choosing this tool over a direct list or recent-files 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?

Despite annotations not marking destructiveHint, the description clearly discloses that an existing file is REPLACED, not merged or appended, and warns about size limits and binary content. This goes well beyond the minimal annotation info and fully informs the agent of 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?

Three sentences with no fluff. The primary action is stated first, followed by critical behavioral warnings and limits. Information is front-loaded and every sentence adds value.

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

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

For a write operation with two parameters, no output schema, and minimal annotations, the description covers the core behavior, side effects, limits, and alternatives. An agent has all necessary information to call it correctly without ambiguity.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds a note about automatic folder creation and replacement semantics, but these are also echoed in the schema descriptions. The description doesn't significantly enhance parameter meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description states a specific verb ('Writes') and resource ('a text file to the given path in the signed-in user's OneDrive'), and distinguishes it from siblings like files_read_text and files_create_folder. It is immediately clear what the tool does and how it differs from related file operations.

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 explicitly explains when to use it (text files up to 4 MB) and when not to (larger or binary uploads need a resumable session not exposed). It also advises reading the file first with files_read_text before editing, giving clear usage and exclusion criteria.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this by adding 'Reads only the signed-in account from Graph,' which tells the agent the call has a narrow read footprint rather than enumerating all permissions or making changes. This adds behavioral context beyond the annotations without contradicting them.

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

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

The description is three sentences with no filler. It front-loads the core purpose ('Reports how this server is configured'), then lists the concrete output categories, gives a practical usage trigger, and closes with the read scope. Every sentence earns its place.

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

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

For a zero-argument, read-only diagnostic tool, the description is complete. It tells the agent what the tool reveals, when to call it, and what side effects it has. Although there is no output schema, the description sufficiently characterizes the return content for an agent to decide whether this tool fits the situation.

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

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

The tool has zero parameters, and the schema confirms an empty properties object with 100% coverage. With no parameters to describe, the baseline of 4 applies; the description appropriately avoids inventing parameter-related noise.

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 'Reports how this server is configured' and enumerates exactly what it covers: enabled tool groups, delegated Graph scopes, admin consent requirements, write-tool suppression, and the signed-in account. This clearly distinguishes it from the sibling tools, which perform actions on mail, files, calendar, and contacts rather than inspecting server permission configuration.

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

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

The description gives an explicit trigger: 'Call it when a request fails with 403 or "insufficient privileges" to see whether the needed area is switched on at all.' This is a clear context for use. It does not explicitly name alternative tools or say when not to use it, but the diagnostic purpose is distinct from the action-oriented sibling tools, so no exclusion is necessary.

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 reconciles the safety profile rather than contradicting it: it discloses that GET is unconditional while write methods are gated behind --allow-generic-write, consistent with readOnlyHint/destructiveHint being defaults. It also adds behavior no structured field carries — absolute URLs are rejected, maxPages follows @odata.nextLink, and the token scope is guessed from `path` with a fallback to the union of enabled groups.

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 purpose then constraints, and nearly every sentence carries a distinct fact (alternatives, host/path rule, method gating, paging, scope resolution). The prose is dense with semicolon-joined clauses, which is slightly wall-of-text, but appropriate for a 7-parameter generic 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?

No output schema exists, and the description compensates by characterizing the return value (raw JSON, often far more text than the purpose-built tools). For a tool with nested objects, enums, and configuration-dependent write/auth behavior, all decision-relevant facts — path form, write gating, beta gating, paging limit, scope override — are present.

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 earns one extra point by adding operational meaning on top of field docs — which parameters matter ($select/$top in `query`, `maxPages` for paging) and that `scopes` exists specifically to override the path-based guess. It stops short of adding syntax detail the schema doesn't already give.

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

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

States a precise verb+resource ("sends an arbitrary request to Microsoft Graph and returns the raw JSON response") and immediately distinguishes itself from the large set of purpose-built siblings ("the dedicated tools project and trim their results, while this one returns everything Graph sends"). An agent can tell this is the generic escape hatch without opening any schema.

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

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

Explicitly scopes when to use it: "Use this only when no purpose-built tool covers the endpoint," which names the alternative category (47 purpose-built siblings) and the condition that selects this tool. It also states the write-method prerequisite (--allow-generic-write / --read-only) and gives efficiency advice ($select, $top) — real operational guidance, not just 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 establish read-only/idempotent/non-destructive behavior. The description adds meaningful behavioral detail beyond that: it fetches only one item via $top=1, reports the shape of a real item, omits null properties, and returns no properties for an empty collection. This helps set expectations about incomplete results.

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 four sentences and front-loads the core function in the first sentence. The caveats about null properties and empty collections are necessary and earn their place. The final 'Read-only' is redundant with annotations but not harmful.

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

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

For a simple two-parameter probe tool with no output schema, the description covers what the tool returns, how it behaves with real data, and when to use it relative to graph_request. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description mentions the Graph path concept and $top=1 but does not add significant parameter-level meaning beyond what the input schema provides. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource: it fetches one item from a Graph path and reports property names, JSON types, and @odata.context. It also explicitly positions itself against graph_request by saying it is meant to be used before that tool to learn what $select and $filter can reference.

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

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

The description gives clear context: 'Use it before graph_request to learn what $select and $filter can reference.' This names the alternative tool and the condition for using graph_schema. It does not explicitly state when not to use it, but the intended workflow is clear.

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

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

Annotations already indicate this is a mutating, non-idempotent, non-destructive operation. The description adds valuable context beyond annotations: nothing is transmitted, the draft is unsent, and the tool returns id and webLink. This meaningfully clarifies the tool's 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?

Three sentences with no filler. The core behavior is front-loaded, and each sentence adds distinct value: what it creates, what it cannot do, and how recipients behave.

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 create-draft tool with a fully documented schema, the description covers the essential behavioral context: return values, non-sending behavior, and the fallback path. It does not explain error conditions or permissions, but those are not necessary for correct invocation here.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds the useful note that recipients are optional, but does not need to explain each parameter further. Baseline 3 is appropriate.

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

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

States a specific verb and resource: creates an unsent draft in the Drafts folder. It explicitly differentiates itself from mail_send by noting it cannot send, so an agent can distinguish it from the sibling tools without opening schemas.

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

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

Provides explicit guidance on when to use this tool versus mail_send, and notes that there is no companion tool to send an existing draft. It also clarifies that recipients are optional, which is directly useful for invocation decisions.

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, the description discloses critical behavioral details: the operation is a soft delete, the message is recoverable in Outlook, no server-side undo exists, and deleting from Deleted Items is permanent. This gives the agent the full side-effect picture needed to decide safely.

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

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

Three short sentences, each carrying essential information: the action, the soft-delete behavior and recoverability, the lack of server-side undo with a confirmation instruction, and the permanent-deletion edge case. No filler or repetition; the most important warning is front-loaded.

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

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

For a destructive single-id operation with one documented parameter and no output schema, the description covers the key contextual needs: what happens, what the user can do to recover, what the server cannot do, and when deletion becomes permanent. The agent has enough information to invoke the tool responsibly.

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

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

The schema already documents the single required id parameter with full coverage and a clear description ('Id of the message to delete'). The tool description adds no additional parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description opens with 'Deletes a message,' a specific verb and resource that clearly identifies the operation. It further clarifies the exact behavior (soft delete moving the message to Deleted Items), which distinguishes this from sibling tools like mail_move_message or mail_mark_read. The purpose is unambiguous and immediately actionable.

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

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

The description provides clear practical guidance: confirm with the user first, since the server has no undo tool, and warns that deleting a message already in Deleted Items is permanent. This establishes when caution is required, though it does not explicitly compare to alternatives like mail_move_message or state 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 already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: quote-fold markers with guaranteed in-response indices, meta.fold and meta.budget, the three reason values including the no-cursor rationale, bodyRendering:'stripped-html' with linksLost, plus the explicit notes that nothing is marked read and attachments are never included.

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 purpose and alternative in the first sentence, then dense return-value detail. Length is justified by the absence of an output schema, though it is on the verbose side and could tighten slightly.

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

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

With no output schema, the description carries the full return-value burden and does so: it documents result ordering and the `n` citation index, meta.fold/meta.budget, all reason values, and the stripped-html caveat. Nothing an agent needs to call and interpret the result correctly is missing.

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

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

Schema description coverage is 100% and the parameter docs are already rich, so baseline is 3. The description reinforces fromMessageId (any id, server finds the rest) and ids (also works across conversations), but this largely duplicates what the schema already states, adding little net-new meaning.

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

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

States a specific verb and resource ('Reads a whole reply chain in one call') plus the distinguishing fold behavior. It explicitly names the sibling it replaces ('Use it instead of looping mail_get_message'), so an agent can separate it from mail_get_message without opening either schema.

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

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

Gives an explicit when-to-use condition ('whenever you want two or more messages of one conversation') with concrete scenarios, names the alternative (mail_get_message loop), and explains the fallback path (narrow with mail_search_messages and pass ids) when the thread is too long.

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 mark destructive and non-idempotent, and the description adds meaningful behavioral detail: immediate sending, no undo, attachments included, comment placement, and the separate Mail.Send permission requirement. 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?

Three tight sentences front-load the core behavior and warning, then add only necessary context about comment placement and permissions. Every clause contributes actionable information with no filler.

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

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

For a 3-parameter tool with no output schema, the description covers what the action does, side effects, safety guidance, and required permission. An agent has enough to decide whether to call it and what to tell the user before invoking.

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

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

Schema description coverage is 100%, so the schema already documents id, to, and comment. The description adds only that attachments are included and that no undo exists, which is behavioral context rather than new parameter semantics; the comment placement detail essentially repeats the schema 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?

States a specific verb, resource, and mode ('Forwards an existing message immediately, attachments included') and explicitly distinguishes itself from draft creation. An agent can reliably tell this apart from mail_send, mail_create_draft, and mail_reply.

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

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

Gives clear context: the tool acts immediately, includes attachments, and is not a draft; it also tells the agent to confirm recipients with the user first because there is no undo. It does not explicitly name alternative tools or state 'use X instead', but the actionable guidance is strong.

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?

Goes well past the readOnly/idempotent annotations by disclosing the 1 MB refusal threshold, the text-vs-base64 return decision, the refusal hand-off to files_parse_document, and the sourceUrl behavior for link attachments. These are exactly the runtime traits an agent cannot infer from the schema.

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

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

Four tight sentences, each carrying distinct information, with the core definition front-loaded. The prerequisite ('Check kind... first') would be better placed at the top than at the end, but there is no filler.

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

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

There is no output schema, so the description must carry the return contract — and it does, enumerating the three possible outcomes (text, base64, sourceUrl) plus the refusal case. With 100% param coverage and full annotations, nothing material is missing.

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

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

Schema coverage is 100%, so id, attachmentId, and maxChars (including default, bounds and truncation marker) are already documented in the schema. The description adds no parameter detail, which is appropriate here since the schema fully carries that burden — baseline 3 would understate a case where the schema is complete and the description uses its words for return-shape semantics instead.

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

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

Specific verb and resource ('Returns the content of one message attachment'), scoped to a single attachment rather than a message or a search. It clearly occupies distinct ground from mail_list_attachments and files_read_text, which it routes to by name.

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

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

Gives an explicit prerequisite ('Check kind on mail_list_attachments first') and names alternatives with their selecting conditions: files_parse_document for files over 1 MB, and files_resolve_share for reference attachments. The agent knows both when to call this tool and where to go when it declines.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds substantial context beyond that: reading does not mark the message read, the body is capped at 8000 chars, attachment contents are never returned, and bodyRendering/linksLost explain provenance and lossy HTML stripping. This is rich disclosure that annotations alone could not convey.

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

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

Front-loaded with the return shape, then constraints, then routing — a sensible order. It is long (~200 words) for a single-message getter, but nearly every sentence carries actionable information (caps, non-mutating behavior, bodyRendering semantics); only the bodyRendering detail verges on over-explaining.

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

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

With no output schema, the description carries the return-value burden and does so fully: it enumerates the fields returned and explains bodyRendering and linksLost. Combined with the cap, format, and non-marking behavior, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds decision context the schema does not: raise maxBodyChars for a long thread, and use format:"preview" to skip the body when only identifying a message. It stops short of explaining foldLinks, which is left entirely to the schema.

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

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

States a specific verb and resource ('Returns one message with its body plus sender, recipients, timestamps, importance, conversationId and webLink') and explicitly demarcates itself from siblings: 'Use this tool for a single message, and mail_fetch_thread for two or more of one conversation.' An agent can distinguish it from mail_list_messages, mail_fetch_thread, and mail_list_attachments without opening any schema.

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

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

Gives explicit when/when-not and named alternatives: use mail_list_attachments for attachment contents, mail_mark_read for marking read, mail_fetch_thread for two or more messages of one conversation, and format:"preview" when you only need to identify the message. The anti-pattern (looping over a reply chain) is called out with a concrete cost measurement.

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 annotations (readOnly, idempotent, non-destructive), the description discloses that file contents are never returned and explains why (output budget), plus notes the default limit of 20 per call. This adds valuable behavioral context that the annotations do not cover, with no contradictions.

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

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

The description is well-structured, front-loading the main purpose and fields, then adding the important caveats about file contents and inline images. It is slightly verbose with the output budget explanation, but every sentence earns its place by conveying essential behavior.

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

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

For a list tool with no output schema, the description fully explains the return metadata, pagination default, and a necessary prerequisite. It is complete enough for an agent to call the tool 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?

The schema already describes both parameters (id and top) with full coverage (100%). The description reinforces the default of 20 per call but does not add new semantic meaning beyond the schema. Baseline of 3 is appropriate when the schema carries the 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 tool's action ('Lists attachment metadata for one message') and enumerates the specific fields returned (id, name, contentType, size, inline flag, kind). It is unambiguous and distinguishes itself from other mail tools by scoping to a single message's 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 a clear usage guideline: 'Check hasAttachments on the message first' and warns that inline images count as attachments, which is a practical caveat. It doesn't explicitly mention alternatives or when not to use it, but the prerequisite and the clarification about inline images offer sufficient guidance for typical use.

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 readOnly/idempotent annotations, the description discloses pagination behavior (50 per call by default), the nesting limitation (only one level with includeChildren), and the requirement for a second call otherwise. It also reveals the output fields (ids, counts) and cross-tool contract (folderId reuse), giving an agent a clear picture of runtime behavior without needing to inspect schemas.

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

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

Three sentences, each carrying distinct information: what is returned and default page size, how to expand nesting, and how to use the result with a sibling tool. The most critical facts are front-loaded, and there is no filler or redundancy.

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

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

Given the lack of an output schema, the description names the fields returned (ids, unread counts, total counts), states the default pagination, explains the nesting behavior, and points to the dependent sibling – everything an agent needs to decide whether to call it and to interpret the result. The only minor omission is explicit error/edge-case handling, but that is not essential for a simple list tool with strong input schema coverage.

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 already provides high-quality descriptions for both parameters (top default/range, includeChildren behavior), and the description's parameter mentions largely mirror that. The description adds minor value by reinforcing the 50-default and the second-call nesting nuance, but it does not meaningfully extend parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (lists), the resource (top-level Outlook mail folders), and the specific fields returned (ids, unread counts, total counts). It also distinguishes this tool from mail_list_messages by explaining how folder IDs feed into that sibling, avoiding ambiguity about which tool handles folders vs messages.

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

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

The description gives explicit usage context: it clarifies that only top-level folders are returned by default, that includeChildren adds one subfolder level, and that a nested folder requires a second call. It also directly names the sibling tool (mail_list_messages) and explains when to use it with well-known folder names, providing a clear when-to-use and when-not-to-use 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description then adds genuine behavioral context the annotations cannot: what the projection contains, that bodies are never returned (only Graph's 255-char preview), the cost rationale for omitting webLink, and the Exchange restriction-complexity error with a remediation. Slightly verbose rather than incomplete.

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

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

Front-loaded with the operation, ordering, and sizing before covering edge cases, and every sentence carries information. It loses a point for repetition between the description and the includeWebLink parameter description, which restate the same webLink-cost rationale.

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

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

No output schema exists, and the description compensates by enumerating the returned projection fields and the paging total. For an 8-parameter read tool with annotations covering safety, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: it explains why includeWebLink is off by default (payload cost), why `select` must not request body, and how `orderby` interacts with `filter` in Exchange. It does not restate the filter syntax, leaving that to the schema.

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

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

States a specific verb and resource ('Lists Outlook messages'), plus the ordering, default page size, ceiling, and the exact default projection it returns. An agent immediately knows what it gets back and how this differs from a body-fetching tool like mail_get_message.

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

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

Gives explicit routing rules: use `id` for further mail tool calls, pass includeWebLink only when a human needs a clickable link, use mail_get_message for bodies, and page with `skip`. It even covers the failure mode where Exchange rejects complex filter/orderby combinations and tells the agent what to change.

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=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: the default is read, isRead:false flips it back, and reading via mail_get_message has no effect on the flag, which helps the agent understand 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?

Two sentences with no filler. The core action is front-loaded, the optional parameter is explained clearly, and the relationship to mail_get_message is stated in one efficient clause.

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

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

For a simple two-parameter mutation with annotations covering safety and idempotency, the description provides everything needed to invoke it correctly. No output schema is present, so explaining return values is not required.

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

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

Schema coverage is 100%, so the schema already documents both parameters and the default for isRead. The description restates the default behavior but adds little beyond the schema, making a baseline 3 appropriate.

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

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

The description uses a specific verb and resource: 'Sets the read flag on one message.' It clearly distinguishes the tool from mail_get_message, mail_list_messages, and mail_delete_message by focusing on the read-flag mutation.

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 the default behavior and how to invert it with isRead:false. It also gives useful context by noting that mail_get_message does not alter the flag, implying this tool is the way to change read state, though it does not explicitly list exclusions or 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 only indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds critical behavioral disclosure not covered by annotations: the move reassigns a new id, invalidating the old one and requiring the returned id for follow-ups. It also clarifies the soft-delete semantics of the deleteditems destination. This is valuable, non-obvious behavior that an agent must know.

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 of high information density. It front-loads the core action, then the most critical behavioral caveat (new id), then the parameter-specific guidance. Every sentence adds value, and there is no redundant fluff or restating of the tool's name or title.

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

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

Given the tool's simplicity (2 simple params, no output schema, no nested objects), the description covers all essential contexts: the action, the id reassignment side effect, the referral to mail_list_folders, and the soft-delete use case. An agent has everything needed to invoke it correctly and interpret the result. No critical information is missing.

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

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

Schema coverage is 100%, so both id and destinationId are documented. The description adds meaning for destinationId by referencing mail_list_folders and the soft-delete nuance, which helps an agent choose the right value. For id, it explains the consequence (new id) but that's more about output than the parameter itself. It supplements the schema meaningfully without repeating it, justifying above-baseline scoring.

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 specific verb+resource: 'Moves a message to another mail folder.' It clearly distinguishes this from sibling tools like mail_delete_message (a delete, not a move) and mail_mark_read (a state change). The unique consequence of the move—the message receiving a NEW id—is stated up front, further differentiating it.

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

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

The description gives clear context on when to use this tool: it references mail_list_folders for obtaining destinationId and explicitly explains that 'moving to deleteditems is how you soft-delete without mail_delete_message.' This provides a usage nuance relative to the delete tool, though it doesn't explicitly enumerate all alternative tools or exclusions. Overall, it offers solid guidance beyond the schema.

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 destructiveHint=true, and the description adds significant context: immediate send, no undo, and the Mail.Send permission requirement. It also explains how the comment is placed above the quoted original and that Graph builds subject and recipients. This goes beyond the annotations and covers key behavioral traits, though it doesn't mention potential failures or idempotency nuances (already covered by idempotentHint=false).

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

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

The description is three sentences with no filler. The most critical caveat (immediate send, no undo, confirm first) is front-loaded, followed by formatting details and permission requirements. Every sentence earns its place and the structure is logical and efficient.

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

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

For a simple 3-parameter tool with no output schema, the description covers the essential aspects: behavior, permission, formatting, and recipient semantics. It lacks explicit mention of return values or error handling, but these are not critical for a basic reply action. The description is sufficiently complete for an agent to call the 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 coverage is 100%, so baseline is 3. The description adds value by explaining that the comment is placed above the quoted original as plain text, and that replyAll includes every original recipient. This clarifies the semantics of comment and replyAll beyond their schema descriptions. The id parameter is self-explanatory and needs no extra 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 clearly states the tool sends a reply to an existing message immediately, and explicitly contrasts with creating a draft. It names the specific resource (message) and the action (reply), making it distinct from siblings like mail_create_draft and mail_send. The verb 'sends' is specific and unambiguous.

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

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

The description provides clear usage guidance by stating it sends immediately, has no undo, and requires confirmation with the user first. It implies when to use this tool (when an immediate send is desired) and contrasts with draft creation. However, it does not explicitly name alternative sibling tools (e.g., mail_create_draft) as the recommended path for draft scenarios, leaving some inference to the agent.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description goes well beyond them: $search results are not in date order, $filter mode silently degrades `query` to a subject substring and stops searching the body, and the response reports which mode ran. Those are non-obvious behavioral traits an agent would otherwise get wrong.

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 purpose and pagination, then the mode rules, then the practical fallback for body-text-within-a-date-range. Every sentence carries information, though the two-mode section is dense enough that bullets would have made the $search vs $filter contrast easier to scan.

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

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

For an 8-param, no-output-schema tool the description covers the return projection, the page size, the mode reporting, and the key workaround, which is most of what an agent needs. It leaves one gap: whether `to`, `from`, and `hasAttachments` are honored in $search mode or only in $filter mode is never stated.

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 per-parameter text already documents syntax and bounds (baseline 3). The description adds cross-parameter semantics the schema cannot express: that supplying `after`/`before` changes the meaning of `query` entirely, and that the output projection/pagination defaults match the list tool.

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

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

States a specific verb+resource (finds mail messages by text) and immediately anchors it to the sibling tool by name ("the same compact projection as mail_list_messages"), so an agent can place it in the family without opening a schema. The two-mode explanation further pins down exactly which search capability this tool exposes.

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 which mode runs under which condition (no date range -> $search; after/before -> $filter) and warns what each mode can and cannot match, which is exactly the guidance an agent needs to pick arguments. It stops short of an explicit when-to-use/when-not versus mail_list_messages or mail_fetch_thread; the alternative is only implied by comparison.

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 annotations (non-read-only, non-idempotent, destructive), the description discloses critical behavior: no undo or confirmation step, no returned message id, a copy in Sent Items unless saveToSentItems is false, and a specific permission requirement. This goes well beyond what the annotations alone convey and gives the agent a realistic model of the operation's consequences.

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

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

The description is four sentences, front-loads the core behavior first, and then adds the most decision-relevant caveats (no undo, no id, Sent Items behavior, permission). Every sentence earns its place; there is no filler or repetition of schema content.

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 send-message tool with no output schema, the description covers the operational essentials: side effects, failure-relevant behavior, permission requirements, and an explicit sibling alternative. The input schema handles parameter details, and the annotations handle the low-level safety profile, so nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the input schema fully documents every parameter. The description adds only modest semantic color, such as the saveToSentItems behavior and the overall emphasis on confirming recipients, but it does not materially extend the schema's parameter explanations. Baseline 3 is appropriate.

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

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

The description states a specific action and resource: 'Sends a message immediately from the signed-in mailbox.' It also distinguishes itself from the sibling mail_create_draft by noting that a send returns no message id and that creating a draft is the alternative. This makes the tool's purpose unambiguous and clearly 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 explicitly tells the agent when to use this tool and when not to: confirm recipients and text because there is no undo, and use mail_create_draft when a message id is needed. It also warns about the separate Mail.Send permission requirement, giving practical usage context beyond a simple 'send a message' statement.

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 mark the tool read-only and idempotent, and the description adds substantial behavior beyond that: reply bodies are stripped to plain text and truncated to replyBodyChars, scheduled start/end times are only meaningful when status is 'scheduled,' and missing mailboxes surface as a specific 404. This is exactly the contextual detail an agent needs.

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, each with a distinct job: scope, reply-body behavior, schedule semantics, and error condition. The most decision-relevant information is front-loaded in the first sentence, with no filler.

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

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

Even without an output schema, the description covers what is returned, the only parameter's effect, edge-case semantics for scheduled replies, and the failure mode. Nothing an agent needs to call and interpret this tool correctly is omitted.

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

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

Schema coverage is 100%, so replyBodyChars is already fully documented in the schema, including the 0-omits-bodies behavior. The description adds that bodies are 'HTML in Graph' and are truncated, but this largely restates the schema's semantics rather than providing new meaning.

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 specific verb-plus-resource phrase, 'Returns the signed-in user's Outlook mailbox configuration,' and enumerates the exact fields returned. This makes the tool distinguishable from sibling tools like me_get_profile or mail_get_message without inspecting the schema.

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

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

It clearly establishes when the tool applies: signed-in user's mailbox settings. It also flags a boundary case with 'Accounts with no Exchange Online mailbox fail with 404 MailboxNotEnabledForRESTAPI,' but it does not explicitly name sibling alternatives or say 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?

Beyond the readOnly/idempotent annotations, the description discloses important behavioral nuances: null/empty properties are omitted, 'mail' is null for accounts without Exchange mailboxes, personal accounts return empty work fields, and userPrincipalName is always present. This adds meaningful runtime expectations the schema cannot convey.

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

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

The description is compact and every sentence earns its place: default set, how to override, omission semantics, and field-specific edge cases. It is front-loaded with the core purpose and avoids repetition 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?

With only one optional parameter, no output schema, and strong annotations, the description fully covers what an agent needs to call it correctly: default projection, selection behavior, and interpretation of absent keys. No critical operational detail is missing.

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

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

Schema coverage is 100% and the schema already thoroughly describes the select parameter, its format, examples, validation, and default behavior. The description's 'Pass select to ask for different properties instead' is helpful but does not substantially exceed what the schema already documents.

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 specific verb and resource: 'Returns the signed-in user's own Entra ID profile from /me'. It clearly scopes the operation to the caller's own profile intest and enumerates the default fields, making it easy to distinguish from sibling tools like me_get_mailbox_settings.

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

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

The description gives clear context: this is the tool for the signed-in user's own profile. It does not explicitly name alternatives, but the '/me' scoping and default property list are enough to signal when it is appropriate. No exclusion guidance is provided, so slightly short of a 5.

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

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

Adds substantial behavior beyond the readOnly/idempotent/destructive annotations: per-split failure isolation (a chatMessage 403 while every other split still returns), the exact permission each index needs, that ChannelMessage.Read.All requires tenant admin consent, that results are ranked not date-sorted, indexing lag, and that chatMessage ignores `fields`. The read-only-despite-POST note is consistent with readOnlyHint=true, not a contradiction.

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 purpose and return format, then layers caveats, all in one dense paragraph with little redundancy. It is long and leans into implementation detail (observed 400 on message+driveItem), but nearly every sentence carries actionable content, so the size is defensible.

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

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

With no output schema, the description carries the full burden and does so: it enumerates hit fields, explains merging/ranking semantics, documents the permission matrix, and warns about partial failures and index staleness. An agent can call this correctly without opening anything else.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning the schema does not: `size` is per entity-type group rather than total, `from` is the paging mechanism, and `fields` is ignored for chatMessage (echoed but usefully framed). These clarifications go beyond the field-level 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?

Opens with a specific verb+resource ('Runs a relevance-ranked Microsoft Search query across Microsoft 365') and immediately names the return shape (rank, summary, id/name/subject, web URL, last-modified). It also tells the agent the default scope (['message','driveItem']), which distinguishes it from the single-source siblings like mail_search_messages and files_search.

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

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

Gives clear operational context: paging via `from`, default group size, and the permission conditionals that gate the chatMessage split. It does not explicitly name alternatives (e.g. use files_search for files only) or state when not to use this broad cross-entity search, so the routing guidance is implied rather than spelled out.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds real behavioral context the annotations don't: it reads a cached account, probes whether the stored session still mints tokens, and performs a live GET /me call.

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

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

Three tight sentences: identity, return contents, then action guidance, with the most important information front-loaded. No wasted words.

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

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

With no output schema, the description correctly carries the burden of describing the return payload and does so concretely. The only gap is that it doesn't clarify its relationship to the sibling login-status/login tools.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline of 4 applies for a parameterless tool.

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

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

States a specific verb and resource ('unified session and consent probe') and enumerates what it returns (cached account, token minting, live /me reachability). It does not explicitly distinguish itself from the sibling auth_login_status/auth_begin_login tools, so an agent must infer the boundary.

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?

'Call once first' gives clear sequencing guidance, and 'on consent errors sign in again with just the missing scopes' gives an explicit remediation path. It still doesn't name the alternative login sibling by name, leaving the routing decision partially 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?

The description goes beyond the annotations by clarifying that the operation patches status, that the updated task with completedDateTime stamps is returned, and that recurring tasks are rolled forward rather than closed. This adds meaningful behavioral context beyond readOnlyHint/idempotentHint/destructiveHint.

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 with no filler. The primary action and return value are front-loaded, and the second sentence adds a valuable edge case about recurring tasks without bloat.

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 low-complexity mutation with two simple parametersley and no output schema, the description covers the action, the return value, and the notable recurring-task behavior. Nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 100%, and both parameters are simple string IDs with clear descriptions. The description does not add parameter-specific details, but the schema already documents the parameters adequately, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Marks'), a clear resource ('a To Do task'), and an explicit outcome ('completed by patching its status to completed'). It also distinguishes this completion action from sibling tools like todo_update_task and todo_delete_task by narrowing the operation to marking complete, not generic updating.

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 intended use is implied: use this tool when you want to complete a To Do task. However, the description does not explicitly state when not to use it or mention alternatives such as todo_update_task for broader status changes, leaving some routing to inference.

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

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

Annotations already indicate readOnly=false and idempotent=false, and the description adds the important behavioral detail that display names are not unique. It also clarifies the return values, which are not in the schema or annotations. No contradiction exists.

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

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

Two concise sentences with no filler. The core action is front-loaded, and the important uniqueness caveat is included without redundancy.

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

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

For a simple one-parameter creation tool with no output schema, the description is complete: it states what is created, what is returned, and the key behavioral caveat about duplicate names. Nothing essential is missing.

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

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

The schema has 100% coverage for the single displayName parameter, including a helpful description. The tool description adds little beyond the schema, so the baseline score of 3 applies.

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

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 To Do list and returns its id and display name, using a specific verb and resource. It is easily distinguished from sibling tools like todo_list_lists and todo_create_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?

The description gives explicit guidance to check todo_list_lists first when uniqueness is expected, which is a useful pre-condition. It does not fully enumerate when to use this tool versus alternatives, but the context is clear for a create operation.

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 this as a write operation (readOnlyHint=false) and non-idempotent. The description adds value by disclosing specifics: it returns the created task, normalizes date-only due dates to midnight, and turns on reminder when reminderDateTime is supplied because Graph defaults isReminderOn to false. These behaviors are not apparent from the schema or annotations alone.

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

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

The description is concisely structured, leading with the primary action and return value, then adding essential details about required fields and date handling. Each sentence contributes value without 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 complexity (7 params, date-time nuances, no output schema), the description covers the critical edge cases (timezone handling, all-day dates, reminder enabling) and clearly states the return of the created task. It is sufficient for an agent to invoke correctly, though it omits potential error conditions and auth details, which are not always required.

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 covers all parameters with descriptions, so baseline is 3. The description adds nuance: explains that due/reminder values are converted to Graph dateTimeTimeZone using the timeZone argument, and clarifies the midnight behavior for all-day dates. This goes beyond the schema's notes, enhancing the agent's 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 states a specific verb ('Creates'), a resource ('task in a To Do list'), and a return value ('returns the created task'). It clearly distinguishes from sibling tools like todo_update_task and todo_delete_task by naming the create action. No 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?

The description gives clear guidance on required fields ('Only title is required') and explains the handling of due and reminder dates, which is essential for correct usage. However, it does not explicitly contrast with alternative tools (e.g., todo_update_task) or state when not to use it. Still, the context is strong.

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 critical context: 'permanently' and 'There is no recycle bin for To Do tasks.' This reinforces the irreversibility and gives the agent a stronger reason to prefer the completion tool when appropriate. It also notes the tool returns a confirmation.

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 with no filler. The core action and permanence are front-loaded, followed by the alternative usage guidance. Every word earns its place.

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

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

For a simple delete operation with two straightforward parameters, the description fully covers what it does, the irreversibility, the return of a confirmation, and when to choose an alternative. Nothing essential is missing.

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

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

Schema description coverage is 100%, and both parameters have clear descriptions (listId and taskId). The tool description adds no additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action (deletes a To Do task), the resource (To Do task), and the key characteristic (permanently). It also differentiates from the sibling todo_complete_task by explicitly noting the alternative for non-permanent removal, making the purpose unambiguous.

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

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

The description explicitly instructs when to use this tool versus the alternative: 'prefer todo_complete_task when the user only wants it out of the way.' This direct guidance leaves no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds a key behavioral detail beyond annotations: the notes body is truncated, informing the agent that the returned content is not fully complete. This is valuable context for a read operation.

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

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

Two sentences, no fluff. The core purpose is front-loaded, followed by a precise list of returned fields and the ID prerequisite. Every word earns its place.

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

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

For a simple read tool with two parameters, full schema coverage, and annotations covering safety, the description is complete. It conveys the returned fields, warns about truncation, and explains the dependency on sibling tool outputs. No gap that an agent needs to call it correctly.