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

No annotations, so the description carries the full burden. It usefully discloses the upsert-like behavior (Graph returns an existing chat) and the return shape, but says nothing about permissions, whether repeated calls create duplicate messages, or notification side effects.

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

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

Front-loads the action and the no-lookup insight, then gives the return values and parameter hint. The parameter note is dense but every sentence contributes; no filler.

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

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

With an output schema present, the return-value mention is a bonus rather than a necessity, and the key ambiguity an agent would hit (whether to resolve the chat or the user first) is resolved. The remaining gap is message-format guidance for a mutation tool with no annotations.

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 0%, so the description must compensate. It thoroughly documents user_email (userPrincipalName, user id from get_user, alias caveat) but says nothing about the 'message' parameter's accepted format (plain text vs. HTML/markdown).

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 composite action: send a message in the 1:1 chat with a user, creating the chat if it doesn't exist. It explicitly distinguishes itself from list_chats (no lookup needed) and, by specifying '1:1', implicitly from create_group_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?

Gives clear usage context: 'no need to look it up with list_chats first' removes a common pre-step an agent would otherwise take. It does not state when NOT to use it or call out send_chat_message as the alternative for existing chats, so it stops short of full routing 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, the description carries the disclosure burden and does well: it warns that every call creates a new chat and Graph will not reuse a group chat with identical members, which is non-obvious behavior an agent must plan around. It omits permission/auth requirements, so not a full 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 alternative-tool routing in the second sentence, then compact per-parameter lines. No filler; each sentence carries distinct 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 3-parameter, annotation-free mutation tool with an output schema present, the description covers purpose, alternative routing, no-dedupe behavior, and all parameter formats. Return values are covered by the output schema, so nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must supply param meaning, and it documents all three: member_emails with an explicit comma-separated sign-in-address format plus an example, and topic/message as optional. It adds real format guidance beyond the bare schema property names.

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 ('Create a new group chat') with an explicit scope qualifier ('you and at least two other users'), which immediately distinguishes it from the single-recipient sibling create_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 the agent to an alternative ('For one other person use create_chat') with the exact condition that selects it. It also discloses when NOT to expect reuse, telling the agent this is not an idempotent get-or-create.

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 full burden and does well: it discloses that the delete is soft, that other members will see a placeholder, and that no undo exists, which is meaningful irreversibility context. It stops short of naming permission/auth requirements or rate limits, leaving a modest gap 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?

Four short sentences, front-loaded with the core action and followed by per-case parameter guidance. Slight redundancy between the opening scope line and 'Works on top-level channel messages and on chat messages,' but no wasted sentences 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?

An output schema exists, so return values need not be explained, and the description covers action, routing, limitation, and irreversibility. It is nearly complete for a destructive 4-param tool, missing only authorization/permission expectations.

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 0%, so the description must compensate, and it does: it maps exactly which parameters pair with which message type, resolving the ambiguity left by a schema that marks only message_id as required and expresses no conditional requirement.

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 (soft-delete a message) plus the scope constraint that it must be a message the caller sent. This distinguishes it cleanly from update_message and the send_* siblings without needing to open 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?

Gives explicit conditional routing: team_id + channel_id + message_id for channel messages, chat_id + message_id for chat messages. It also supplies an explicit exclusion (channel thread replies are not supported) with the reason, so the agent knows when not to use 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?

No annotations are provided, so the description carries the full burden and largely meets it: it discloses the return value (local file path), the side effect (image written to the system temp directory of the server host), and that the file is not deleted afterwards. It omits auth/permission requirements and any rate-limit or cleanup 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?

Front-loaded with the one-line purpose, then broken into terse conditional lines for each message context, followed by return/side-effect notes. Every sentence adds a distinct fact and none are 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 6-parameter tool with no annotations and an output schema present, the description covers exactly what the structured fields cannot: context routing, the excluded attachment type, the temp-directory side effect, and the return form. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate and does so meaningfully: it maps parameters to their scenarios (which combination applies to channels vs replies vs chats) and identifies the origin of hosted_content_id ('from the hostedContents array in message data'). It leaves some identifiers (team_id, channel_id, message_id) defined only by name rather than by source, so it is not fully exhaustive.

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 ('Download') and a precisely scoped resource ('an inline image (hosted content) from a message'), and immediately narrows what is NOT covered (SharePoint/OneDrive file attachments). An agent can distinguish it from siblings like get_message or search_messages without opening any schema.

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

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

