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

No annotations are present, so the description carries the full burden of behavioral transparency. It states the destructive action (deleting cached tokens and pending login state) and adds a 'Development only' caveat, but it does not disclose potential side effects on the current session or clarify that this is local-only, which would be useful for a destructive operation.

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

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

The description is extremely concise and front-loaded. The first sentence 'Development only.' immediately communicates the context, followed by a precise action statement. The Chinese intent examples add multilingual value without bloat. 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 tool with no parameters and no output schema, the description is largely complete. It covers the purpose, the environment restriction, and the exact state cleared. However, it could go slightly further by stating whether this impacts server-side auth sessions or what the expected result is, which would enhance completeness.

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

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

With zero parameters, the schema is trivially 100% covered. The baseline for no parameters is 4, and since there are no parameters to explain, the description does not need to add parameter semantics. It correctly avoids unnecessary detail.

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: to delete locally cached tokens and pending device-code login state. It uses a specific verb ('Delete') with a clear resource and distinguishes itself from sibling auth tools like auth_start_device_login and auth_complete_device_login.

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 includes a clear usage context: 'Development only.' This indicates when the tool should be used (development environments) but does not explicitly mention alternatives or exclusions beyond environment. The uniqueness of the action makes usage context reasonably 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?

With no annotations, the description carries the transparency burden. It discloses key behaviors: polling, local caching, and that 'Token values are not returned.' It also notes 'Development only,' providing a usage constraint. However, it omits error/timeout behavior.

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

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

The description is concise and front-loaded with the core action. The addition of Chinese intents is supplementary but still compact. Every sentence serves a purpose, though the localization list could be seen as extra.

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 tool with no output schema, the description covers the essential flow (poll, cache, no token return) and the development-only caveat. It could be more complete by explicitly referencing the preceding auth_start_device_login step, but overall it is adequate.

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

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

The only parameter, timeoutSeconds, is fully described in the schema. The tool description does not add further parameter semantics, but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Poll the token endpoint after the user enters the device code, then cache the token locally.' This distinguishes it from sibling auth tools like auth_start_device_login and auth_status.

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

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

The description provides clear context for when to use: after the user enters the device code, and it restricts usage to 'Development only.' It does not explicitly name alternatives, but the sequencing with the device login flow is implied.

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

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

With no annotations, the description carries the behavioral burden. It explicitly discloses 'Development only' and that the result is cached locally, which are important behavioral traits. It does not detail the interactive device-code prompt or local cache format, but it provides meaningful transparency beyond a vague verb.

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

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

The description is brief and front-loaded: a development-only warning, the core action, and the caching result. The Chinese intent list adds value for multilingual intent matching without unnecessary 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 low-complexity tool with one optional parameter and no output schema, the description is largely complete: it states the purpose, context, and side effect. It omits the next step (e.g., use auth_complete_device_login) and what the tool returns, but the sibling list and title make this inferable.

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 covers 100% of parameters and already describes the optional scopes override and its default. The description adds no extra parameter semantics, but the baseline of 3 applies because the schema does the heavy lifting sufficiently.

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

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

Description clearly states a specific action: 'Start a 21V Entra device-code login and cache the result locally.' It names the resource (Entra device-code login), the verb (start), and the side effect (cache locally). This differentiates it from sibling tools like auth_complete_device_login and auth_status.

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 with 'Development only' and implies when to use the tool (when initiating a local device-code login). However, it does not explicitly contrast with or point to related tools, such as auth_complete_device_login for finishing the flow, nor does it 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?

No annotations are present, so the description carries the full burden. It adds a key privacy disclosure that token values are never returned, and the verb 'Inspect' implies read-only behavior. It does not mention network side effects or rate limits, but for a zero-parameter status tool, this is adequate.

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

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

The description is concise, with key information front-loaded in the first sentence. The Chinese intent mapping adds value without unnecessary bloat, and 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?

