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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'reads calendars and books nothing', 'Requires Calendars.Read.Shared', and details return behavior ('candidate slots with a confidence percentage and per-attendee availability'). This meaningfully extends the annotation metadata without contradicting it.

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-loaded with the primary purpose, then covers return value, safety/next step, and required permission. Every sentence adds distinct value with no 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?

For a read-only tool with 7 well-documented parameters and no output schema, the description covers the essential context: what it does, what it returns, that it doesn't mutate, the required permission, and how to proceed with scheduling. It is sufficiently complete for an agent to select and invoke correctly.

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

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

The input schema has 100% parameter coverage with detailed descriptions (e.g., 'Only suggest slots where at least this percentage of attendees are free'). The tool description does not add parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function: 'suggest meeting times when the given attendees are free, ranked by how likely everyone is to attend.' It distinguishes itself from sibling calendar tools by emphasizing ranked candidate slots and that it 'books nothing', which sets it apart from calendar_get_event or calendar_get_free_busy.

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 use: finding meeting times based on attendee availability. It explicitly says it does not book and points to calendar_create_event for actual scheduling, giving an alternative action. It doesn't explicitly contrast with other read-only calendar tools like calendar_get_free_busy, so it stops 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the required 'Calendars.Read' permission and the specific return fields, which enriches transparency beyond the structured metadata. No contradiction.

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

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

The description is three sentences, each with a distinct purpose: presenting the operation and return contents, specifying the ID source, and noting an alternative plus permission. There is no extraneous information.

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

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

Even without an output schema, the description fully specifies the returned fields and the required input context. It also covers the alternative tool and permission requirement, making it self-contained for a simple get operation.

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

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

The schema defines meeting_id with a generic description, but the description adds provenance: the ID comes from either calendar_list_upcoming_events or calendar_list_events_in_range. This helps the agent locate a valid ID and complements the schema rather than repeating it.

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 'Get' with a clear resource 'calendar event in full' and enumerates the detail fields. It explicitly names calendar_get_event_attendees as an alternative, distinguishing it from the sibling 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?

It states the tool takes an event id from calendar_list_upcoming_events or calendar_list_events_in_range, providing a prerequisite. It also directly advises when to use a different tool ('Use calendar_get_event_attendees when only the attendee list is needed'), which gives exclusion 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 read-only, idempotent, and non-destructive behavior. The description adds that it returns email, display name, and response status per attendee, and requires Calendars.Read permission. This goes beyond annotations by describing the return payload and permission requirement, though it doesn't detail pagination or edge cases.

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 redundancy: the first sentence delivers the core function, the second explains the return payload, and the third provides usage guidance and an alternative. All content 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 one-parameter tool with no output schema, the description covers the return fields (email, display name, response status), the permission requirement, and when to use it over the sibling. It is fully sufficient for an agent to decide when and how to invoke 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?

The schema fully describes the single parameter meeting_id with a clear description, achieving 100% schema description coverage. The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description states the tool lists who was invited to a calendar event and their response status (accepted, declined, tentative, no response), using a specific verb and resource. It clearly differentiates from sibling calendar_get_event by focusing on attendee responses, 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 says to use this when the question is about who is coming, and mentions that calendar_get_event returns the same list alongside other details, providing a direct alternative. It also notes the required permission Calendars.Read, which is useful 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?

Beyond the readOnlyHint annotation, the description adds crucial behavioral context: it does not reveal meeting details ('without seeing what their meetings are'), returns specific availability categories (busy periods, slot-by-slot free/tentative/busy/out of office), and states the required permission (Calendars.ReadBasic). This significantly enhances the agent's understanding.

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 primary action and scope, then a clear alternative and permission note. Every sentence contributes value with no 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?