Gives explicit routing rules per context: team_id+channel_id+message_id for channel messages, an added parent_message_id for channel replies, and chat_id+message_id for chats. It also states the negative case (file attachments listed under `attachments` cannot be downloaded here), which is exactly the when-not guidance an agent needs.

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 burden and does disclose behavior beyond the schema: the return payload shape (chat_id or team_id+channel_id, parent_message_id, id, sender, createdDateTime, content) and the non-obvious pagination quirk that 'after alone returns the newest messages'. It stops short of stating access prerequisites (e.g. membership) or failure modes, so it is strong but not complete for an annotation-free tool.

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

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

Front-loaded with purpose in the first sentence, followed by addressing modes then return shape; every paragraph carries information. The trailing pagination advice for a sibling tool is useful routing but lengthens the block more than strictly necessary for this tool.

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

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

An output schema exists, so the return-value prose is a bonus rather than a requirement, and the addressing logic is fully covered for a six-parameter, all-optional tool. Missing only edge behavior such as permission requirements and what happens with an unresolvable link or mismatched ids.

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 0% across six params, so the description must compensate, and it largely does: it explains the link URL shape, the chat_id+message_id combination, the team_id+channel_id combination, and the role of parent_message_id as the thread root for channel replies. It does not document id string formats or note which combinations are invalid, leaving a gap.

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

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

Opens with a specific verb+resource ('Get one chat or channel message') and immediately scopes it to a single message, which cleanly separates it from list_* and search_messages siblings. An agent can identify the tool without opening the schema.

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

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

Explicitly states the two accepted addressing modes (Teams link vs. ids) and the exact id combinations for each, then names the alternative (list_chat_messages) and the precise before/after conditions under which to use it. When-to-use and how-to-alternate are both spelled out.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the prefix-only matching gotcha (surname or middle fragment finds nothing), the fields returned, and the limit behavior. It omits auth/permission requirements, but for a read lookup those are minor.

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, then the prefix-match caveat, then return/consumption details — a sensible ordering with no filler. The parenthetical Graph reference is slightly technical but 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?

An output schema exists, so return-value documentation is not strictly required, yet the description still adds useful field-level context. Combined with the matching semantics, it is essentially complete for calling the tool; only auth expectations are absent.

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 0%, so the description must compensate and largely does: it defines `query` as a prefix match over displayName/mail and describes `limit` as the cap on returned users. It does not restate the default (10) or any maximum, leaving a small gap.

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

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

States a specific verb+resource ('Find users') and immediately scopes it to display name or email prefix. It further distinguishes itself by naming the sibling tools that consume its output (get_user_presence, mention, create_chat), so an agent can place it in the workflow.

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 intended use case (resolving a user id or email for downstream calls) and names the consumers, which effectively signals when to reach for it. It does not state explicit when-not-to-use conditions or a named alternative lookup tool, 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the shape of the result (availability values such as Available, Busy, DoNotDisturb, Away, Offline and activity values such as InACall, InAMeeting, Presenting), which is genuinely useful. However, it says nothing about permission requirements, whether presence is live or cached, or latency/rate characteristics of polling awareness state.

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

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

Three short sentences: purpose first, return values second, ID sourcing last. Every sentence earns its place with no filler or restatement of the tool name.

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

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

For a single-required-parameter read tool with an output schema, the description covers purpose, result shape, and ID provenance, which is close to sufficient. The residual gap is the absence of any note about permissions or freshness of the presence data, which an agent might need for this class of call.

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 0%, so user_id is completely undocumented in the input schema, and the description must compensate. It partially does by naming the three sibling tools that yield a valid user_id, which is real semantic guidance beyond the schema, though it never describes the expected identifier format or whether other ID forms are accepted.

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 ('Get the presence/availability status of a user') and enumerates the two returned dimensions (availability and activity), so the agent knows this is a presence lookup rather than a profile lookup. It does not explicitly contrast itself with the sibling get_user, which also takes a user_id, leaving that differentiation to inference.

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 a concrete prerequisite — where to obtain user_id (list_team_members, list_chat_members, get_user) — which is actionable routing guidance. It never states when to prefer this tool over get_user or any alternative, so usage context is implied rather than explicit.

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

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

No annotations are present, so the description carries the burden, and it does disclose the read-only nature and the field set (id, display name, email, roles). However, it omits auth requirements, pagination behavior, and result-size limits, which matter for a potentially large member list.

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

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