Even without an output schema, the description conveys what information is exposed (auth state, token state, OAuth/OBO configuration, user details) and the critical privacy boundary. It is sufficient for a read-only diagnostic tool with no parameters.

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 schema coverage is 100%, so the baseline is 4. The description adds meaningful context about what the status inspection covers, which is sufficient given no parameters exist.

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

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

The description uses the specific verb 'Inspect' and enumerates the exact resources covered (MCP auth state, local token state, remote OAuth/OBO configuration, current request user details). It clearly distinguishes this tool from sibling auth tools that start, complete, or clear login flows.

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

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

The description provides clear context for when to use it, including '诊断授权问题' (diagnose authorization issues) and checking login status. It does not explicitly name alternatives or exclusions, but the diagnostic intent and read-only scope differentiate it from mutation-focused auth siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the required delegated Calendars.Read permission and the fact that recurring instances are expanded into the result set. It does not discuss pagination or result limits, 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?

The core purpose is front-loaded in the first clause, and the auth requirement and returned-field list follow compactly. The Chinese intent list is long but serves a routing purpose. A small amount of redundancy exists between the returned-field enumeration and the schema, but overall it is 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?

There is no output schema, so the description usefully enumerates the returned fields (subject, time, location, organizer, my response, attendees, cancellation state), which an agent needs to decide whether this tool answers a query. Combined with the stated permission requirement, it covers the four-parameter, two-required read tool adequately; only paging/limit behavior is unaddressed.

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 every parameter already carries its own documentation, including defaults for top and timeZone and ISO 8601 handling for the date bounds. The description's 'date-time range' phrasing only echoes that the two required parameters form the range, adding no syntax or format detail beyond the schema. 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 states a specific verb (List) and resource (meetings and events) with an explicit scope (date-time range, including recurring instances) and enumerates the fields returned. It is the only calendar tool among the siblings, so there is no ambiguity to resolve, and an agent can tell immediately what the tool fetches.

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 clear context for when to use the tool ('in a date-time range', including recurring instances) and reinforces it with example intents in Chinese. It does not name exclusions or alternative tools, but with a single calendar sibling set there is little to disambiguate, so this is strong-but-incomplete 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals crucial traits: the token is user-bound, one-time, and short-lived, and the tool never grants approval. However, it does not explicitly state potential side effects (e.g., whether the operation is destructive) or error behavior, which would add further transparency.

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

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

The English text is concise, with two sentences that efficiently communicate purpose and usage. The addition of a Chinese translation line is redundant for an AI agent but does not harm clarity; it merely adds a bit of length. Overall, it is well-structured and free of 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 tool with one parameter, no output schema, and no annotations, the description is fully contextual. It explains the exact flow (pending operation, web preview approval, token constraints), the precondition, and the tool's non-approval role. There are no significant gaps that would hinder correct invocation.

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

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

The schema describes confirmToken as 'One-time token returned by the pending operation,' but the description adds meaningful semantics: the token is user-bound, short-lived, and must belong to the same signed-in user who approved the preview. This goes beyond the schema's basic type/role information.

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

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

The description clearly states the tool's function: 'Continue a pending sensitive operation after the same signed-in user approved its web preview.' This specifies the verb (continue), the object (pending sensitive operation), and the condition (after user approval), which distinguishes it from sibling tools like auth_complete_device_login that handle login flows, not operation execution.

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 explicit usage guidance: 'Call it only after the user says the confirmation page was approved' and 'This tool never grants approval itself.' This gives a clear when-to-use condition and a when-not-to-use (it does not approve), which is sufficient for an agent to decide when to invoke it.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial beyond that: the URL is short-lived and pre-authenticated, pdf conversion applies to Office files, small plain-text files return inline, and SharePoint requires the mcp.sharepoint App Role.

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?

Purpose and inputs are front-loaded in the first sentence with no wasted lead-in. The trailing multilingual keyword block is somewhat of a routing dump but does aid intent matching, so the cost is small.

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, so the description carries the return-value burden and does so: it specifies a short-lived pre-authenticated download URL and inline text for small files. Auth requirement for SharePoint is also covered.

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, but the description adds real meaning: format=pdf converts Word/Excel/PowerPoint, and includeText behavior (small plain-text files returned inline) is explained beyond the schema's terse notation.

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 (Resolve/return) and resources (OneDrive/SharePoint file, download URL) with clear scope. An agent can distinguish it from files_search, which locates items rather than producing a fetchable URL.

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?

