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

Annotations already declare readOnly/idempotent/openWorld, so the description's job is to add context — and it does, disclosing the two-tier resolution behavior and the membership constraint on name-only lookups. It leaves unstated what happens when multiple channels match a name or when no arguments are supplied, which is the main behavioral gap.

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 paragraphs, resolution strategy front-loaded before the return shape, with a concrete slug example. No filler sentences.

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

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

Safety profile comes from annotations and the return shape is already declared by the output schema, so the description is not obliged to enumerate return fields — the listed keys are mild redundancy. The definition is broadly complete, but the edge cases of argument precedence and empty-input behavior are absent for a tool where every parameter is optional.

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 none of the four parameters are described in the schema, so the description must carry the load. It defines name as the URL slug and explains the role of team_id/team_name in scoping, but says nothing about precedence (e.g. channel_id vs. name both supplied), mutual exclusivity of team_id/team_name, or the all-null case — meaningful omission given zero required parameters.

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 (look up) and resource (channel) plus both resolution keys (ID or name/URL slug). The scope distinction — membership-only search by name alone vs. team-wide lookup with team_id/team_name — makes it unmistakable versus siblings like list_channels or get_channel_posts.

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 usage: pass channel_id, or name; with name alone only member channels are searched, and team_id/team_name widens it to any channel. It does not name an alternative tool or say when to prefer list_channels over this lookup, so it stops short of full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered elsewhere. The description adds the sort order (newest first), which is genuinely useful for an agent consuming the results, but says nothing about pagination depth, rate limits, or what happens when the channel is empty.

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?

One sentence, front-loaded with the verb and resource, with the ordering constraint appended. Nothing is wasted and nothing needs trimming.

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 input schema is fully documented. The only residual gap is that the description does not allude to paging back through history via the 'before' parameter, which is the tool's main non-obvious affordance.

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

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

Schema description coverage is 100%, and the schema already documents limit, since, before, and channel_id in detail, including pagination semantics. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get recent posts from a Mattermost channel') plus the ordering ('newest first'), which implicitly separates it from get_thread, get_pinned_posts, and search_posts in the sibling list. It stops short of naming those alternatives explicitly, so it is clear but not fully 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 word 'recent' hints at the intended use case, but there is no explicit guidance on when to reach for this versus search_posts, get_pinned_posts, or get_thread, and no stated exclusions or prerequisites.

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

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

Annotations already establish readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds one genuine behavioral trait — results are returned newest first — but says nothing about pagination behavior, result caps, or permission requirements for reading another user's DMs.

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?

A single front-loaded sentence with zero filler, and the ordering guarantee is placed where it matters. It is efficient but so terse that it leaves obvious gaps unaddressed.

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 annotations cover the safety profile; schema coverage is complete. What is missing is minor context such as whether group conversations are included and how to page back through history in practice.

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

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

With 100% schema description coverage, every parameter already carries its own documentation, including the default limit of 30 and the ISO 8601 format for since. The description adds no parameter-level meaning beyond the implicit ordering caveat, so the baseline 3 applies.

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

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

The description states a specific verb and resource (get direct message history) and narrows scope to a specific user, which separates it from channel-oriented siblings like get_channel_posts or get_thread. It stops short of naming an alternative tool explicitly, so differentiation has to be inferred from the sibling list.

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

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

Usage is only implied: needing a username suggests a one-to-one conversation, but the description never says when to prefer this over get_channel_posts, get_mentions, or search_posts, and gives no exclusions or prerequisites.

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

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

Annotations already declare readOnly, idempotent, and openWorld behavior. The description adds important scope beyond that: it returns metadata only and does not download content, which prevents a common misuse. It does not describe error handling or permission requirements, but the core behavioral boundary is disclosed.

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, front-loaded with the core action and immediately followed by the key limitation. Every phrase earns its place, with no redundant restatement of the tool name or schema.

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

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