Three short lines, front-loaded with the purpose, then output fields, then the prerequisite. The field enumeration is somewhat redundant with the existing output schema, costing it a point.

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?

Because an output schema exists, the description need not explain return values, so that line is a bonus rather than a necessity. The real remaining gaps are team_id semantics and pagination behavior on a list tool with no annotations to fall back on.

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 0%, so both required parameters need compensating detail. The description explains where channel_id comes from (list_channels) but says nothing about team_id or its relationship to the channel, leaving one of two parameters undocumented.

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 members of a specific channel"), and the scope word "channel" separates it from the sibling list_team_members and list_chat_members. It does not name those siblings explicitly, but the resource noun alone is enough to disambiguate.

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

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

Gives an actionable prerequisite — "Use list_channels to get the channel_id" — which is the main thing an agent needs before calling this tool. It stops short of stating when-not to use it versus list_team_members or list_chat_members.

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 full burden and does so: it discloses ordering semantics ('threads with the latest activity first'), the absence of pagination ('there is no cursor for older ones'), and content exclusions ('System messages are excluded'). It also names fields returned and points inline image ids at download_attachment, which is well beyond a bare restatement.

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 prerequisites, then behavioral caveats - a sensible order with no filler sentences. The middle return-fields sentence is dense and slightly sprawling, but each clause carries operational 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?

An output schema exists so return values need not be enumerated, yet the description still summarizes the shape usefully. Combined with the ordering, pagination and exclusion notes, nothing an agent needs to call this 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 0%, so the description must compensate, and it does for the key range constraint ('up to `limit` (1-200)') and for the provenance of team_id and channel_id via the discovery chain. It does not describe id formats or what happens if limit is omitted, leaving a small gap.

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

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

States a specific verb and resource ('List recent top-level messages in a Teams channel') and immediately constrains scope with the word 'top-level'. It cleanly distinguishes itself from siblings like list_thread_replies and list_chat_messages, which an agent can tell apart without opening the schemas.

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

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

Gives an explicit prerequisite chain ('Use list_teams -> list_channels to get team_id and channel_id') and an explicit exclusion with a routed alternative ('Replies are not included - read a thread with list_thread_replies'). Both when-to-use and when-not-to-use are covered.

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 provided, so the description carries the full behavioral burden. 'List' implies a safe read, and it names the returned fields, but it says nothing about pagination, permissions, or result limits for a lookup that could span many channels.

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

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

Three short sentences, each earning its place: purpose, prerequisite, and return shape, all front-loaded with no filler.

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

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

For a simple single-parameter list tool with an output schema, the definition covers purpose, prerequisite, and returns. The only gap is the absence of any note on pagination or result volume.

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 0% for the single parameter, so the description must compensate. It does by explaining that team_id comes from list_teams, which is genuinely useful provenance beyond what the bare 'Team Id' property conveys.

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 channels in a Microsoft Teams team'), scoping it to a team distinct from sibling tools like list_teams or list_channel_messages. An agent can determine what this returns without opening the schema.

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

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

Explicit prerequisite: 'Use list_teams first to get the team_id.' This tells the agent the correct order of operations. It lacks any when-not or alternative guidance, but the conditional 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It implies a read-only operation via 'List,' but does not state permissions, side effects, rate limits, or pagination behavior. The return fields mentioned are redundant given the output schema, so behavioral context is minimal.

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

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

The description is short, front-loaded with purpose, and well-structured. The middle sentence about return fields is redundant given the output schema, but the overall size is appropriate.

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 1-parameter list tool with an output schema, the description covers the purpose and parameter source. It neglects usage alternatives and behavioral details, but those gaps are minor given the tool's low complexity and the presence of an output schema.

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

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

With 0% schema description coverage, the description must compensate. It does partially by pointing to list_chats for obtaining the chat_id, which adds actionable meaning beyond the bare schema. However, it does not explain the chat_id format or constraints, so it only partially compensates.

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

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

The description states a specific verb and resource: 'List members of a chat.' It implies scope by naming 'chat' as opposed to team or channel, but does not explicitly name sibling tools like list_team_members or list_channel_members. A 4 for clear purpose without explicit sibling differentiation.

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 provides a concrete prerequisite: 'Use list_chats to get the chat_id,' which helps an agent source the required parameter. However, it gives no guidance on when to choose this tool over alternatives such as list_channel_members or list_team_members. Implied usage only, so 3.

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 full burden and delivers: pagination semantics, the newest-first pitfall (after alone returns newest, not messages after that time), system-message exclusion impacting page size, and timezone handling for offsetless timestamps. This is unusually rich behavioral disclosure.

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

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