States two concrete entry paths — a pasted link or driveId+itemId — and notes the SharePoint App Role prerequisite. It stops short of explicitly naming when to prefer files_search or files_get_download_url, but 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 cover readOnlyHint=true and openWorldHint=true, so safety profile is given. Description adds valuable non-structured context: SharePoint results require the mcp.sharepoint App Role, and lists the exact returned fields. This is genuinely beyond what the schema/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?

Front-loaded with purpose, then filters, then return values, then auth requirement, then Chinese intent keywords. Efficient overall; the Chinese intent list is useful for routing but slightly bulky.

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

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

Covers purpose, filters, returns, and the SharePoint App Role requirement. With no output schema, the description does list key return fields, which is helpful, but omits pagination/top behavior nuance beyond the schema default and broader auth expectations. Adequate but leaves gaps.

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

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

Schema coverage is 100% and includes enum and bounds descriptions, so the schema carries parameter meaning. Description summarizes filters (site, file type, modification date) but adds no format/syntax detail 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?

States a specific verb+resource ('Find documents across OneDrive and SharePoint sites') and explicitly names the coverage scope ('the signed-in user can open'). Differentiates from sibling files_get_download_url by stating the returned fields feed into 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?

Clear context for when to use (keyword search across OneDrive/SharePoint, filterable by site/type/date) and points explicitly at files_get_download_url as the follow-up. No explicit 'when not to use' or named alternative search tools, but nothing is misleading.

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, readOnlyHint=false, and openWorldHint, so the safety profile is partly covered. The description adds genuinely useful context beyond them: rechecks for App Roles, confirmation policy, audit, and Graph scope controls, plus the failure behavior ('invalid parameters return the expected schema'). It does not describe what specifically gets destroyed on a mutating call, keeping it from 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?

Front-loads the core verb and object in the first sentence, then layers workflow, security behavior, and error handling. The trailing Chinese intent keywords are extra bulk but serve a legitimate multilingual routing purpose, so the structure is efficient overall.

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 is not obligated to explain returns, and it covers purpose, prerequisites, re-validation behavior, and error signaling. For a generic gateway executor with a nested, free-form parameters object, the coverage is solid though it says nothing about execution scope limits or success semantics.

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 parameters (toolName and parameters) are already documented in the schema, giving a baseline of 3. The description reinforces the relationship between 'parameters' and the target tool's inputSchema but adds no format, syntax, or constraint detail 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?

States a specific verb (Execute) and resource (a tool returned by gateway_search_tools), and explicitly anchors the tool within the search→schema→execute chain that distinguishes it from gateway_search_tools and gateway_get_tool_schema. An agent can immediately tell what this does and how it differs from its 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?

Names the prerequisite producer (gateway_search_tools) and the parameter source ('matching its inputSchema' / gateway_get_tool_schema), so the intended workflow is clear. It stops short of explicit when-not-to-use guidance or naming confirm_execute as an alternative, so it is not a full 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful disclosure that the response contains not just the input schema but also "authorization metadata" – important because there is no output schema to reveal the return shape.

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 core purpose in the first clause, with the prerequisite immediately following. The trailing Chinese-intent keyword line is padding for a mostly English-speaking agent, but it is brief and does not obscure the meaning.

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 tool with annotations covering safety, the description supplies the missing pieces: the provenance of the required name and the fact that authorization metadata is returned. Only minor details (e.g., behavior when a name is unknown or not from search) are unaddressed.

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 single parameter is fully documented in the schema (100% coverage), which already states it must be the exact tool name returned by gateway_search_tools. The description reinforces that provenance but adds no format, casing, or validation detail beyond the schema, so the baseline of 3 applies.

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

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

