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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavioral context beyond that: membership-gated visibility and the chat:write.public exception for posting. It doesn't describe pagination or return shape, but with annotations present a 4 fits.

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

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

Three tight sentences, no waste, with the core scope front-loaded before the visibility caveats.

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

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

No output schema exists, but the description covers the key semantic an agent needs: which channels appear and what membership means. It could say more about returned fields or pagination, but it is adequate for a filtered list 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 schema documents limit, query, types, and member_only. The description adds meaning around membership gating but references 'is_member', which is not a parameter name (the parameter is member_only) – this could confuse an agent mapping it to input. Baseline 3 for full schema 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?

Uses a specific verb (List) and resource (channels) with an explicit scope: 'channels the bot can see'. The optional name filter is stated. It doesn't explicitly differentiate itself from siblings like conversations_history, but the resource is distinct enough to route correctly.

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

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

Gives clear context on visibility: private channels and DMs appear only if the bot is a member, and explains the is_member=false implication. It stops short of naming alternatives or stating exclusions ('use X instead'), which keeps it from a 5.

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

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

Beyond the annotations, it discloses that answered questions are removed from the pending list and that earlier-session pending questions are included. It does not describe authorization needs or rate limits, but the key mutation of pending state is explained.

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

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

The description is front-loaded with the core behavior, then covers mode selection and usage advice without filler. The parenthetical about pending-question sources earns its place by explaining the tool's state model.

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?

It covers behavior, modes, side effects, and long-wait workflow, which is strong for a tool with four optional parameters and full schema coverage. Because there is no output schema and the description does not explain the return shape, a minor completeness gap remains.

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

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

Schema description coverage is 100%, so the schema already documents channel, since_ts, thread_ts, and dismiss. The description adds mode-level context for no-argument versus channel/since_ts usage, but it does not add parameter details beyond the schema, making 3 the appropriate baseline.

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

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

The description states a specific verb and resource: checking once, without waiting, whether people answered the bot. It also distinguishes the all-pending mode from the single-conversation mode, so an agent can identify the tool's role 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 clear usage context: no arguments checks all pending questions, channel plus since_ts checks one conversation, and it is cheap to call for long waits via scheduled or looped runs. It does not explicitly route the agent to wait_for_reply as the blocking alternative, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds real behavioral context – result ordering (newest first), pagination direction, and the fact that thread replies are omitted. It stops short of mentioning rate limits or any auth scope quirks, so not 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?