Front-loaded with the core action and ordering, then pagination and edge cases. Every sentence carries actionable information; none is filler despite the density.

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 paged list tool with a 4-param schema, no annotations, and an output schema, the description covers invocation, pagination, edge cases, and timezone semantics. Nothing an agent needs 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 coverage is 0%, so the description must compensate, and it does: limit range (1-200), after/before are ISO 8601, optional, exclusive, and offsetless values read as UTC, and chat_id's source. Every parameter gains meaning beyond the bare schema.

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

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

States a specific verb ('List'), resource ('messages in a chat'), and ordering ('newest first, a page at a time'). An agent can immediately distinguish it from list_channel_messages by the chat scope and from get_message by the list/paging nature.

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 the agent to list_chats to obtain the chat_id, and clearly explains the pagination loop (call again with before=next_before). It does not explicitly contrast against siblings like search_messages or list_channel_messages, so it stops short of full alternative discrimination.

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 provided, so the description carries the full burden. It does disclose useful behavioral context: what the tool does not cover (channels) and what fields come back (chat id, topic, type, member names). However it leaves out auth expectations, pagination behavior, and what 'recent' actually means, which is a meaningful gap for an unannotated tool.

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

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

Three short, front-loaded lines with zero filler; the scoping constraint follows the core purpose. The 'Returns ...' sentence is slightly redundant against the existing output schema but not wasteful.

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?

Purpose, negative scope, and routing are complete, and return values need not be explained since an output schema exists. The only real gap is the undocumented 'limit' parameter, which is minor for a simple read tool.

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

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

Schema description coverage is 0% for the single 'limit' parameter, so the description must compensate and does not. 'Recent chats' loosely implies a bounded, default-limited result, but the meaning, allowed range, and effect of 'limit' are never stated.

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 recent chats') and immediately scopes it with participant names. The explicit exclusion of channel conversations further distinguishes it from siblings like list_channel_messages and list_teams, so an agent can identify it without opening the schema.

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

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

Names the excluded case ('Does NOT include channel conversations') and routes the agent to the correct alternative ('use list_teams + list_channels for those'). This is an explicit when-not plus named alternatives, the top of the scale.

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 full behavioral burden. It implies a read via 'List' but never states that it is non-mutating, whether it requires specific permissions, or any pagination/limit behavior. The only returned-value note overlaps with the existing output schema, so it adds little.

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

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

Three short, front-loaded sentences with no filler, and the purpose statement leads. The middle sentence about return content is partially redundant given the output schema, which keeps it 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 simple one-parameter read tool with an output schema documenting returns, the description covers purpose and parameter sourcing adequately. The missing piece is sibling-based usage guidance, which is not critical for 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?

Schema description coverage is 0%, so the description must compensate for the single required chat_id parameter. Telling the agent to obtain chat_id via list_chats adds real meaning beyond the schema, but format/validity details are left unspecified.

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 gives a specific verb and resource ('List pinned messages in a chat'), which is clearly distinct from the mutation siblings pin_message and unpin_message. It doesn't explicitly contrast itself with list_chat_messages or search_messages, but the scope is unambiguous.

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

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

It supplies one prerequisite pointer — 'Use list_chats to get the chat_id' — which is genuinely useful for obtaining the required parameter. However, there is no guidance on when to prefer this over siblings like list_chat_messages or search_messages, so usage is only 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 full behavioral burden. It discloses the return fields (member id, display name, email, roles), which is helpful, but it does not state that this is a read-only operation, nor does it mention pagination, rate limits, or authentication requirements. The added return detail is useful but incomplete.

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

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

Three short sentences that are front-loaded with the tool's purpose, then return values, then a prerequisite. Every sentence adds useful information with no waste.

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

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

