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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context: the ban persists until explicitly lifted, the required permission scope, and a mandatory user-confirmation step. It does not state whether a reason is required or what happens when the target is not currently a member.

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 no filler; the effect statement comes first and the precondition second. 'Returns: Confirmation.' is largely redundant given an output schema exists, costing it the top score.

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 destructive moderation tool, the description covers effect, permission requirement, and confirmation policy, and the output schema handles the return value. Missing edge cases (target not in server, interaction with existing bans, audit-log reason requirements) are minor against the annotation coverage.

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 75%, with reason, guild_id, and delete_message_days all already described in the schema itself. The description's 'optionally deleting their recent messages' merely restates delete_message_days without adding format, default, or range detail, so the baseline of 3 applies.

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

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

States a specific verb (Ban) and resource (user from the server), and the parenthetical clarifies the durable effect ('cannot rejoin until unbanned'), which distinguishes it from kick_member and timeout_member in the sibling set.

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 concrete prerequisites and a procedural rule: 'Needs Ban Members' and 'Confirm with the user before calling.' It stops short of explicitly naming alternatives (kick/timeout/unban) and when to prefer them, so routing between the sibling moderation tools still requires 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. The description still adds non-obvious behavior: irreversibility, the Manage Messages permission requirement, and Discord's 14-day refusal rule — genuinely useful context beyond the structured fields, though it doesn't cover audit-log semantics or partial-failure handling.

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, front-loaded sentences: action and irreversibility first, then the platform limit and the alternative, then the confirmation guardrail, then the return shape. No sentence is 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?

For a destructive bulk-mutation tool with an output schema present, the description covers the action, limits, permission requirement, required user confirmation, fallback tool, and return summary. 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 67% and the uncovered channel_id has no description in either place. The description compensates by reinforcing that all message_ids must live in one channel and be under 14 days old, and that the count is bounded at 2–100 — adding constraint meaning beyond the raw 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 (Delete), resource (messages), and scope (2–100, single channel) in one call. It clearly distinguishes itself from the sibling discord_delete_message by specifying the bulk range, so an agent can route 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?

Explicitly names the when-not case: messages older than 14 days must be deleted one at a time with discord_delete_message, naming the alternative. It also adds a procedural guardrail ('Confirm with the user before calling'), which is actionable usage guidance rather than vague advice.

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=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds the permission requirement and confirms a mutation with a return value, but doesn't disclose non-idempotency or destruction scope. With annotations covering the safety profile, the added value is modest.

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?

Very concise and front-loaded: the core action is stated first, then the permission requirement, then the return value. Two sentences with no waste, though the return-value line is a bit 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 7-parameter mutation tool with no annotations covering permissions, the description could say more about required Discord permissions, the effect of each type value, or how the channel placement works. With an output schema present, the return description is unnecessary. Adequate but not complete.

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

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

Schema coverage is 86% – the schema already documents all 7 parameters, including the enum for 'type' and descriptions for name, topic, reason, guild_id, parent_id. The description adds no parameter-level details beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Create a channel or category in a server.' This clearly distinguishes it from siblings like discord_edit_channel or discord_delete_channel, which are non-create operations on the same resource.

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 required permission (Manage Channels) but offers no when/when-not guidance or references to alternatives. For instance, it doesn't say to use discord_create_thread instead for forum-like threads, nor when to create a category vs. a channel. Implied usage only.

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

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

Annotations cover the safety profile (not read-only, not destructive, not idempotent, open-world), and the description adds value beyond them: the Manage Roles authorization requirement and the behavioral note that new roles land at the bottom of the hierarchy. It doesn't cover error cases such as hitting the role limit, so it stops short of 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, front-loaded sentences with no padding; purpose comes first, then prerequisites, then hierarchy behavior. The 'Returns: Confirmation with the role ID' line is mildly redundant given an output schema exists, keeping it from a 5.

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

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

With an output schema and annotations present, the description is complete enough: purpose, auth requirement, and a key behavioral trait are all stated. Minor gaps remain around failure modes (permission errors, role limits) for a 7-parameter 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 description coverage is 86%, so the schema already documents the parameters (color format, hoist, mentionable, permissions bitfield, guild_id fallback). The description adds no parameter detail, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Create a role') that inherently separates it from discord_edit_role, discord_delete_role, and discord_list_roles. It stops short of naming a sibling explicitly, so it's clear but not maximally 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?

'Needs Manage Roles' gives a permission prerequisite, which is genuine usage context, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives like discord_edit_role for later changes. 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is clear. The description adds valuable context: the return value (thread ID) and the follow-up action (use discord_send_message with the thread ID as channel_id). It does not mention rate limits or permission requirements, but the core behavioral guidance is present and useful.

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, followed by the return value and next-step guidance. Every sentence earns its place with no redundancy.

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

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