For a moderately complex tool with no output schema, the description adequately discloses return value structure (per-person busy periods and slot breakdown), required permissions, and tool-specific semantics (doesn't reveal meeting details). Together with the strong annotations, this gives the agent a complete picture.

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 all 5 parameters, so the schema already documents each field. The description adds context about the output shape (slot-by-slot breakdown) which indirectly relates to interval_minutes, but it does not explain individual parameters 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 uses a specific verb ('Look up whether people are free or busy') and resource, clarifying it's a read-only availability check. It also distinguishes from the sibling tool calendar_find_meeting_times by explicitly stating the difference in use case.

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: 'Use to answer "when is X available"' and provides an alternative: 'calendar_find_meeting_times is better when the goal is a slot that suits a whole group.' This clearly guides tool 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?

Beyond annotations (read-only, idempotent, non-destructive), the description discloses behavioral details: chronological ordering, inclusion of both end days, ISO 8601 format requirements, returned fields, and the required permission (Calendars.Read). This adds significant value beyond the annotations.

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

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

Three sentences, each purposeful: the first states primary function and ordering, the second gives usage context, the third covers date format, inclusivity, return fields, and permission. 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?

For a simple list tool with 3 well-documented parameters and no output schema, the description covers purpose, usage, format, return values, and permissions. It fully equips an agent to select and invoke the tool correctly without needing additional context.

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

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

Schema already covers all parameters (100% coverage), so baseline is 3. The description goes beyond the schema by clarifying that dates are ISO 8601 and that whole end days are inclusive, which enriches the meaning of start_date and end_date. max_results is adequately handled by 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 the tool's function with a specific verb ('List') and resource ('calendar events'), scoped by a date range. It also distinguishes itself from sibling tools like calendar_list_upcoming_events by noting it's for any window beyond 'the next few days'.

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?

Explicit usage guidance is provided: 'Use for any window that is not simply the next few days' with concrete examples (last week's meetings, a specific month). This clearly differentiates when to use this tool versus alternatives like upcoming events.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the permission requirement (Calendars.Read) and specifies return fields (id, subject, start/end times, organiser, online status), which goes beyond the annotations and provides useful expectations.

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 value: action and ordering, return fields, and usage guidance with a permission note. No redundancy or filler, making it highly concise and well-structured.

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 list tool with two optional parameters and no output schema, the description covers purpose, scope, alternatives, permission, and return fields. It is sufficiently complete for an agent to select and invoke correctly without 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?

The input schema has 100% description coverage with both parameters (days_ahead, max_results) clearly described. The description adds no new parameter-level details beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the signed-in user's upcoming calendar events for a specified number of days, ordered soonest first. It explicitly distinguishes from siblings by naming calendar_list_events_in_range and calendar_get_event and asserting this is 'the tool for what's on my calendar'.

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 vs alternatives: 'Use calendar_list_events_in_range for a specific window, and calendar_get_event for full detail including the join URL.' Also frames the primary use case with 'This is the tool for what's on my calendar'.

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 hints, but the description adds valuable details beyond those: supported file types (text, Office, PDF), placeholder behavior for binary files, truncation to a caller-specified limit, and required permissions. This provides rich behavioral context without contradicting 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?

The description is three succinct sentences, front-loaded with the core purpose, followed by supported formats, behavior for binary files, truncation, and permissions. Every sentence adds necessary information with no 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 file-content retrieval tool with no output schema, the description covers all critical aspects: input origins, supported file types, binary handling, output truncation, and required scope. It is self-sufficient for an agent to select and 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?

Although the schema already describes all three parameters (100% coverage), the description adds meaning by explaining where the drive_id and item_id come from (files_search or files_list_recent) and that max_chars is a character limit for output truncation. This supplements the schema-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?

The description clearly states the verb ('Read the text content') and the resource ('a file in OneDrive or SharePoint'), and specifies how to locate the file via drive id and item id from files_search or files_list_recent. This distinguishes it from sibling tools that list or search files.

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 explains the prerequisite of having a drive id and item id from files_search or files_list_recent, and notes the permission requirement (Files.Read.All). While it doesn't explicitly mention when not to use it or name alternative tools, the context is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context beyond annotations by specifying required permissions (Files.Read.All and Group.Read.All), the exact return values (drive id and web URL), and the tool's role as a prerequisite for other file tools. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the core action, and every sentence earns its place: what it does, what it returns and why, and required permissions. No redundant or extraneous information.

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

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

With no output schema, the description compensates by explaining the return values (drive id and web URL) and their purpose. It also covers prerequisites (group id from directory_search_groups), permissions, and the relationship to other file tools. For a single-parameter tool, this is 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% with group_id described as 'Microsoft 365 group (Team) id — same as team.id.' The description enhances this by specifying the source: 'given a group id from directory_search_groups,' which tells the agent where to obtain the value. This adds meaningful context 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 the tool's function: 'Get the document library backing a Microsoft 365 group or Teams team.' It specifies the resource (document library) and the action (get), and distinguishes itself from sibling file tools by noting it returns the drive id and web URL needed by other file 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 provides clear usage context: it takes a group id from directory_search_groups and explains that the returned drive id and web URL are prerequisites for other file tools. It implies when to use (before reading/writing in a team's files) but does not explicitly state alternatives or exclusions, so it falls 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 (readOnlyHint, idempotentHint, etc.), the description adds return field specifics ('Returns id, name, drive id and web URL'), ordering behavior ('most recent first'), and a permission requirement ('Requires Files.Read'). This contextualizes the tool's behavior and authentication needs without contradicting 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?

The description is two sentences: the first states the core behavior and return format, the second provides usage context and sibling alternatives. It is front-loaded with the primary action and contains no redundant information.

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

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

For a simple list tool with no required parameters and no output schema, the description is complete: it specifies the returned fields, ordering, use case, permission requirement, and how it differs from related tools. 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 input schema already fully describes the single parameter max_results with 'Maximum recently accessed files to return.' The description does not add parameter-level details, 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 uses a specific verb+resource+scope: 'List files the signed-in user has recently opened or edited, most recent first.' It clearly distinguishes the tool from siblings like files_search and files_list_trending, making its unique role 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 states when to use the tool ('Use for the document I was working on yesterday') and contrasts it with alternatives ('files_search is better when the name or a keyword is known, and files_list_trending covers what colleagues are working on'). This provides clear decision 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 indicate a safe, idempotent read operation. The description adds important behavioral context beyond annotations: the authorization requirement (Files.Read.All), the scope of items covered, and the return fields (owner and web URL). 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 two sentences with no filler. The first sentence front-loads the core purpose, and the second adds scope context and alternatives. 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 tool with one optional parameter and no output schema, the description is complete: purpose, scope, alternatives, authentication requirement, and return information (owner, web URL) are all covered. No 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?

The input schema covers the single parameter max_results with a clear description (100% coverage). The tool description does not add any additional parameter 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 clearly states the tool lists files shared directly with the user, including owner and web URL. It explicitly distinguishes from sibling tools files_list_recent and files_search by explaining why those may not surface these items.

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 when-to-use context: items shared via OneDrive/SharePoint not in the user's own drive. It names specific alternative tools (files_list_recent, files_search) and explains why they may not be sufficient.

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 annotations, it discloses the ranking mechanism ('activity signals rather than by the user's own history') and the scope ('around the signed-in user'). It also notes the API permission, adding useful behavioral context. No contradiction with the read-only, idempotent 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 concise sentences: purpose, usage guidance, and permission. Every sentence has a distinct role without redundancies. Front-loaded with the primary action, making it easy 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?

With one optional parameter, no output schema, and strong annotations, the description covers all relevant aspects: purpose, ranking behavior, usage context, alternative, and permission. Nothing important is missing for an agent to decide when and how to use 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?

The schema already fully describes the single parameter (max_results with default and description). The description adds no additional parameter-level detail beyond what the schema provides, 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 tool's function: 'List documents currently trending around the signed-in user'. It specifies the ranking source ('Microsoft 365 activity signals') and explicitly distinguishes itself from the sibling tool files_list_recent.

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 an explicit use case ('what is the team working on') and names the alternative (files_list_recent) with a clear contrast ('what this user personally touched'). Also mentions the permission requirement, indicating when the tool is applicable.

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 as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond these hints: it covers both OneDrive and SharePoint in one search, requires Files.Read.All permission, and specifies the return fields (id, name, drive id, size, last-modified date, web URL). 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 concise at three sentences, with the primary action front-loaded in the first sentence. Every sentence adds value: scope/method, return fields, and a note about combined coverage plus permission requirement. No redundant or filler 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?

Given the tool's simplicity (2 parameters, no output schema), the description is complete. It covers the search scope, the input semantics, the permission requirement, and the return fields. Combined with strong annotations and full schema coverage, the tool is fully specified for an AI agent to select and 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?

The input schema provides full descriptions for both 'query' and 'max_results', so the baseline is 3. The description adds extra semantics by clarifying that the query can target both filename and content keywords, which enriches the meaning of the 'query' parameter beyond the schema's generic description.

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

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

The description clearly states the action ('Search'), the resource ('signed-in user's OneDrive and the SharePoint sites they can reach'), and the method ('by filename or content keyword'). It also distinguishes itself from sibling file tools by emphasizing that both OneDrive and SharePoint are covered in a single search, which is a specific and differentiating detail.

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 this tool: when searching for files across OneDrive and SharePoint by name or content. It does not explicitly mention alternative tools for other file operations (e.g., files_list_trending or files_get_content), so it lacks explicit exclusions, but the scope and return fields are well-defined.

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?

Descriptions adds useful context beyond the annotations: it returns full bodies, orders oldest first, and requires Mail.Read. However, the claim 'every message' is not strictly accurate since the max_results parameter can limit the number returned; this is a minor inconsistency that prevents 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 description is two sentences, front-loaded with the core action, and every clause earns its place. No fluff or repetition of schema details.

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 tool with two well-documented parameters and strong annotations, the description covers purpose, usage, ordering, and auth. It doesn't explain return format in detail, but no output schema exists and the statement about full message bodies is likely sufficient. The max_results caveat is the only notable omission.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The tool description does not add meaning beyond the schema except for the hint that conversation_id comes from listing tools, which is minor. 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 reads every message in one email conversation, oldest first, and distinguishes itself from mail listing tools by returning full message bodies rather than previews. The verb 'read' and resource 'email conversation' are specific and unambiguous.

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

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

It explicitly says to use this tool when you have a conversation ID from any mail listing tool and need full bodies before replying or summarising. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

Despite strong annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds meaningful behavioral detail: it returns metadata only, never file contents, is safe on large attachments, excludes inline images, and requires Mail.Read. This goes beyond the annotations and helps the agent anticipate edge cases.

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, no filler. The first sentence states the core purpose, the second adds safety/behavior, and the third notes an exclusion and a permission requirement. 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 tool is simple (one required param, no output schema), and the description fully covers purpose, return scope (metadata only), safe usage, exclusions, and required permission. Combined with strong annotations, this is complete for the tool's complexity.

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

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

Schema coverage for the single parameter (message_id) is 100%, so the schema already describes it. The description adds minimal parameter-specific meaning beyond 'one email,' which is implied by the tool name and schema. Baseline 3 applies because the schema carries the load.

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+resource ('List the file attachments on one email') and enumerates the exact fields returned (name, content type, size in bytes). It clearly distinguishes itself from sibling tools like mail_list_recent by focusing on attachments of an individual 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?

The description provides clear context: use this to get attachment metadata safely even for large attachments, and notes that inline images are excluded. It does not explicitly name alternatives or state 'use X instead,' but the context is sufficient for an agent to pick this over other mail 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 (readOnly, idempotent, non-destructive), the description adds valuable behavioral context: requires Mail.Read permission, returns specific fields (id, subject, sender, date, preview), orders newest first, and explains the meaning of flags as the user's own marker. This enriches the agent's understanding substantially.

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, front-loaded with the core action, and every clause adds meaningful information. It efficiently covers purpose, scope, ordering, return fields, permissions, and usage distinction without any 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?

For a simple list tool with one optional parameter and no output schema, the description is remarkably complete. It specifies the user scope, ordering, return fields, permission requirement, and the conceptual purpose, leaving little ambiguity about 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?

The single parameter max_results is fully documented in the schema with a clear description ('Maximum flagged emails to return'), so schema coverage is 100%. The tool description does not add further detail about the parameter, which is acceptable given the schema already covers it. 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 tool lists emails flagged for follow-up, with a specific verb and resource, and explicitly distinguishes it from mail_list_recent by noting the latter returns everything regardless of state. This makes the purpose unambiguous and sibling-differentiated.

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

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

The description provides explicit guidance: use for 'what do I still need to deal with' rather than mail_list_recent, which is an alternative tool. This directly addresses when to use this tool and gives an exclusion, meeting the highest bar for usage guidelines.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful context beyond annotations: requires Mail.Read permission, returns id/subject/sender/date/preview, and orders newest first. It does not contradict annotations, and the added details help set expectations for 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 two sentences, front-loaded with the core action, then usage guidance, an alternative, and a permission note. Every clause earns its place, with 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?

For a simple read-only list tool with two optional parameters and no output schema, the description covers purpose, usage context, return fields, ordering, permission, and the alternative tool. It is fully self-contained and enables correct invocation without additional context.

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

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

Schema coverage is 100%, with both parameters described ('Number of days back to fetch' and 'Maximum emails to return'). The description only adds the phrasing 'last N days' which mirrors the schema, so it does not significantly enhance parameter understanding. 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 'List the signed-in user's most recent emails from the last N days, newest first' with a specific verb and resource scope. It distinguishes itself from mail_search by noting that mail_search is for known keywords/senders, and from mail_list_flagged by focusing on recency rather than flags.

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 explicitly provides when to use: 'Use for what came in today or catching up after time away' and names the alternative: 'mail_search is the tool when specific keywords or a sender are known.' This directly answers the when-to-use vs alternatives question.

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 annotations, the description discloses the return structure ('Returns id, subject, sender, date and a preview snippet'), ordering ('newest first'), folder constraints, and permission requirement ('Requires Mail.Read'). This adds substantial behavioral context without contradicting the readOnly, idempotent 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 three sentences, front-loaded with the core purpose, and every sentence adds value: purpose, return/ordering, alternatives, and permissions. There is no 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?

The description thoroughly covers the tool's behavior—search scope, output fields, ordering, folder options, permission requirements, and sibling tool alternatives—despite lacking an output schema. It provides enough context for an agent to select and 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?

The input schema already covers all parameters with clear descriptions, so the baseline is 3. The description does reinforce query semantics and folder enumeration but adds little beyond the schema's own 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 function: 'Search the signed-in user's mailbox by keyword, subject or sender name.' It specifies the resource (mailbox), the action (search), and the fields searched, and it distinguishes itself from sibling tools by naming alternatives.

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: 'Use mail_list_recent when the ask is time-based rather than keyword-based, and mail_get_thread to read a whole conversation.' It also explains the scope of searchable folders, giving clear context for when 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 this as read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context by specifying the required permission (User.Read.All), the failure condition for non-tenant addresses, and the exact fields returned, which goes beyond the annotation metadata.

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 yet packed with essential information: what it does, when to use it, the alternative, failure behavior, and permission requirement. No unnecessary words; 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 one-parameter tool with no output schema, the description is remarkably complete. It covers the return content, usage context, failure mode, and permission prerequisites, leaving little ambiguity about the tool's behavior in typical scenarios.

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% parameter coverage with a simple 'email' parameter. The description enriches this by clarifying that the email must be exact, that it refers to a person in the organization, and that non-tenant addresses will cause a failure. This adds meaning beyond the schema's basic description.

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

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

The description clearly states the tool's function with a specific verb ('Look up') and resource ('one person in the organisation by their exact email address'), and lists the output fields. It explicitly distinguishes itself from the sibling tool people_search, making its purpose unambiguous.

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

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

The description gives explicit usage guidance: 'Use when the address is already known' and names the alternative for partial/approximate searches (people_search). It also notes failure conditions and permission requirements, which helps the agent decide when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds the 'Requires User.Read' permission requirement, which is not in the annotations, providing useful behavioral context beyond what structured data provides.

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: the main action, usage guidance with examples, and permission requirement. Every sentence earns its place, no fluff, and the most important information 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 simple self-profile retrieval tool with zero params and no output schema, the description is complete: it states what is returned (name, email, job title, department, office), when to use it, and the required permission. No 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?

The tool has zero parameters, so the description doesn't need to explain parameter meaning. It mentions 'Takes no arguments', which is redundant with the empty schema but harmless. Baseline for 0 params is 4, and no additional info is needed.

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: 'Get the signed-in user's own profile' and lists the specific fields (name, email, job title, department, office). It uses a specific verb + resource and distinguishes itself from sibling tools like people_get and people_search by explicitly focusing on the signed-in user.

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 this first when a request says "me", "my" or "I"' and gives concrete examples like filtering a calendar or addressing a message. This tells the agent exactly when to use this tool versus 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 (readOnlyHint: true, idempotentHint: true) already establish a safe, non-destructive read operation. The description adds that the tool returns names, email addresses, and phone numbers, and requires the Contacts.Read permission, giving context beyond the structured hints. It also clarifies that results are limited to the signed-in user's saved contacts, not the broader directory.

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?

All three sentences are purposeful: the first explains the action/output, the second provides key differentiation, and the third adds a use case and permission requirement. There is no redundancy with the schema or 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-param list tool with strong annotations, the description fully covers purpose, usage boundaries, permission, and expected return fields. It even contextualizes the relationship to sibling tools, making it self-sufficient.

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 covers the only parameter (max_results) with a full description and range (1-100), so schema_coverage is 100%. The description adds no further param-specific semantics, meeting the baseline of 3 for high coverage.

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 'List the signed-in user's saved Outlook contacts' – a specific verb and resource. It further distinguishes itself by stating it's the only place external contacts live and references specific sibling tools (people_search, directory_search_users). This clearly defines its purpose.

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

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

The description explicitly conditions usage: it's the personal address book where external contacts live, and it's invisible to directory searches. It even says 'Use it for phone numbers,' providing a concrete trigger condition. It names the alternatives (people_search, directory_search_users) and implies when not to use them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: personalization via mail/meeting history, fuzzy matching ('without exact spelling'), return fields (name, email, title, department), and permission requirement ('Requires People.Read'). This exceeds the structured 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 fluff: purpose/behavior, return fields, and alternatives/permission. It is front-loaded with the core purpose and each 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 two-parameter tool, the description is complete: it covers what it does, how results are ranked, what fields are returned, when to use alternatives, and the required permission. No output schema exists, but the return fields are listed explicitly.

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 query and max_results are fully described in the schema. The description adds overall context but does not meaningfully expand on parameter semantics beyond the schema's own descriptions. 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 tool's function: 'Find colleagues the signed-in user actually works with' with a specific verb and resource, and differentiates it by ranking from mail/meeting history. It explicitly contrasts with directory_search_users and people_list_contacts, making its purpose unmistakable.

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 guidance is explicit: 'Use directory_search_users to search the whole tenant instead, or people_list_contacts for the saved address book.' This tells the agent when to choose alternatives, and the description implies this tool is for personalized work-related searches.

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 and idempotentHint annotations, the description discloses the personal-address-book-only scope, the fact that it returns emails and phone numbers, and the required permission (Contacts.Read). This adds meaningful behavioral context that annotations alone do not 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?

Three sentences with no wasted words: purpose is front-loaded, differentiation is immediately clear, and the permission requirement is stated at the end. 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?

Given the tool's simplicity (2 params, no output schema), the description fully covers what the tool does, what it returns, when to use it, and what permission is needed. It is complete for an agent to decide on and 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 description coverage is 100%, so the baseline is 3. The description's 'name or company' phrasing mirrors the query parameter's schema description and adds no new semantic detail. max_results is already well-described in the schema, so no compensation needed.

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 ('Search') and resource ('signed-in user's saved Outlook contacts') with clear scope ('by name or company') and output ('returning emails and phone numbers'). It also explicitly distinguishes itself from sibling tools by naming people_search and directory_search_users, making the tool's unique role clear.

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 when-to-use guidance: it states this searches only the personal address book and directs users to alternative tools for other scopes (colleagues via people_search, whole tenant via directory_search_users). It even highlights that this is the one for external contacts, giving clear selection 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, so the tool is a safe read operation. The description adds valuable behavioral context beyond annotations: each entity type requires its own permission, and it lists the specific permissions needed (Mail.Read, Calendars.Read, etc.). This informs the agent about setup requirements. It also mentions KQL support, which is a behavioral feature. No contradictions with annotations.

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

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

The description is concise, well-structured, and front-loaded. The first sentence states the core purpose, the second gives strategic usage guidance, and the third covers permissions. No filler or redundant content. 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 cross-workload search tool with no output schema, the description is fairly complete: it covers purpose, when to use, permissions, and query language. It doesn't mention return format or pagination, but those are not critical for a search tool and the schema covers parameter constraints. The permission requirements are critical for actual invocation and are clearly stated. Minor gaps prevent a 5.

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 largely repeats what the schema already documents (KQL example is present in both). It adds the permission-per-entity-type note, which is not directly tied to parameter meaning but provides useful context. Overall, the description does not significantly enhance parameter semantics beyond the thorough 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?

Description clearly states the tool's purpose: search across Microsoft 365 in one call, enumerating specific workloads (email, calendar, files, SharePoint, people). This distinguishes it from siblings like mail_search or files_search by emphasizing the cross-workload scope. The verb 'search' is specific and the resource is clearly defined.

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 recommends this as the 'best first move for a vague request', providing clear when-to-use guidance. It also explains that it spans workloads no other single tool covers, which implies when not to use it (for narrow, workload-specific queries). However, it does not explicitly name alternative tools or provide when-not-to-use scenarios, so a 4 is appropriate.

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