For a simple single-parameter read tool with an output schema, the description is nearly complete: it states the purpose, the return fields, and how to obtain team_id. The only minor gap is lack of explicit guidance on when to choose this tool over similar member-listing tools.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by explaining how to obtain the required team_id ('Use list_teams to get the team_id'), which adds sourcing meaning beyond the bare schema. It does not describe the expected format of team_id, but the sourcing guidance is valuable.

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+resource: 'List members of a Microsoft Teams team.' It clearly distinguishes this from sibling tools like list_teams (which lists teams) and list_channel_members (which lists channel members) because the resource scope is explicit.

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 useful prerequisite ('Use list_teams to get the team_id'), but it does not explain when to prefer this tool over alternatives such as list_channel_members or list_chat_members. Usage is implied by the resource scope, but explicit when/when-not guidance is absent.

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 provided, so the description carries the behavioral burden; 'List' implies a read-only operation and 'you are a member of' hints at authorization scope. However, it says nothing about pagination, result size, ordering, or whether the listing is complete, which are real gaps for a zero-param enumeration call.

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

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

Three short lines, front-loaded with what the tool does, followed by the return fields and the follow-up routing hint. Nothing is padding, though the return-field sentence is mildly redundant given the output schema exists.

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

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

For a zero-parameter list tool with an output schema that already defines the return fields, the description supplies the essential scope and a follow-up path, so it is nearly complete. Only pagination and completeness behavior 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 tool takes no parameters, so there is no parameter semantics to document and the baseline of 4 applies. The mention of team_id in the description correctly describes a value returned for use elsewhere rather than an input.

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 gives a specific verb and resource ('List all Microsoft Teams') plus a scoping condition ('you are a member of'), which tells an agent exactly what set is returned. It does not explicitly contrast with sibling list tools such as list_chats or list_team_members, so it stops short of full sibling differentiation.

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 only guidance is the follow-up hint 'Use a team_id with list_channels to see its channels,' which describes a next step rather than when to choose this tool over alternatives. Usage is implied by 'Teams you are a member of' but no exclusions or preconditions are stated.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the TeamworkTag.Read permission requirement, the phantom-tag failure mode in shared channels, the Graph API limitation, and a concrete workaround for shared channels.

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 important output/scope context is front-loaded, and each sentence adds distinct value about permissions or channel behavior. It is somewhat dense but not padded.

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?

An output schema exists, so return-value details need not be explained. The description covers permissions, channel compatibility, and alternatives; only the team_id parameter's expected format or source is left undocumented.

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

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

Schema description coverage is 0% for the single team_id parameter, and the description adds no format, source, or constraint details for it beyond saying tags belong to a team. It does not compensate for the schema's lack of 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 states a specific verb and resource: listing TEAM-level tags of a team. It clearly distinguishes team-level tags from channel-scoped shared-channel tags, which is the key conceptual distinction an agent must understand.

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 covers when the tool's ids are valid (STANDARD channels) and provides an alternative path for shared channels (reuse the tag id from mentions of an existing message). It also states the required delegated permission, leaving little 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?

No annotations are provided, so the description carries the full burden and does so well: it discloses ordering ('newest first'), the inclusion of the parent message, the hard cap on replies, system-message exclusion, and — critically — a silent truncation behavior where the oldest replies are dropped with no marker. That silent-data-loss disclosure is exactly the kind of trait an agent cannot learn from the schema.

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

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

Four short sentences, each earning its place: purpose first, then prerequisite, then return shape, then the truncation caveat. No filler and no restatement of the tool name.

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

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

An output schema exists, so return values need not be spelled out, yet the description still conveys the useful structure (parent first, then replies) and the truncation edge case. It stops short of telling the agent how to recover the omitted oldest replies or what permissions the call requires, which are the only meaningful remaining gaps.

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

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

Schema description coverage is 0%, so the description must compensate; it clarifies that message_id must be a top-level parent message (retrieved via list_channel_messages) and gives the valid limit range (1-200) plus its default. team_id and channel_id are left to their self-evident names, which is a minor but real gap at zero 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?

States a specific verb and resource ('List replies in a channel message thread') and explicitly scopes to threads versus the general channel message listing handled by list_channel_messages. An agent can distinguish it from every sibling that deals with messages 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?

Names the prerequisite and the alternative path directly: 'Use list_channel_messages to get the parent message_id (a top-level message).' The condition that selects this tool (you have a parent message and want its replies) is made explicit rather than inferred.

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 provided, so the description carries the full disclosure burden. It states the basic effect ('as read for the current user') but says nothing about idempotency, whether it triggers read receipts/notifications for other participants, or permission requirements for a mutation tool.

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

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

Two short sentences with the core action front-loaded and no filler. Efficient and readable, though extremely minimal.

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

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