For a tool with 6 parameters, 83% schema coverage, and an output schema, the description covers the purpose, the two modes, the return value, and the integration with discord_send_message. It is nearly complete. A minor gap is the absence of permission requirements or rate-limit notes, but given annotations and output schema, this is a strong definition.

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 83%, so most parameters are already documented in the schema. The description does not elaborate on any parameter beyond noting the two modes, which aligns with the schema's message_id description. Baseline 3 is appropriate when schema does the heavy lifting and the description adds no extra parameter details.

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 (Start) and resource (thread), and explicitly covers the two modes: from an existing message or standalone in a channel. This distinguishes it clearly from siblings like discord_send_message or discord_create_channel.

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 clarifies the two creation modes (message-based vs standalone), which is the key usage decision. It also tells the agent how to post into the new thread (discord_send_message with thread ID as channel_id). However, it does not mention when to use this versus discord_list_threads or discord_create_channel explicitly, nor does it state prerequisites like permissions.

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, so the description earns credit for additive context: it discloses the cascade effect ('every message in it'), irreversibility, the required permission (Manage Channels), and a confirmation requirement. It stops short of 5 only because 'Irreversible' partially echoes the destructive annotation.

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, front-loaded sentences: action, irreversibility, prerequisite/confirmation, and return. Zero filler and every sentence carries operational weight.

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 destructive single-target mutation with full annotations and an output schema, the description covers the essentials an agent needs: what is destroyed, irreversibility, permission, and confirmation. Return-value detail is safely delegated to the 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?

Schema description coverage is 100% – channel_id documents the pattern and irreversibility, and reason documents its audit-log purpose. The description adds nothing about parameter usage, 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 ('Permanently delete a channel or thread') and clarifies scope with 'every message in it', which sharply distinguishes it from siblings like discord_delete_message or discord_delete_role. An agent can select 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?

Gives explicit pre-call guidance ('Confirm with the user before calling') and a permission prerequisite ('Needs Manage Channels'), which is clear context for when the tool is appropriate. It does not name alternative tools (e.g., discord_edit_channel) for non-destructive edits, so it stops short of full alternative routing.

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, non-idempotent, and open-world. The description adds the critical 'Irreversible' warning and the permission nuance, both valuable. But with annotations carrying the safety profile, and the description adding only irreversibility and permissions, a 3 is appropriate – more detail on audit log or recoverability would raise 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 sentences plus a return note. Every clause carries information: scope, permission, irreversibility, and sibling routing. Front-loaded and zero 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?

Output schema exists, so return values needn't be explained; the 'Returns: Confirmation' suffices. Description covers scope, permissions, and irreversibility. Missing only audit-log/reason behavior, which is minor given the schema documents 'reason'.

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 67%. The description doesn't mention any parameters by name; the schema documents channel_id, message_id, and reason. The description adds no parameter-level meaning, which is acceptable at baseline 3 when schema does substantial work, but it doesn't compensate for the remaining uncovered parameter.

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 ('Delete one message') and explicitly distinguishes scope from the sibling discord_bulk_delete_messages by stating the bulk range (2-100). An agent can immediately tell this is the single-message deletion tool.

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

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

Explicitly routes bulk operations to discord_bulk_delete_messages and notes the permission requirement (Manage Messages) for others' messages. Doesn't state when-not-to-use beyond the bulk case, but the context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the bar is lower. The description adds concrete value beyond them by stating the blast radius (removed from every member) and the irreversibility/confirmation requirement, though it says nothing about audit-log reasoning or permission needs.

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, front-loaded statements with no filler; the destruction scope leads and the caution follows. The trailing 'Returns: Confirmation.' is slightly 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 destructive mutation with annotations covering the safety profile and an output schema covering the return value, the description supplies the key missing behavioral context (scope + irreversibility). Only minor gaps remain, such as permission prerequisites.

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 67%, with 'reason' and 'guild_id' documented in the schema while 'role_id' is only implied by its name and pattern. The description adds no parameter syntax or format detail, so baseline 3 applies when the schema carries most of the load.

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

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

States a specific verb+resource ('Delete a role') and clarifies scope ('removing it from every member'), which distinguishes it from edit_role, create_role, and set_member_role among the 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?

Provides a clear precondition: 'Irreversible — confirm with the user first,' which is actionable guidance for an agent. It does not, however, name alternatives (e.g., edit_role to modify rather than delete), so the routing guidance is incomplete.

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=false, destructiveHint=false, idempotentHint=true, so safety and idempotency are covered. The description adds the permission requirement and the partial-update behavior, which is genuinely useful context. It stops short of describing rate limits or side effects of archiving.

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: action list, partial-update caveat plus permission, and return summary. Front-loaded with the operations and no wasted clauses.

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?

Output schema exists, so return values needn't be explained; the description still summarizes the confirmation. Permissions and partial-update semantics are covered. Minor gap: no mention of thread-vs-channel field restrictions beyond the per-param notes in 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 description coverage is 70%, with several params (locked, reason, archived, position, parent_id, slowmode_seconds) already documented in the schema. The description's list of actions maps to those params but adds no format or unit detail beyond the schema. Baseline 3 is appropriate.

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

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