Specific verb (Get) plus a precisely named resource (exact input schema and authorization metadata) for a tool supplied by gateway_search_tools. It is clearly distinguishable from its siblings, especially gateway_search_tools (the discovery step) and gateway_execute_tool (the invocation step).

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 states the prerequisite clearly: the tool name must be one returned by gateway_search_tools, which tells an agent when this tool is applicable in the search -> inspect -> execute flow. It does not state exclusions (e.g., when to skip schema lookup), 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: results are limited to the user's authorized tools, top hits carry input schemas, and intent can be expressed in either language. It does not mention result limits/pagination or ranking behavior, so it stops 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?

The capability statement and the exclusion clause are front-loaded in a single efficient sentence. The trailing Chinese-language phrase list ('搜索可用工具, 查找能完成任务的工具...') is somewhat redundant filler, which keeps it from a 5.

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

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

For a read-only discovery tool with no output schema, the description adequately conveys what comes back (top-ranked tools with embedded input schemas) and the scope of the search corpus. It omits anything about result volume limits, ranking or empty-result behavior, but nothing critical for correct invocation 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 limit, query, category and schemaCount are already documented with defaults, bounds and purpose. The description restates the query's language flexibility and the schema-embedding behavior of results, but adds no syntax, format or filtering nuance beyond the schema, making the 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 names a specific verb and resource ('Search the signed-in user's authorized Microsoft 365 tools') and scopes it by intent language (English or Chinese). It also carves out the boundary against the directly exposed siblings by listing the capability areas it covers that they do not.

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 exactly when to reach for it ('for anything the directly exposed tools do not cover') and gives concrete examples (sending, scheduling, OneDrive/SharePoint, contacts, users). It also routes the agent away from gateway_get_tool_schema by noting top results carry their input schema, so the alternative tool is explicitly made unnecessary.

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 openWorldHint, but the description adds genuinely useful behavior beyond them: the delegated Mail.Read requirement, plain-text output with recipients and attachment list, onlyNewContent stripping the quoted thread, and offset-based continuation for long bodies. Only the return shape/pagination envelope is left unstated.

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 information-dense sentences front-loaded with the core action, followed by the permission and localized intent keywords. The Chinese intent list is repetition for intent matching rather than new content, which keeps it just short of a 5.

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

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

For a six-parameter read tool with no output schema and 100% schema coverage, the description covers the action, output form, permission requirement, attachment inclusion, and long-body continuation. An agent has enough to call it correctly, with only pagination/return envelope details unaddressed.

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 for the chained offset pattern ('long bodies continue with offset') and clarifies onlyNewContent's effect ('drops quoted earlier mails'). bodyFormat and includeAttachments rely on the schema, but the description still earns above 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?

States a specific verb and resource ('Read one message') with the returned shape (plain text, recipients, attachment list). This clearly distinguishes it from mail_list_messages and mail_search_messages, which the agent can tell apart 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?

Usage is implied rather than stated: 'Read one message' plus the offset-continuation note communicates the retrieve-by-id workflow, and the permission requirement gives a prerequisite. However, it never explicitly says when to prefer this over mail_list_messages or mail_search_messages, leaving the routing 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 declare readOnlyHint=true and openWorldHint=true, but the description adds real context beyond them: the delegated Mail.Read auth scope and the default ordering (newest first). It also hints at return shape (sender, recipients, preview, read/flag state), though it does not mention pagination behavior implied by the cursor parameter.

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 what it does and what it returns, then the filters, then the alternative, and finally the auth requirement. The Chinese intent list is long but serves a concrete routing purpose for non-English queries; the rest is waste-free.

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 conveys the return fields, the default folder, ordering, auth scope, filter taxonomy, and the sibling alternative. Nothing an agent needs in order to call 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 all nine parameters with enums, defaults, and formats. The description groups the filter dimensions and restates the inbox default, which mirrors rather than extends the schema, 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?

States a specific verb (List) and resource (mail), plus ordering (newest first) and the returned fields (sender, recipients, preview, read and flag state). It explicitly names the sibling it is not (mail_search_messages for keywords), so an agent can distinguish it 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?