An output schema exists so return values needn't be described, and the single parameter's origin is covered. Still, for a mutation tool with zero annotations, the absence of any behavioral detail (side effects, idempotency) 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 description coverage is 0%, so the description must compensate. It names the parameter and its source ('Use list_chats to get the chat_id'), which adds real value, but it gives no format or constraints for the chat_id value.

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

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

The description states a specific verb and resource ('Mark a chat as read') scoped to the current user, which is unambiguous about what the tool does. It does not explicitly differentiate from the sibling mark_chat_unread, but the purpose itself is 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?

It gives a workflow hint ('Use list_chats to get the chat_id') that helps the agent supply the required parameter. However, there is no guidance on when to use this versus alternatives like mark_chat_unread or under what conditions marking read 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?

No annotations are supplied, so the description carries the full burden. It does disclose the meaningful behavioral rule for the timestamp (messages after it appear unread), which is real value, but says nothing about permissions, whether this is reversible, or side effects on notification state.

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 action is front-loaded in one short sentence, followed by a focused explanation of the one non-obvious parameter. No filler, though the trailing 'Messages after this timestamp will appear as unread' slightly restates the preceding clause.

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

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

An output schema exists, so return values need not be described. However, for a mutation tool with no annotations, the description omits any mention of required permissions, reversibility, or effect on unread counts, leaving the agent short of 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 0%, so the description must compensate, and it does for last_message_read_date_time by stating the ISO 8601 format, giving a concrete example, and explaining the semantic cutoff. chat_id is left unexplained, but its meaning is unambiguous from the tool name.

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 (mark) plus resource (chat) and scope (unread, for the current user), which is immediately actionable. It does not name the obvious sibling mark_chat_read or contrast the two, so sibling differentiation is left implicit.

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?

There is no when-to-use or when-not-to-use guidance, and the sibling list contains mark_chat_read, the natural alternative for the inverse operation. The agent must infer the read/unread relationship entirely on its own.

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 provided, so the description carries the full disclosure burden. It does add one genuine behavioral fact beyond the schema (chat-only applicability), but omits permission requirements, idempotency when the message is already pinned, pin-count limits, and whether pinning is visible to all members.

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, zero filler, with the core action statement front-loaded ahead of the scope caveat and the sourcing hint.

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?

An output schema exists, so return values need no explanation here. For a mutation with two required params and no annotations, however, the description leaves pin-specific semantics (already-pinned behavior, per-chat pin limits, permission errors) unstated.

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 0%, so the description must compensate. It usefully explains where message_id comes from (list_chat_messages), which the schema does not, but chat_id is left entirely unexplained.

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

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

States a specific verb (pin) and resource (message) plus an explicit scope constraint: chats only, never channels. That constraint alone separates it from channel-oriented siblings like send_channel_message and list_channel_messages.

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

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

Gives a clear when/when-not rule ('Only works in chats, not channels') and routes the agent to list_chat_messages to obtain the message_id. It stops short of naming unpin_message as the inverse operation or stating any other precondition.

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 full burden and discloses real behaviors: content is plain text (newlines kept, URLs linkified, Markdown/HTML rendered literally) and a mention whose '@<name>' does not exactly match is silently dropped without error. It still omits permission requirements and any rate-limit or error semantics, 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 action and alternatives in the first lines, then sections the content and mentions semantics. Multi-line but every clause carries information; slightly longer than strictly necessary for a routing statement.

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?

An output schema exists, so return values need not be described, and the description fills the two behavioral gaps the annotations and schema leave open (content rendering and mention matching). Only mutation-side concerns like required permissions remain unstated.

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 0%, so the description must compensate: it fully documents the two non-obvious parameters, spelling out plain-text rendering rules for content and an otherwise opaque mention format ({"user_id","name"} or {"tag_id","name"}) plus where to get tag_id. The three ID parameters (team_id, channel_id, message_id) are left implicitly documented only by their names.

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 ('Reply to a message in a Teams channel thread'), which unambiguously separates it from send_channel_message (new top-level) and send_chat_message. An agent can pick it correctly without opening any schema.

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

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

Explicitly routes the agent: use list_channel_messages to obtain message_id, and use send_channel_message for new top-level messages instead. It also names list_team_tags as the source of tag_id, covering when-to-use and the closest 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?

With no annotations, the description carries the full burden and delivers: results are capped at `size`, newest first, with no further pages (a real pagination limitation), hits contain a snippet rather than the full body, and ids are absent. These are non-obvious behavioral facts that materially change how an agent should call 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?