Specific verb list (rename, retopic, move, slowmode, archive/lock) plus the resource (channel/thread). It clearly distinguishes itself from siblings like discord_create_channel or discord_delete_channel by being the edit tool.

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

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

States 'Only the fields you pass are changed' and the required permission (Manage Channels / Manage Threads for threads), which tells the agent when the call will succeed. It does not name sibling alternatives, but the edit-vs-create/delete distinction is implied by the verb set.

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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description usefully adds the ownership restriction, but it omits whether the edit fully replaces prior content, permission requirements, or rate-limit behavior. The 'Returns: Confirmation.' line is minimal context, not real 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?

Two short sentences, front-loaded with the action and the constraint; nothing is padded. The 'Returns: Confirmation.' line is largely redundant given a dedicated output schema exists, which is the only wasted element.

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 three-parameter mutation tool with an output schema, annotations, and full schema coverage, the description covers the essential constraint (bot-owned messages only). An agent has enough to call it correctly; only replace-vs-append semantics and failure modes are left 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 100% and each of the three parameters carries a substantive description (ID patterns, 2000-char Markdown limit, bot-ownership requirement). The description adds no parameter-level detail beyond the schema, 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 ('Replace the text of a message') and adds a scope qualifier ('the bot sent') that separates it from discord_send_message and discord_delete_message. It does not name a sibling explicitly, but the ownership restriction makes the tool's role unambiguous.

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

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

The description gives one hard precondition — the message must have been sent by the bot — which implies when the tool is applicable. It offers no explicit routing guidance versus alternatives such as discord_delete_message (for removal) or discord_send_message (for new content), so usage must be 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 readOnly=false, destructive=false, and idempotent=true, so the safety profile is covered. The description adds a genuine behavioral trait not in the annotations — partial-update semantics ('only passed fields change') — plus a return confirmation, but says nothing about required permissions or the risk of granting a permissions bitfield.

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 with the mutable-field list front-loaded and the partial-update rule immediately after. The 'Returns:' line is mildly redundant given an output schema exists, but it is short and costs little.

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 8 parameters, the description covers the field set and patch behavior adequately, and the output schema means returns need not be detailed. It omits authorization requirements and the consequence of overwriting a role's permission bitfield, which an agent should know before calling.

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 only 50%, and the description usefully names exactly the undocumented fields (name, hoist, mentionable) alongside color and permissions, compensating for the gap. It still does not explain semantics such as what 'hoist' does or the permission bitfield encoding, which the schema handles only for permissions.

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 ('Change') and resource ('a role') and enumerates the mutable fields, so an agent can distinguish it from discord_create_role, discord_delete_role, and discord_list_roles without opening the schema. It stops short of explicitly naming a sibling or exclusion, 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?

'Only passed fields change' implies a patch-style update against an existing role, which is usable context. However, there is no explicit when-to-use guidance, no mention of prerequisites such as needing Manage Roles, and no comparison against alternatives like discord_set_member_role.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive. The description adds the non-obvious prerequisite 'Needs View Audit Log', which is exactly the kind of auth context annotations cannot express. It doesn't mention rate limits or pagination, 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?

Front-loads the core purpose, then permission requirement, then use cases, then return shape, in four short lines with zero filler. Every 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?

Covers purpose, permission requirement, intent examples, and return shape (including both markdown and JSON field sets). With an output schema also present, nothing needed for correct invocation is missing.

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

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

Schema coverage is 80%, so the schema already documents action, user_id, guild_id, and response_format. The description adds no parameter-level syntax or format detail beyond what the schema provides, which is the expected baseline 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?