Enumerates the filter contexts (folder, time window, unread, flagged, importance, sender) that select this tool and routes keyword-based retrieval to mail_search_messages explicitly. The condition that governs the alternative is stated, not 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 cover the read-only and open-world profile; the description adds genuinely new behavioral context – the delegated Mail.Read permission requirement and default all-folders scope. It stops short of describing pagination or result ordering, so it is strong but not exhaustive.

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 search behavior and syntax up front, with permission and scope details following. The Chinese intent list adds length but serves a real matching purpose, so it stays reasonably tight.

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 read-only search tool with no output schema and full schema coverage, the description supplies the key extras – auth requirement and folder scope. Missing only return-value hints (nextCursor usage) which the cursor parameter largely implies.

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 query, folder, top and cursor are already documented with their KQL syntax and limits. The description's examples restate schema content and the folder-default note duplicates the schema, 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?

States a specific verb (Search) and resource (mail) plus concrete KQL examples like from:Zhang Wei and hasAttachments:true. The keyword-search framing clearly separates it from sibling mail_list_messages and 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?

Provides clear trigger context via KQL examples and Chinese intent phrases (搜索邮件, 查找某人发的邮件) that map user phrasing to this tool. It notes the all-folders default unless folder is set, but does not name an alternative or a when-not-to-use condition (e.g. fetch a single known message).

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 openWorldHint, so the safety profile is covered. The description adds real value beyond them: the per-page ordering, the auth requirement, the fact that system messages are excluded by default, and what each message contains. Return format and pagination interplay are not fully spelled out, keeping it below 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?

Front-loaded with the core action and scope in the first sentence, then pagination and auth. The Chinese intent list is useful for retrieval but adds length; overall still tight and free of 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 7-parameter read tool with no output schema, the description covers ordering, page size default, content returned, paging via nextCursor, and the required permission. Auth and system-message defaults are highlighted, so an agent has enough to invoke it correctly, though it does not describe error or empty-result behavior.

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

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

Schema description coverage is 100%, so top, since, until, cursor, format and includeSystemMessages are already documented in the schema. The description restates the since/until window and nextCursor without adding syntax or format detail beyond what the schema provides, 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 and resource ('Read messages in a Teams chat') plus the returned shape (plain text, sender, @mentions, shared files) and ordering (oldest first within a page). This clearly distinguishes it from sibling list/search tools like mail_list_messages and teams_list_chats.

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?

Explains the since/until window and that nextCursor pages to older messages, and names the required permission (delegated Chat.Read). It gives clear operational context but does not explicitly contrast itself with alternatives such as mail_search_messages for keyword lookups.

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

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

With readOnlyHint and openWorldHint already declared, the description adds real context: the required delegated Chat.Read scope, the sort order, and the fact that each result carries member names and a last-message preview. Pagination behavior itself is left to the schema's cursor field rather than explained.

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 and ordering, then parameter guidance, then a short prerequisite. The Chinese intent list is longer than strictly necessary but serves genuine multilingual intent matching. No wasted sentences aside from that block.

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 read-only list tool with no output schema, the description supplies what the schema cannot: the shape of each returned item (member names, last message), the ordering, auth requirements, and filter intent. 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 interpretive value beyond the schema text: 'since' is framed as 'keep only chats with new messages' rather than only an ISO timestamp bound, and 'query' as finding a chat by person or topic. 'top' and 'cursor' are left to the schema, which documents them adequately.

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 ('List ... Teams chats'), names the covered chat kinds (one-on-one, group, meeting), and specifies ordering ('most recently active first') plus returned fields (member names, last message). That scope cleanly separates it from teams_list_chat_messages, which lists messages inside a chat.

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 routes parameter choice: 'Use since to keep only chats with new messages, and query to find a chat by person or topic.' It also surfaces the delegated Chat.Read prerequisite. It never names the sibling teams_list_chat_messages as the alternative for reading message contents, so there is a gap at the boundary.

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