Front-loads purpose, then behaviors, then the routing caveat in a logical order with no filler sentences. Dense and well-organized, though the enumerated return fields are borderline redundant given an output schema exists.

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 two-parameter search tool with no annotations, it covers scope, matching behavior, result cap and ordering, snippet-vs-body, and the missing-id consequence. An agent has everything needed to call it correctly and to know when not to.

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 0%, so the description must compensate and only partially does: it clarifies that `size` caps the number of hits and that `query` matches message content including attachments. It gives no search syntax or operators, so the query param's effective semantics remain partly undefined.

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 (Teams messages) and delimits scope to 'all chats and channels the signed-in user can see'. It also actively distinguishes itself from list_chat_messages and list_channel_messages, so an agent can route between search-style discovery and list-style retrieval without opening schemas.

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

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

Gives explicit routing guidance: message ids are not returned, so to reply/react/delete a hit the agent must use list_chat_messages or list_channel_messages. This names the alternatives and the exact condition that selects them, which is precisely the when/when-not signal an agent needs.

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 full burden and does well: it discloses that content is plain text with newlines preserved and URLs auto-linked, that Markdown/HTML render literally, and that a mention whose '@<name>' doesn't match 'name' is silently dropped with no error. It doesn't cover permission requirements, rate limits, or rate of delivery, so it falls 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?

Front-loads the core action, then the prerequisites and the sibling exclusion, then parameter detail. Dense but every line serves a purpose; the multi-line formatting is functional rather than padding, though slightly longer than strictly necessary.

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?

An output schema exists so return values need not be explained, and the description covers prerequisites, the reply alternative, content rendering semantics, and the mentions contract including the silent-failure mode. Missing only auth/permission and error-handling context for a mutation tool.

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

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

Schema coverage is 0%, yet the description compensates fully: it explains where team_id/channel_id come from, gives the exact mentions JSON shape ([{"user_id","name"} | {"tag_id","name"}]), points to list_team_members/get_user for user_id and list_team_tags for tag_id, and defines the content-side '@DisplayName' contract.

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 ('Send a message to a Teams channel'), and immediately distinguishes itself from the reply tool. An agent can differentiate it from send_chat_message and reply_to_channel_message without inspecting schemas.

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

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

Provides explicit prerequisites ('Use list_teams -> list_channels to get team_id and channel_id') and names the alternative for the reply case ('use reply_to_channel_message instead'). Both when-to-use and when-not-to-use are covered.

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 full burden and does so: Markdown/HTML render literally, newlines are kept, URLs become links, mentions are silently dropped if '@<name>' does not match, and team tags cannot be mentioned in chats. These failure modes and rendering behaviors are exactly what an agent needs before calling.

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, then organized into prerequisite lookups, content semantics, and mentions. Every line earns its place, though the multi-block layout is slightly denser than a single tight paragraph would be.

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?

An output schema exists so return values need not be described, and the description covers all inputs, required lookups, mention syntax, and rendering/error behavior. Nothing needed to invoke this 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 0% and all four parameters are documented in prose: chat_id source, content text semantics, reply_to as an optional quoted-reply message ID, and mentions as a JSON array with the exact shape [{"user_id":..., "name":...}] plus where the '@DisplayName' token goes in content. Fully compensates for the empty schema.

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

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

States a specific verb and resource (send a message to a Teams chat), which is enough to separate it from send_channel_message and reply_to_channel_message by the chat/channel distinction. It does not explicitly name those siblings, but the resource noun does the discriminating work.

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 the agent to list_chats for chat_id, list_chat_messages for reply_to's message_id, and list_chat_members/get_user for mention user_ids. Prerequisite lookups are well covered, though there is no statement of when not to use this tool (e.g. channels vs chats) beyond the resource name.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the scope constraint (thread replies unsupported, addressed under the parent message), which is valuable negative-space context, but says nothing about permission requirements, whether re-reacting is idempotent or errors, or how duplicate/existing reactions behave.

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 purpose followed by context-specific parameter routing, a constraint, and value examples. Every line earns its place and the structure mirrors the branching logic of the tool.

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

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