For a one-parameter read-only tool with an output schema and full annotation coverage, the description supplies everything needed to select and call the tool correctly: what it returns (metadata), what it does not return (content), and where the ID originates.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by indicating where to obtain the file_id (a post's file_ids), which is genuinely useful context for constructing the call.

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 metadata of a file') and clarifies scope by tying the file to a post via file_ids. It does not explicitly differentiate from a sibling, but no sibling tool handles file metadata, so the ambiguity is low.

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

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

It gives clear context for use (retrieving file metadata) and a useful negative constraint ('The file content is not downloaded'), which steers agents away from expecting bytes. It stops short of describing when to use an alternative or any prerequisites, but no direct alternative exists.

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

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

Annotations already establish that this is a safe, idempotent read. The description adds useful behavioral context by explaining auth_mode values and what write_enabled means for posting/editing tools.

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

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

Front-loads the core purpose and then provides a compact, relevant return-field summary. No sentence is wasted.

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?

Annotations cover safety and idempotency, and an output schema exists, so the description does not need to carry the full return-value burden. It is still complete enough for an agent to know what this call provides and how to interpret auth_mode and write_enabled.

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

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

The tool takes zero parameters, so parameter semantics meet the baseline. No additional parameter guidance 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?

States a specific verb and resource: get the authenticated user plus server permissions. The word "authenticated" distinguishes it from get_user and search_users, though it does not explicitly name those siblings.

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

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

Usage is implied: call it to identify the current user and learn whether write tools are available. It does not explicitly say when to prefer it over get_user or how to use auth_mode operationally.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description goes beyond them by explaining a non-obvious behavioral rule: muted channels are still included by default because mute only suppresses unread badges, and include_muted=False changes that. Return format and pagination are left unstated, but an output schema exists to cover 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?

Two short sentences: the resource and ordering come first, then the only non-obvious caveat. No restatement of the tool name, 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 annotations, a full-coverage schema, and an output schema, the description only needed to add the non-obvious behavioral caveat, which it does. It stops short of noting result-shape or cursoring behavior, but the output schema and limit parameter make that low-risk.

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 limit and since are already fully documented and baseline would be 3. The description earns above baseline by explaining the semantics behind include_muted — what muting actually does and why the default is True — which the schema description alone does not convey.

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 ('Get') and resource ('posts that mention the authenticated user') with scope and ordering ('newest first'), so an agent can distinguish it from get_channel_posts or search_posts. It does not explicitly name the sibling it displaces, which keeps it short of a 5.

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

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

Usage is implied by the mentions-feed framing rather than stated: there is no explicit 'use this instead of search_posts when…' guidance and no prerequisites (e.g. auth requirements) mentioned. The muted-channel note is a usage nuance for one parameter, not a when-to-use rule.

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, idempotentHint, and openWorldHint, so the safety profile is covered elsewhere. The description adds nothing beyond that — no note on whether an empty list is returned when nothing is pinned, whether the channel must be public, or how pinned items are ordered.

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?

One short sentence with the scope qualifier front-loaded and zero wasted words. It is appropriately sized for a simple getter, though it is so terse that nothing is structured beyond the single 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 and annotations cover the safety profile, so the essentials for invoking the tool are present. Still, a minimal description like this leaves the agent without ordering, pagination, or empty-result expectations for a read that could return an unbounded 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?

With a single required parameter at 100% schema coverage, the schema fully documents channel_id and the description adds no meaning on top of it. Baseline 3 applies since the schema carries the parameter burden.

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

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

The description states a specific verb and resource ('Get the posts') with the qualifying scope 'pinned in a channel', which inherently separates it from get_channel_posts. It stops short of explicitly naming that sibling, so an agent must infer that the unpinned variant lives elsewhere.

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 statement of when to use this versus get_channel_posts, get_post, or search_posts, and no prerequisites or exclusions. The only guidance is implicit in the word '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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety and idempotency profile is fully covered externally. The description adds no behavioral context beyond that (no note on what happens with missing/deleted IDs or access restrictions), so it neither helps nor contradicts.

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?

One short, front-loaded sentence with zero waste and the identifier is stated immediately. It is appropriately sized, though it could have spent a clause on disambiguation at no real cost.

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 with one required parameter and an output schema, so return-value explanation is unnecessary. However, given many overlapping read siblings (get_thread, get_channel_posts, search_posts, get_pinned_posts), the description is not complete enough to route the agent confidently.

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

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

Schema description coverage is 100% and the single post_id parameter is documented in the schema, so the description's restatement of 'by ID' adds nothing new. Baseline 3 applies when the schema does the heavy lifting.

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

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

Specific verb+resource: 'Get a single post by ID' clearly states retrieving one post identified by ID. It does not differentiate from siblings like get_thread, get_channel_posts, or search_posts, which an agent must distinguish when deciding between single-post retrieval and thread/channel listing.

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

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

No guidance on when to use this versus alternatives such as search_posts or get_thread. The only implied usage is 'you have a post ID,' which is left for the agent to infer.

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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds the useful scope detail that replies are returned alongside the root post, but says nothing about ordering, pagination, or reply depth, and an output schema covers return shape.

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

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

One short sentence, front-loaded with the verb and resource and free of filler. It is arguably too terse rather than too long — nothing is wasted, but little is added.

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 with an output schema and full annotations, this is close to sufficient. Still, it omits reply depth/ordering and whether the ID must be a root post, leaving minor gaps an agent might hit on real calls.

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?

There is a single parameter fully documented at 100% schema coverage, so the schema does the heavy lifting. The description adds no meaning beyond it, such as whether post_id may be a reply ID rather than a root ID — which the schema hint calls 'root post ID' but the description does not echo or clarify.

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 clear verb ('Get') and resource ('a post and all its replies'), with the scope ('all its replies') indicating how it differs from the sibling get_post. It never names get_post explicitly, so differentiation is inferred rather than stated.

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/when-not guidance and no reference to alternatives such as get_post or get_channel_posts. The agent must infer that this is the tool for whole-conversation retrieval rather than a single post.

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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: the default result is silently filtered to exclude sidebar-muted channels, and the filter mirrors the client unread badge. That hidden default is exactly the kind of thing an agent could otherwise misreport, though result shape/pagination is not discussed (and the output schema covers 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?

Two short paragraphs, front-loaded with the core capability before the default-behavior caveat. No filler or redundancy; the only small weakness is that the muted-override sentence could be tightened further.

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 description does not need to explain return values, and both optional parameters are covered by the schema. For a two-param read-only aggregate tool, the only meaningful gap is the absence of sibling routing guidance for when an agent should prefer get_mentions.

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

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

Schema description coverage is 100%, so both parameters are already documented in structured form, and the description largely restates the include_muted default. It adds a conceptual anchor (this skip matches the client unread badge) that gives the parameter meaning beyond its literal wording, but says nothing about the category filter (e.g. what happens on a non-matching category). 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?

"Get unread counts and mention badges per channel" names a specific verb and resource with an explicit aggregation scope (per channel). The scope wording implicitly separates it from get_channel_posts or list_channels, but it never names a sibling to distinguish from, so it stops just short of a 5.

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

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

The description gives genuine usage context for the muted-channel case (default skips muted, pass include_muted=True to see everything) and anchors the behavior to the client's unread badge. It gives no guidance on when to reach for this versus get_mentions or search_posts when an agent actually wants individual mention items, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds no behavioral context of its own — nothing about what happens when the username does not exist or whether the lookup is case-sensitive — but with annotations and an output schema in place this is only a modest gap.

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?

One short sentence, front-loaded with the verb and resource, with zero filler. It is efficient, though its terseness is part of why usage and behavioral guidance are thin.

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?

This is a simple one-parameter lookup with full schema coverage, rich annotations and an output schema that explains the return shape. Nothing essential for invoking it correctly is missing, though a note on not-found behavior would round it out.

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

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

Schema description coverage is 100% and the single parameter already documents the 'without @' format, so the schema carries the semantics. The description only restates that lookup is keyed on username and adds no format or edge-case detail 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?

States a specific verb and resource ('Get a Mattermost user's profile') and narrows it with 'by username', which implicitly separates it from the sibling search_users. It stops short of explicitly naming that alternative, so it is clear but not fully 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?

'By username' implies an exact-match lookup rather than a fuzzy search, which hints at when to use it over search_users. However, no alternative is named and there is no statement about when this tool is inappropriate or what to do if the exact username is unknown.

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, idempotentHint and openWorldHint, so the safety profile is covered. The description adds one real behavioral fact — results are limited to the user's memberships, not all server channels — but says nothing about result volume, ordering, or pagination behavior for a list tool over a potentially large workspace.

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?

A single front-loaded sentence with no filler or redundant restatement of the title. Nothing to trim.

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 annotations cover the safety profile. However, for a 4-parameter filtered list tool the description says 'all channels' without signaling the filtering surface, which risks an agent treating it as an unfiltered dump and pulling DMs/category-restricted results unexpectedly.

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 team_id, category, include_dm and include_muted are all documented in structured data; baseline 3 applies. The description adds no parameter context at all — notably it never hints that the list is filterable by team or sidebar category, nor that DMs are included by default.

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

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

States a specific verb (list) and resource (Mattermost channels) plus a meaningful scope qualifier: only channels the authenticated user is a member of. It does not distinguish itself from siblings like list_teams or get_direct_messages, which is the only thing keeping it from a 5.

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

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

There is no when-to-use guidance, no mention of alternatives (get_channel for a single channel, get_direct_messages for DMs, list_teams for teams), and no note that this is the entry point for discovering channels before calling get_channel_posts. Usage is only inferable from the verb.

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, idempotentHint, and openWorldHint, so the safety and repeatability profile is covered elsewhere. The description adds the meaningful behavioral detail that results are scoped to the authenticated user's membership, but says nothing about pagination, ordering, or result size limits.

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 purpose front-loaded and the return shape second. Nothing is wasted and no sentence needs to be re-read.

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, read-only list tool with full annotations and an output schema, the description covers scope and nothing essential is missing. The return-shape sentence partly duplicates the output schema, but as a quick hint it is harmless rather than misleading.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly avoids inventing filtering options that the empty schema does not support.

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 the teams') plus the scope ('the authenticated user belongs to'), which is enough to distinguish it from siblings like list_channels or search_users. It stops short of naming any sibling, but none of the siblings list teams, so disambiguation is largely inherent.

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

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

The description implies its use case (discovering teams available to the current user), but never says when to call it versus alternatives or what prerequisites exist. With no directly competing tool among the siblings, the implied usage is adequate 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?

Annotations already declare readOnly, idempotent, and open-world behavior, so the safety profile is covered. The description adds meaningful traits beyond that: result ordering is newest-first and muted channels are silently excluded by default, which is a subtle omission an agent would otherwise miss. Return format is covered by the output 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?

Two short paragraphs, zero filler. The core operation is front-loaded in the first sentence and the syntax guidance follows as a compact parenthetical.

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

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

Covers operation, ordering, syntax, and the muted-channel caveat, with parameters and return shape handled by schema and output schema. What remains unstated is how limit interacts with ordering and whether pagination is available, a minor gap for a search tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns more by documenting the query parameter's supported search syntax (from:, in:, before:/after:/on:, quoted phrases, negation) and by restating the include_muted default — real semantic value the schema's "Search terms" text does not provide.

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 ("Full-text search across Mattermost posts") plus result ordering ("newest first"). This clearly separates it from get_channel_posts, get_pinned_posts, and search_users, which are scoped or resource-specific.

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 usage condition: default searching excludes muted channels, and include_muted=True widens scope. It does not explicitly contrast with siblings like get_channel_posts for single-channel retrieval or get_mentions for directed messages, so routing is partly left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering the safety profile. The description adds the useful detail that matching spans username, full name, nickname, or email prefix, but does not mention result ordering, matching semantics, rate limits, or partial-match 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?

A single, front-loaded sentence with no wasted words. It communicates the core capability and searchable fields immediately.

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 has detailed annotations, 100% schema coverage, and an output schema, so the description needn't explain return values. It is nearly complete for a search tool, though it could say more about when to prefer this over exact user lookup.

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 already 100%, so the baseline is 3, but the description adds real meaning by explaining that the 'term' parameter searches across username, full name, nickname, and email prefix. That goes beyond the schema's generic 'Text to search for' description and helps the agent construct better queries.

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 ('Find') and resource ('users') and lists the searchable fields, so the agent knows exactly what the tool does. It does not explicitly differentiate itself from siblings like get_user or search_posts, which keeps it from a 5.

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

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

The description states what the tool does but gives no guidance on when to use it versus alternatives such as get_user for exact lookup or search_posts for post content. It leaves the agent to infer usage entirely from the capability statement.

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