Three short sentences, front-loaded with what it returns and the ordering, then paging, then the exclusion. Every clause carries information an agent would otherwise have to guess.

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 covering the read-only/open-world profile and the schema covering all six parameters, this description covers what remains: result scope, ordering, pagination mechanics, and thread exclusion. No output schema exists, so no return-shape explanation is owed.

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 every parameter including limit, latest, oldest, and include_activity is already documented. The description only reinforces `channel` (repeating the schema's own wording) and adds a bit on `cursor`; it does not explain the relative/ISO time formats that make oldest/latest non-obvious.

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

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

States a specific verb and resource ('Read recent messages from a channel or DM'), plus ordering ('newest first') and the DM/channel scope. It explicitly sets itself apart from conversations_replies, so an agent can distinguish it without opening either schema.

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

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

Gives both the paging procedure ('use `cursor` from the previous response to page further back') and the exclusion rule with a named alternative ('Thread replies are not included; use conversations_replies for those'). The condition that selects the sibling is explicit, not 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description then adds real behavioral detail the annotations don't: results are ordered oldest first and the parent message is included in the result set. It stays silent on pagination behavior (limit default 50, max 200) and on whether you must page through large threads, which is the remaining 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 sentences, zero waste, with the ordering-and-parent guarantee front-loaded before the parameter note. Nothing is repeated from the schema or annotations.

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

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

For a 4-parameter read tool with full schema coverage and covered safety annotations, this is close to complete: result ordering and parent inclusion are stated. The remaining omission is pagination guidance — with limit capped at 200 and a cursor parameter, an agent would benefit from knowing when to expect truncation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: thread_ts accepts the ts of the parent message *or of any message in the thread*, which actually extends the schema's narrower 'parent message' wording. That resolves a real ambiguity in how to call it.

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

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

States a specific verb ('Read') and resource ('replies in a thread') plus the ordering and the inclusion of the parent message, which is genuinely distinguishing information. It does not, however, contrast itself with the sibling check_replies or conversations_history, so an agent must infer which of the three thread-reading tools applies.

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 resource name — you call it when you want a thread's contents — but there is no explicit 'use this instead of X when Y' guidance despite check_replies and conversations_history being obvious overlaps. The thread_ts clarification hints at the calling context but doesn't set boundaries.

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

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

Goes well beyond the destructive/idempotent annotations by disclosing the permission constraint (bot can only delete its own messages), the thread consequence (deleting a parent leaves replies), and irreversibility. These are exactly the behaviors an agent needs before invoking a destructive 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?

Four short sentences, each carrying a distinct and necessary fact: identity, permission scope, thread side effect, irreversibility/confirmation. The destructive warning is placed at the end where it lands before invocation.

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

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

For a two-parameter destructive tool with no output schema, the definition covers identity, preconditions, side effects, and safety. The only minor gap is what the agent should expect on success or failure (e.g., error when the message isn't the bot's own).

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

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

Schema coverage is 100%, so both parameters are already documented; the description adds provenance for ts ('as returned by send_message'), which helps the agent source the value correctly. No additional format or validation detail beyond that.

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 (delete) and resource (a message the bot posted), plus the identifying keys (channel, ts). It also implicitly distinguishes itself from siblings like send_message and edit_message by scoping the operation to the bot's own 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?

Establishes clear preconditions: the message must be one the bot posted, and Slack enforces that constraint. It also gives a confirmation directive ('confirm with the user unless they asked for it'), though it never names an alternative sibling (e.g., edit_message to blank content) for cases where deletion isn't possible.

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

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

Goes beyond the annotations' destructiveHint=true by explaining exactly what is destroyed: text, context and blocks fully replace the old content, so callers must resend anything they want kept. It also discloses the Slack-side permission restriction that the bot can only edit its own messages — an auth constraint neither the schema nor annotations carry.

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

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

Three sentences, front-loaded with the action and identity, then the permission caveat, then the replacement warning. No filler and nothing repeated from the schema verbatim.

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

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

For a mutation tool with no output schema, it covers the essentials: what it mutates, what is lost, and who is allowed to call it. Failure modes (invalid ts, editing another user's message) and the resulting edit timestamp are not addressed, though those are secondary.

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 already 100%, so baseline is 3; the description adds cross-parameter semantics the schema only partly implies — that text, context and blocks jointly overwrite rather than merge, and that ts must originate from send_message. It does not touch the format parameter, which the schema already covers.

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 ('Replace the content of a message') and pins down the identifier ('channel and ts, as returned by send_message'). That naming distinguishes it cleanly from send_message, delete_message and reactions_* 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?

Gives a clear precondition — the bot may only edit messages it posted — and tells the agent where the ts comes from ('as returned by send_message'). It does not explicitly contrast with delete_message or with sending a fresh message, but the context is unambiguous.

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

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

Adds substantial behavior the annotations don't convey: the inbox is process-local and volatile, so history is incomplete by design. It does not explain why readOnlyHint=false, namely that mark_read defaults to true and mutates read state — that justification lives only in 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?

Three tight sentences: capability first, caveat second, alternative routing third. Every sentence carries distinct information and the most decision-relevant constraint is front-loaded.

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

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

Covers the critical risk for this tool — that results are an incomplete, process-scoped window — which is what an agent most needs to avoid misinterpreting an empty inbox. With no output schema, the return shape is only loosely implied, but message lists are conventional enough that this is a minor 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 100%, so all five parameters (limit, since, channel, mark_read, unread_only) are already documented with formats and defaults. The description adds no parameter-level detail, which meets the baseline for fully covered schemas but no more.

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 ('Return direct messages and @mentions the bot received') plus the precise scope ('while this MCP server was running'). It also names the sibling tools that serve related needs, so an agent can distinguish it from conversations_history and wait_for_reply without opening any schema.

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

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

Explicitly states the exclusion case (messages before startup or delivered to another instance are absent) and routes the agent to wait_for_reply or conversations_history for reliable replies. It does not mention check_replies, a sibling that sounds closely related, leaving a small gap in the alternative-selection guidance.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety and repeat-call behavior are covered. The description adds one genuinely useful behavioral fact beyond the annotations: the reaction is attributed to the bot, not the calling user. It says nothing about failure modes or permission requirements.

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 tight sentence with the effect front-loaded and no filler. Every word earns its place.

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

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

For a 3-param, fully documented, annotation-backed tool, the description is nearly sufficient; the actor disclosure closes the main ambiguity. The remaining gap is prerequisites and error behavior, which matters less for an idempotent non-destructive 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 coverage is 100%, including a concrete emoji naming example ('thumbsup, eyes') and channel formats, so the schema carries the parameter semantics. The description adds nothing on top, which is the expected baseline here.

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

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

Specific verb + resource ('Add an emoji reaction to a message') and it adds the actor identity ('as the bot'). It is clearly distinct from reactions_remove by name and verb direction, though it never names the sibling explicitly.

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 when-to-use guidance, no prerequisites (bot must be a member of the channel, reactions:write scope), and no pointer to reactions_remove for the inverse operation. Usage is only inferable from the name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds one genuinely useful behavioral constraint beyond them — that only the bot's own reactions qualify — but says nothing about what happens on failure (e.g., reaction absent) or whether removal triggers notifications.

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 zero filler. Nothing could be cut without losing the scope constraint.

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 three-parameter mutation with complete schema docs, full annotation coverage and no output schema, the description covers what is needed to call it correctly. The only gap is failure-mode behavior when the reaction is not present.

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

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

Schema description coverage is 100% and all three parameters carry their own docs, including the emoji-without-colons format. The description adds no parameter-level detail, so this sits at the baseline for a fully documented 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 (Remove) and resource (an emoji reaction) with a meaningful scope constraint: only reactions the bot previously added. That scope distinguishes it from a general reaction-removal or from reactions_add, though it never names the sibling tool directly.

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

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

Usage is implied rather than stated: the 'previously added by the bot' clause tells the agent this is the undo path for reactions_add, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer that it cannot be used to remove other users' reactions.

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

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

Annotations already flag this as a non-read-only, open-world write, so the description's added behavior carries the credit: it posts as the bot, resolves users to DMs, appends `context` under a divider, treats `text` as fallback when `blocks` is set, and explicitly warns that interactive elements are unsupported. Remaining gaps are permission requirements and failure modes (e.g., bot not in channel, ambiguous name resolution).

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

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

Four sentences, front-loaded with the core action, then parameter guidance ordered by importance (target, context, blocks), then the return value. Every sentence carries distinct operational content with no restatement of the 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 7-parameter write tool with no output schema, the description covers the send target, layout mode, and return value (`ts` usable as `thread_ts` or with wait_for_reply). It omits what failure looks like and any constraints on DMing users the bot has never interacted with, which an agent may need when a send silently fails.

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 above that by clarifying target resolution semantics (email/name → DM) and giving a usage rule for `blocks` vs `text` that the schema doesn't state. It does not, however, explain precedence among identifier types or ambiguity handling for 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?

Opens with a specific verb+resource+scope: 'Post a message as the bot to a channel, a thread, or a user's DM.' That single sentence distinguishes it from edit_message, delete_message, and the read-oriented siblings, and the DM-vs-channel outcome is stated explicitly.

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 real selection guidance: users get a DM (not a channel post), `context` is for small reference details, and `blocks` should be used 'only when you need a custom Block Kit layout.' It also points forward to wait_for_reply/thread_ts. It stops short of naming siblings it should not be used instead of (edit_message, delete_message), so no explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds nothing beyond that — no mention of permission requirements for reading profiles, rate limits, or what happens when the identifier fails to resolve.

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 front-loaded sentence with the action, scope, and identifier forms in the first clause; nothing is padded. It is close to minimal but could carry one more clause of routing or behavior without bloat.

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

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

For a simple one-parameter read with no output schema, the description still does not indicate what 'profile details' includes (display name, email, title, timezone) or the shape of the result, leaving the agent guessing at return contents.

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 'User ID (U…), email address, or @handle'. The description restates the same accepted formats without adding new meaning such as precedence between them, so it sits at the baseline.

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

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

Names a specific verb and resource ('Get profile details for one Slack user') and scopes it to a single user, which implicitly separates it from the list-oriented users_search. It never names that sibling, so the 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?

Usage is implied by 'one Slack user' versus the sibling users_search and whoami, but the description never says explicitly when to pick this tool over those alternatives, nor any prerequisite such as needing a user ID from a search first.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds useful behavior beyond that: exact matches come first and results are user IDs intended for downstream 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?

Two tight sentences, front-loaded with the core action and search fields, followed by the useful return-value context. No wasted wording.

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

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

For a simple read-only search tool with full schema coverage and no output schema, the description covers purpose, accepted identifiers, return IDs, and ordering. Minor gaps like pagination or bot inclusion are already handled by the schema.

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

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

Schema coverage is 100%, so all three parameters are documented there. The description repeats the query field semantics and notes exact-match ordering, but adds no extra detail about limit or include_bots.

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: finding workspace members. The search fields are enumerated, making the scope clear, though it does not explicitly distinguish itself from user_info or whoami.

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?

Implies usage by saying the returned user IDs work with send_message and other tools, but does not explicitly state when to use this instead of user_info or whoami, nor 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing the blocking cost per call, the `replied: false` contract with `next_step`, the recommendation to cap retries, and the hard interaction with the MCP client's tool-call timeout. Nothing here contradicts the annotations — the tool does read Slack but consumes a model turn, so readOnlyHint=false is not inconsistent with the text.

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 the first clause, and each subsequent sentence carries a distinct operational rule with no filler. It is dense but slightly long, with the Claude Code MCP_TOOL_TIMEOUT parenthetical being the only marginal content.

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

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

For a six-parameter blocking poll tool with no output schema, it covers the blocking semantics, the failure return fields, the retry policy, and the client-side timeout ceiling. An agent can call this correctly and know what to do on a timeout without further information.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `since_ts` should be the ts of the question from send_message, and `timeout_seconds` must stay under the client's tool-call timeout. It also explains that replies both as top-level messages and inside the question's thread are matched, which is not evident from the schema alone.

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 with precise scope: blocks until a human (not the bot) replies in a channel, DM, or thread, then returns the new messages. It also implicitly distinguishes itself from the non-blocking sibling check_replies, which it names later.

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 bounds when to use it ('only when an answer is likely within a minute or two; every call costs a model turn') and gives a decision path for the failure case: follow `next_step`, and after a couple of timeouts stop and use check_replies instead. That is when/when-not/alternative guidance in full.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful context beyond that: the tool surfaces scopes and specifically which tools are missing scopes, making it a diagnostic rather than an identity call. It does not describe output format or failure modes, but with annotations carrying the safety signal this is solid.

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 dense sentence listing the returned fields, followed by one actionable routing sentence. Every clause earns its place; the field list is long but each item is a distinct diagnostic output. Front-loading the verb 'Show' keeps it readable.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so explicitly by enumerating the six categories of information returned. Combined with the troubleshooting trigger, an agent has enough to call it correctly and interpret the result. It could be slightly more complete by noting that it is workspace/bot-scoped rather than user-scoped.

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, which is the baseline-4 case: there is nothing for the description to disambiguate. The description correctly implies no arguments are needed and focuses on what the call reveals.

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 concrete verb ("Show") and enumerates the exact resources returned: server version, connected bot, workspace, connection mode, granted scopes, and missing-scope tools. This clearly reframes the ambiguous name 'whoami' into a Slack diagnostic tool. It does not explicitly contrast with the sibling user_info, which sounds superficially similar, so it falls just short of 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?

It gives a crisp trigger condition: "Call this first when a Slack action fails with a permission error." That is a genuine when-to-use rule tied to the sibling family of Slack actions. It stops short of naming a true alternative or stating when not to call it, so it is strong but not complete.

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