States a specific verb and resource ('Read the server's audit log') and immediately enumerates its content scope (bans, kicks, deletions, channel/role changes). None of the many siblings cover audit log retrieval, so it is clearly distinguishable.

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 concrete selection examples ('Use to answer "who deleted that channel" or "why was X banned"') that map to real agent intents. No explicit when-not-to-use or alternative-naming, which keeps it below a 5, but the intent routing is strong.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds some context by naming thread-specific fields and return formats, but discloses no auth requirements, rate limits, or other operational behavior beyond what annotations and the output schema already provide.

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

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

Two short sentences with the purpose and returned fields front-loaded. The second sentence about return format is somewhat redundant with the existing output schema, so it is not perfectly waste-free, but the definition remains compact and easy to scan.

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

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

For a simple read-only getter, the definition covers what the tool fetches, what fields are included, and how results are formatted. An output schema exists so return values need not be explained in depth, and the main gap is guidance on when to prefer this over the list-channel or list-thread siblings.

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 channel_id and response_format are already documented in the schema. The description adds no parameter-level syntax, format, or constraint details, making the baseline 3 appropriate.

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

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

States a specific verb and resource: 'Get one channel or thread,' and enumerates the returned fields (type, topic, parent, slowmode, thread archive/lock state). This distinguishes it from bulk siblings in spirit, but it never names alternatives like discord_list_channels or discord_list_threads.

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 phrase 'Get one channel or thread' implies single-item lookup as opposed to listing, but there is no explicit when-to-use guidance, no when-not-to-use condition, and no named alternative. Usage is only inferable from the contrast with list-style siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the return-shape context (Markdown summary vs JSON fields), but since an output schema exists this is largely redundant; no permissions, rate limits, or edge cases are 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, front-loaded sentences with no filler; the purpose comes first and the return list second. Slight redundancy in re-listing fields already present in the output schema keeps it from a 5.

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

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

For a simple read-only tool with two optional params, 100% schema coverage, and an output schema, the description covers the essentials. The only real gap is the absence of usage routing against sibling 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 100%, so both parameters are already documented in the schema. The description does not add syntax, defaults, or format guidance beyond that, matching the baseline 3 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?

States a specific verb and resource ('Get details for one server') and enumerates the fields returned, so an agent knows what it retrieves. It does not explicitly distinguish itself from siblings like discord_list_guilds or discord_get_channel, so it stops 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 offers no when-to-use, when-not-to-use, or alternative-tool guidance. The only usage hint ('Omit to use DISCORD_GUILD_ID from .env') lives in the schema, not the description.

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 destructiveHint=false, so the safety profile is covered. The description adds useful context by naming the fields returned and the timeout status, but says nothing about auth requirements, permission scope, or failure modes for a missing/invalid member.

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; purpose is front-loaded and the return-shape note follows. Every line carries some signal, though the 'Returns:' line is partly redundant with the existing output 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?

With an output schema present and rich annotations, the description needn't restate return values, and it sufficiently frames the tool as a single-member read. The only gap is ambiguity on how to identify the member (ID vs username) and which server is targeted.

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 67% and both guild_id and response_format already carry descriptions in the schema. The description's 'Markdown bullets or JSON member object' loosely reflects response_format but adds no new parameter semantics, especially for the undocumented required user_id.

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

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

Specific verb ('Get') plus resource ('one member's profile in this server') with an enumeration of the returned fields (nickname, roles, join date, timeout status). The phrase 'one member' implicitly distinguishes it from the bulk discord_list_members / discord_search_members 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 only implied by 'one member's profile' versus the list/search siblings; there is no explicit statement of when to use this over discord_list_members or discord_search_members, nor any prerequisites for resolving the user.

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 destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing what content the fetch includes (attachments, embeds, reactions) and that JSON output matches discord_read_messages item shape, giving useful consistency context.

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, zero filler. The core action and its scope are front-loaded, and the returns note follows 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?

For a simple read tool with rich annotations and an output schema, this is nearly complete: it names the included content, the two response formats, and cross-references the sibling item shape. It does not mention error behavior for missing/inaccessible messages, 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 coverage is 67% and response_format already documents its markdown-vs-json tradeoff in the schema. The description reiterates 'by ID' and the return format but adds no syntax or constraints for message_id, which is undocumented in both places. Baseline 3 fits.

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 explicit scope: 'Fetch one message by ID, including attachments, embeds and reactions.' This implicitly separates it from the list-oriented discord_read_messages and discord_search_messages, but no sibling is named, so it falls short of full explicit 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?

Usage is only implied by 'by ID' — an agent can infer this is the tool to call when it already has a message ID and wants the full message rather than a list. There is no explicit when-to-use, when-not-to-use, or pointer to discord_read_messages or discord_search_messages as alternatives.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered. The description adds value beyond them: reversibility ('can rejoin with an invite'), the required bot permission, and a confirmation requirement before an irreversible-to-the-user (though recoverable) action.

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, front-loaded sentences with no filler; the action and reversibility lead. 'Returns: Confirmation.' is slightly redundant given an output schema exists, which keeps it from a 5.

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

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

For a destructive moderation tool with an output schema, the description covers action, reversibility, permission, and confirmation gating, which is enough to call it correctly. It doesn't note failure modes (e.g., missing permission or invalid user_id) but 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 coverage is 67% (reason and guild_id are documented; user_id is not). The description adds no parameter meaning at all – no mention of user_id source/format or how guild_id defaults. Baseline 3 is appropriate when the schema does most of the work but a gap remains unaddressed.

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 member from the server'). Crucially, 'They can rejoin with an invite' distinguishes it from discord_ban_member without the agent needing to open either schema, and the sibling set confirms ban/timeout are the relevant alternatives.

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

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

Provides the permission prerequisite ('Needs Kick Members') and an operational gate ('Confirm with the user before calling'), plus implicit selection guidance via the rejoin note. It never explicitly names ban_member/timeout_member as alternatives, 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description still adds the permission requirement and the exact output shapes, which are not in the annotations. It does not mention pagination behavior for the limit, a minor omission.

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 action front-loaded and a labeled 'Returns:' clause; every phrase carries information and nothing is 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 values need not be described, yet the description restates them helpfully and covers the auth prerequisite. The only gap is the undocumented limit parameter, which is minor for a read-only 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 67%: guild_id and response_format are documented in the schema while limit is not. The description reinforces response_format by spelling out what 'markdown' vs 'json' produce, but adds nothing about the limit parameter, so it only partially compensates for the 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 banned users') plus the payload it returns ('the reason recorded for each'), making it clearly distinct from the ban/unban siblings. It stops short of naming a sibling to route against, so it is clear but not maximally differentiated.

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

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

The description supplies a prerequisite ('Needs Ban Members'), which is genuine usage context, but offers no when-to-use vs when-not guidance and never points to alternatives such as discord_get_audit_log or discord_unban_member. Usage is implied by the name rather than 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?

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description still adds real value beyond that by stating the threads exclusion and the exact return shape. It stops short of richer context (pagination, auth scope, ordering guarantees), so a 4 rather than 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, front-loaded sentences: purpose, routing hint, then return contract. No filler, and the most decision-relevant facts (what it lists, the threads caveat, the return format) come first.

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

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

For a read-only list tool with full schema coverage and an output schema, the description covers everything an agent needs: scope, the sibling alternative, and a summary of the return shape. 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 100%, so the baseline is 3. The description references kind and name filtering, which loosely map to the 'type' and 'name_contains' parameters, but the schema already documents each field with examples and patterns, so the description adds little beyond it.

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

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

The first sentence gives a specific verb and resource ('List a server's channels and categories') plus the scope of optional filtering. It also explicitly distinguishes itself from discord_list_threads ('Threads are not included'), so an agent can differentiate it from siblings 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?

It states the primary use case explicitly ('The usual way to find a channel_id before reading or posting') and names the alternative for the excluded case ('use discord_list_threads'). When-to-use and the contrasting tool 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?

Annotations already cover readOnly/idempotent/openWorld safety, but the description adds real behavioral context: the bot only sees guilds where someone with Manage Server added it, and it cannot browse outside its memberships. That permission/visibility constraint is not derivable from the annotations.

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

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

Front-loaded with the core purpose, then a useful visibility caveat, then usage guidance and returns. Slightly padded by a returns block that duplicates the output schema, but no sentence is wasteful enough to break flow.

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 restated, yet the description goes further by clarifying that `owner` means the bot's owner owns the server — non-obvious interpretation help. Combined with annotations covering safety, the agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the single response_format parameter is fully documented by the schema itself. The description's 'Markdown table ... or JSON list' phrasing mirrors the schema's markdown/json enum without adding syntax or constraint details, 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 ('List every server (guild) the bot has been invited to') with clear scope. The 'bot has been invited to' qualifier implicitly distinguishes it from discord_get_guild, which fetches one guild by ID.

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 says 'Use this to find a guild_id', giving a clear reason to invoke the tool. It does not name a specific alternative (e.g., discord_get_guild) or an explicit when-not condition, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the privileged-intent requirement and the resulting Missing Access failure mode, which annotations cannot express. The 'Returns:' line largely restates the output schema, so it earns less credit.

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 action and then the critical precondition, with no filler sentences. The trailing 'Returns:' sentence slightly duplicates the output schema, costing 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?

For a read-only list tool with a full output schema and annotations, the description covers the remaining agent-relevant risks: the privileged intent gotcha, the exact error it produces, and the cursor-based continuation model. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter (after, limit, guild_id, response_format) is already documented in the schema. The description adds only the pagination loop hint via next_after, which the schema itself already states, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List server members') plus a scoping qualifier ('in join order with cursor pagination') that implicitly separates it from discord_search_members and discord_get_member. It never names those siblings, so the differentiation is left for the agent to infer rather than stated outright.

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 real precondition (Server Members privileged intent must be enabled, else Missing Access), which is a usage condition. However, it never says when to prefer this tool over discord_search_members or discord_get_member, so the agent must guess between siblings.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description adds genuine value with the 50-item cap and a cross-tool shape reference ('same shape as discord_read_messages items'). It does not say what happens when a channel exceeds 50 pins, which is the one 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 sentences, zero waste, with the core action and the hard cap front-loaded before the return-shape note. Every clause 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?

With a full output schema and comprehensive annotations, the description carries little extra burden, and it correctly covers the cap and return shape. It omits what an agent should do when a channel has more than 50 pins (pagination / truncation behavior), which is the only loose end.

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, establishing a baseline of 3. The description only loosely implies the response_format choice ('Markdown messages or JSON list') without adding syntax or format 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+resource ('List the pinned messages in a channel') plus a meaningful scope cap (max 50), so it is clearly distinguishable from discord_pin_message and discord_read_messages. It stops short of naming how it relates to those siblings, keeping it at 4 rather than 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 resource name — an agent can infer it is for enumerating existing pins — but there is no explicit when-to-use guidance relative to alternatives such as discord_read_messages or discord_get_message, and no prerequisite/auth context.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds return-format details and the permission bitfield note, but since an output schema exists, some of this is redundant; no rate-limit or pagination context.

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: purpose, usage pointer, return shape. Efficient, though the 'Returns' line partially duplicates what the output schema already conveys.

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

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

Given an output schema exists, the description needn't detail return values, yet it still summarizes them coherently. Covers ordering, downstream use and permission data; only pagination/limits 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?

Schema coverage is 100%, so guild_id and response_format are fully documented in the schema, including the DISCORD_GUILD_ID fallback. The description adds no param-level detail beyond what the schema provides; 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?

Specific verb+resource ('List a server's roles') with ordering stated ('highest to lowest') and the fields returned enumerated. Clearly distinguishable from siblings like discord_get_guild or discord_list_members.

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 names the downstream tool the output feeds ('Use to find role_id for discord_set_member_role'), giving the agent a clear when-to-use condition. Permission bitfield location is also noted.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely useful behavioral context the annotations lack: only unarchived threads are returned, and archived threads are explicitly excluded, which an agent must know to interpret results correctly.

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 sentence, followed by return format and the exclusion note. Three short lines, zero padding, each sentence carrying 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?

With a rich schema (100% coverage), full annotations, and an output schema present, the definition is nearly complete. It omits any mention of result limits or pagination for servers with many threads, which is a minor gap given the otherwise strong coverage.

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 guild_id, channel_id, and response_format are fully documented in the schema (including the .env fallback for guild_id). The description confirms channel_id narrows to a parent channel but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (List) and resource (threads) with a precise scope qualifier (active/unarchived). The optional channel scoping distinguishes it from a generic thread enumeration and from sibling channel tools like discord_list_channels.

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 usage via the channel_id filter ('optionally only under one channel') but never states when to prefer this tool over siblings such as discord_list_channels or discord_get_channel. No explicit when-not guidance is given.

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=false, idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds a genuine auth requirement ('Needs Manage Messages'), which is useful context, but says nothing about rate limits, behavior on already-pinned messages, or unpin side effects. With annotations carrying most of the burden, a 3 is appropriate.

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 lines with the core action front-loaded and no filler. The 'Returns: Confirmation' line is largely redundant given an output schema exists, which costs 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?

For a simple mutation tool, the description covers the action and the permission requirement, and the return value is handled by the output schema. It omits any routing guidance relative to list_pins/delete_message, which leaves a gap an agent could need.

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 50%: reason and channel_id are documented in the schema, while action and message_id are not. The description's 'pin or unpin' and 'in its channel' loosely map to the action and channel_id parameters but add no syntax or format detail, so it only partially compensates for the coverage 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?

The description names a specific verb pair (pin/unpin) and resource (a message in its channel), so the agent knows exactly what operation is performed. It does not explicitly differentiate from the sibling discord_list_pins or explain the relationship, 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 only implied by the verb – there is no statement of when to pin/unpin versus using siblings like list_pins or delete_message. The 'Needs Manage Messages' clause functions as a prerequisite/condition rather than an explicit when-to-use rule, so guidance is present but thin.

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=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds one genuinely useful behavioral fact beyond that: the reaction is the bot's own identity, not an arbitrary user's. It says nothing about rate limits or permission requirements, so it goes modestly past the annotations but not far.

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 operation front-loaded and no preamble. The trailing 'Returns: Confirmation.' is largely redundant given the output schema exists, 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?

For a simple reaction mutation with annotations and an output schema present, the description covers the essentials and the identity-scoping constraint. Remaining gaps are the undocumented message_id parameter and the absence of any when-to-use or permission context, which keeps it short of a 5.

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

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

Schema coverage is 50%: emoji and channel_id are documented in the schema, while message_id and action are not. The description's 'add or remove' maps loosely to the action enum but adds no new detail on message_id or emoji format. Marginal compensation for the coverage gap, so baseline 3 is appropriate.

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

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

States a specific verb pair (add/remove) and resource (reaction on a message), and uniquely scopes it to 'the bot's own reaction'. No sibling tool manipulates reactions, so the resource alone distinguishes it from discord_send_message, discord_edit_message, and the rest of the message family.

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 usage via 'add or remove' but never states when to call this versus alternatives (e.g., reacting vs. replying), nor any prerequisites like needing the message to exist or the bot having channel access. Usage is inferable but not guided.

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 (readOnly, idempotent, non-destructive), and the description adds real operational context on top: a required bot intent whose absence silently yields empty content, cursor-based pagination semantics, and the mutually exclusive cursor constraint. This is exactly the kind of failure mode an agent needs warned about 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 purpose, then the intent warning, then the cursor constraint, then returns. The return-format block is long and largely duplicated by the output schema, which is the one place it does not fully earn its space.

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 and 100% parameter coverage, the description only needs to supply what structured fields cannot: the intent prerequisite, cursor pagination model, and cursor exclusivity. All three are present, so 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 100%, so the baseline is 3. The description earns a bump by stating the one-of constraint across before/after/around, which the schema does not encode (no exclusiveMaximum/oneOf), and by tying `before` to the previous page's cursor.

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 (messages) plus scope (a channel or thread, newest first, cursor-paginated), which implicitly separates it from discord_get_message (single ID) and discord_search_messages. It never names a sibling or an alternative, so the differentiation is inferred rather than 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?

Gives two concrete conditions: the Message Content intent must be enabled or reads come back empty, and only one of before/after/around may be passed. What is missing is routing guidance against the neighboring read tools (search_messages, get_message, list_pins).

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 read-only, idempotent, open-world and non-destructive traits. The description adds genuinely useful behavioral context beyond that: the privileged-intent requirement difference versus discord_list_members and the two possible response shapes. Auth/permission details and search behavior on multiple matches are not covered, 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?

Three short blocks: what it does, why it beats the alternative, what comes back. Scoping and the routing hint are front-loaded, and every sentence carries 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?

Covers purpose, alternative, intent caveat and return shape for a 4-param read tool with a structured schema and output schema. Some return-value detail is duplicated rather than additive, and it omits behavior when several members match or when nothing matches, keeping it from a 5.

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

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

Schema coverage is 75% and the schema itself supplies the prefix example for 'query' and the guild_id env fallback. The description adds return-field names but no syntax or constraint detail for limit, query or guild_id, 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 precise verb+resource+scope: prefix search over username or nickname. It explicitly distinguishes itself from the sibling discord_list_members, so an agent can route between them 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 the when-to-use framing ('quickest way to turn a name into a user_id') and names the alternative (discord_list_members) along with the deciding condition (no privileged Server Members intent required). Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds crucial behavior the annotations cannot convey: Discord's search API is unavailable to bots, so it pages through 100 messages per call and filters locally. It also discloses the cost/latency tradeoff of increasing max_scan and summarizes the return payload.

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 purpose, then the implementation constraint, then the when-to-use heuristic, then the return shape. Three tight sentences with no filler or repetition.

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

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

Given an output schema exists, the description need only set expectations and it does: filtering semantics, scan limits, and a brief return summary. Nothing required to call this tool correctly is missing for a 6-param 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 coverage is 100%, so the baseline is 3; the description still adds meaning by explaining the max_scan/recency relationship ('raise max_scan' for older history) and by tying the result format to discord_read_messages' shape. It does not add syntax detail beyond the schema, but it enriches the two parameters that drive scan behavior.

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 ('Find messages in a channel containing a phrase') plus an optional scope qualifier ('optionally by one author'). It clearly distinguishes itself from discord_read_messages and discord_get_message by describing local substring filtering rather than retrieval by ID.

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 concrete use-case ('what did X say about Y last week') and a tuning instruction ('for older history raise max_scan'). It stops short of explicitly naming sibling alternatives like discord_read_messages or stating when not to use this scan-based approach.

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

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

Annotations only declare the generic non-readOnly/non-idempotent/open-world profile; the description adds real context: the tool fails when the recipient has DMs from server members/bots disabled, that user consent should be obtained first, and that the returned DM channel ID can be reused. It stops short of stating rate limits or whether the message can be recalled, which would be 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?

Three short paragraphs with the action front-loaded, then the failure/consent caveat, then the return value. Every sentence carries distinct information and nothing is redundant.

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 need not document the return payload, and it correctly refrains from doing so while still hinting at the reusable channel ID. Annotations plus schema plus description cover safety, failure mode, and follow-up path; only edge cases like rate limiting or bot-permission errors 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?

Schema coverage is 100%, so both user_id (pattern, DM-allowance constraint) and content (Markdown, 2000-char cap) are already documented in the schema. The description adds no syntax or format detail 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 ('Send a direct message from the bot to a user') and implicitly separates itself from the channel-post sibling by noting 'DMs feel more personal than channel posts'. An agent can tell this apart from discord_send_message without opening either schema.

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

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

Gives an explicit operational precondition ('Confirm with the user before sending') and a failure condition tied to recipient DM settings. It lacks an explicit when-not/alternative routing statement naming discord_send_message, but the context for choosing a DM is clear.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds meaningful behavior beyond them: immediate public visibility, the mention-ping gating rule, and the returned confirmation with message ID and jump link.

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, front-loaded lines: the core action first, then the safety caveat, then the mention rule, then the return shape. No filler, and 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 5-param send tool, annotations cover the safety profile, the output schema covers the return value (which the description also summarizes), and the description covers visibility and mention behavior. Nothing needed 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 100%, so the baseline is 3, but the description adds real semantics for allow_mentions ("mentions do not ping unless allow_mentions is true"), which is the non-obvious behavioral implication of that flag.

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 ("Post a message") plus the target surfaces (channel, thread, DM channel). It's clear what it does, but it doesn't differentiate from the sibling discord_send_dm, which overlaps on the DM case, so sibling disambiguation is incomplete.

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 actionable context: the message is immediately visible to everyone, so confirm wording with the user first, and mentions won't ping unless allow_mentions is set. This is clear guidance, though it never states when to prefer this over discord_send_dm or discord_edit_message.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is partly covered. The description adds meaningful context beyond them: the required Manage Roles permission and the role-hierarchy constraint. It does not describe side effects or audit-log behavior, but the auth requirements are a solid addition.

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 core purpose leads. 'Returns: Confirmation.' is minimal and largely redundant given an output schema exists, which trims 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?

With an output schema present the description need not explain return values, and annotations cover the mutation/idempotency profile. The permission and hierarchy prerequisites are the key operational detail an agent needs, so coverage is largely complete, with only the action/undo semantics left partly implicit.

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 60% (action and user_id are undocumented there). The description maps 'give a role / take it away' to the add/remove action enum and the role_id target, adding some meaning over the schema. But it says nothing about user_id or guild_id resolution, 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 gives a specific verb and resource ('Give a role to a member, or take it away'), clearly stating that it manages member-role assignment rather than editing the role object itself. It is distinguishable from discord_edit_role/discord_delete_role, though it never names a 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?

It states the prerequisite permissions ('Needs Manage Roles, and the bot's own top role must sit above the role being assigned'), which is useful for deciding whether the call can succeed. However, it gives no when-to-use/when-not guidance and never points to an alternative tool.

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

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

Annotations already mark this as a non-read-only, idempotent, non-destructive open-world mutation, so the safety profile is covered. The description adds real value beyond them: the required permission level, a human-confirmation requirement, and the shape of the confirmation returned. It omits failure behavior (e.g. target above the bot's role hierarchy), keeping it short of a 5.

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

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

Three short lines: purpose and duration bound first, lift semantics second, permission/confirmation third, return value last. No filler sentences and every line carries 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 only a pointer, which the description provides. Permissions, confirmation, mutation semantics and the lift case are all covered; only error/edge-case behavior is absent, which is a minor gap for a 4-parameter 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 75%, with minutes, reason and guild_id already documented in the schema, including the 0-lifts-timeout and 40320-max semantics the description repeats. user_id has only a pattern and no prose in either place, so the description does not compensate for the remaining 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 (time out), the target resource (a member), the concrete effects (no posting, reacting or voice), the duration bound, and the inverse operation (minutes=0 lifts). An agent can distinguish this from discord_kick_member and discord_ban_member purely from the described effect.

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 prerequisite (Needs Moderate Members) and an explicit behavioral instruction to confirm with the user before applying, plus the lift-a-timeout case. It does not name the moderation siblings it should be chosen over, but the when-to-use context is clear.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description's note about needing 'Ban Members' permission adds useful context beyond the annotations. However, it doesn't clarify what 'Confirmation' means as a return value—the output schema may cover that, but the description is thin on behavioral detail beyond the permission requirement.

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?

Extremely concise: one sentence for the purpose and one for the permission requirement, plus a brief return note. Front-loaded and waste-free.

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

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

For a mutation tool with an output schema and annotations, the description covers the core action and permission requirement minimally. It lacks details on error handling (e.g., if user isn't banned), audit logging behavior for the reason parameter, or any caveats, leaving gaps that could affect 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 coverage is 67%, with user_id having no description but reason and guild_id documented in the schema. The description doesn't add parameter information beyond what's in the schema. Baseline 3 is appropriate given partial schema coverage and no supplementary parameter semantics in the description.

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

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

States a specific verb+resource: 'Lift a ban so the user can rejoin.' Clearly distinguishable from siblings like discord_ban_member and discord_kick_member. The 'Returns: Confirmation' line adds little but doesn't detract.

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 a prerequisite ('Needs Ban Members') but doesn't explicitly say when to use this versus alternatives, or when-not to use it (e.g., for timed bans versus permanent bans). Usage is implied rather than 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and open-world behavior, so the safety profile is covered. The description adds genuine value beyond that by disclosing the failure mode ('Error: Invalid bot token…' when DISCORD_BOT_TOKEN is wrong or missing), though the return-format sentence is largely redundant given an output schema exists.

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 lines: purpose first, then usage, then returns/errors. Every sentence earns its place and nothing is 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?

For a 0-param, read-only identity probe with annotations and an output schema, the description covers purpose, correct timing, output shape, and the auth failure case. An agent has everything needed to call it and interpret the result.

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 nothing for the description to disambiguate — the baseline for a 0-param tool is 4. No syntax, defaults, or naming ambiguities exist to explain.

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 ('Identify the bot account this server is running as') with clear scope, and no sibling tool overlaps with it — the surrounding tools all operate on channels, messages, members, or roles.

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 says when to use it ('Use first to confirm the token works') and gives the downstream reason (the bot's own user ID is needed to distinguish the bot's messages from others'). This is actionable guidance an agent can act on without inference.

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