An output schema exists, so return values need no explanation, and the required-parameter routing is fully covered. The only gap is behavioral context (permissions, duplicate-reaction handling) that a no-annotation tool ideally supplies.

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 0%, so the description must compensate — and it does: it maps the ID parameters to channel vs chat contexts and documents the reaction value space (the six common reactions plus arbitrary unicode emoji). It stops short of clarifying team_id/channel_id individually, but the pairing guidance is the essential semantics.

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

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

States a specific verb+resource ('React to a message with an emoji') that is unambiguous and clearly distinct from siblings like unset_reaction, send_channel_message, and get_message. An agent can identify the operation without opening the schema.

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

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

Explicitly routes the caller by context: 'For channel messages: provide team_id + channel_id + message_id' vs 'For chat messages: provide chat_id + message_id'. It also names an exclusion — channel thread replies are not supported — which is exactly the when-not guidance an agent needs.

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 provided, so the description carries the full behavioral burden. It usefully discloses the ID-acquisition dependency and the ID-type pitfall, but says nothing about required permissions, error behavior for an unpinned message, or reversibility via pin_message. For a mutation tool with no annotation coverage that leaves real gaps.

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 short sentences, purpose front-loaded before the caveat, and every clause earns its place by either stating the action or preventing a likely calling error.

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?

An output schema exists, so return values need no explanation, and the description covers the critical calling pitfall. What is missing is only peripheral: permission/error behavior and confirmation of what unpinning does to the pin list.

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 0%, so the description must compensate. It explains the non-obvious parameter (pinned_message_info_id, sourced from list_pinned_messages, explicitly NOT the message_id), which is exactly the trap an agent would fall into. chat_id is left undocumented, but its meaning is self-evident.

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 ("Unpin a message from a chat"), so the operation is unambiguous. It implicitly distinguishes itself from message_id-based siblings by warning against passing a message_id, but it never names pin_message, the tool that reverses it, so sibling differentiation is partial.

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

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

Gives an explicit prerequisite: call list_pinned_messages first to obtain the pinned_message_info_id. That is actionable sequencing guidance rather than vague context. It stops short of stating when not to use this tool or what happens when the message isn't currently pinned.

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 and does disclose a genuinely non-obvious constraint: thread replies are unsupported because Graph addresses them under the parent message. It does not cover permissions, idempotency when the reaction is absent, or error behavior, so gaps remain.

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 is front-loaded in one short sentence, followed by compact routing rules and a scope caveat. Every sentence earns its place, with only mild redundancy between the chat-routing line and the scope sentence.

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?

An output schema exists so return values need no explanation, and the routing plus thread-reply exclusion cover the main ambiguity for a 5-parameter tool. The missing reaction-format detail and absence of any permission/idempotency note leave a small but real gap.

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 0%, so the description must compensate, and it does explain the conditional required combinations of team_id/channel_id/chat_id/message_id. However it never describes the required 'reaction' parameter's expected format (emoji, name, unicode), which is the single most error-prone input.

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 ('Remove a reaction from a message'), and the removal semantics are inherently distinguished from the sibling set_reaction. An agent can identify the tool without opening the schema.

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

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

Gives explicit conditional routing (channel messages need team_id + channel_id + message_id; chat messages need chat_id + message_id) and a clear exclusion (channel thread replies not supported). It stops short of naming the complementary sibling set_reaction or stating prerequisites, so it is strong but not exhaustive.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses that the whole body is replaced with plain text, that @mentions cannot be added and existing ones are flattened to plain text, and that the tool is only available in Global cloud (not GCC/DOD). These are non-obvious behavioral constraints an agent could not infer from the schema.

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

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

Front-loaded with the one-line purpose, then conditional parameter guidance, then caveats, all in a compact block. Every sentence adds distinct routing or constraint information with no waste.

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

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

An output schema exists, so return values need no explanation, and the description covers the remaining gaps: authentication-relevant deployment scope, message-type applicability, and content semantics. Nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate – and it does, mapping parameter combinations to the channel-vs-chat scenario and clarifying that content is plain text. It stops short of describing edge cases such as empty or oversized content, so it is not fully exhaustive.

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

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

The description opens with a specific verb+resource ('Edit a message you sent'), and the scope is narrowed against siblings by stating it works on top-level channel messages and chat messages but not thread replies. An agent can distinguish this from send_channel_message, delete_message, or reply_to_channel_message immediately.

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

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

It gives explicit conditional routing: team_id + channel_id + message_id for channel messages, chat_id + message_id for chat messages. It also states exclusions (thread replies unsupported), though it does not explicitly name the alternative tool to use for that case.

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