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

Annotations already declare idempotentHint=true, and the description reinforces this with a concrete explanation of the idempotent behavior. It adds valuable context beyond the annotations by stating the required permissions and that the action is performed as the bot. There is no contradiction with any 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 sentences, each carrying distinct useful information: action, permissions, undo path, and idempotency. The core action is front-loaded, and there is no redundant or filler wording.

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

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

For a simple three-parameter action with no output schema, the description covers the essential context: what it does, what permissions are needed, how to undo it, and its idempotent nature. The schema already documents parameter formats, so nothing important is missing for an agent to invoke this correctly.

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

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

The schema covers all parameters with descriptions, including emoji format ('name:id' for custom emojis) and snowflake patterns for IDs. The description adds little parameter-specific meaning beyond 'single emoji reaction', but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

States a specific verb and resource: adds a single emoji reaction to a message as the bot. The phrase 'as the bot' clarifies the acting identity, and 'single emoji reaction' disambiguates it from broader message actions. This clearly distinguishes it from related siblings like discord_remove_reactions and discord_get_reactions.

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

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

Provides explicit permission requirements (Add Reactions and Read Message History), which tells the agent when the tool is usable. It also names discord_remove_reactions as the undo alternative, giving clear routing for the reverse operation. It does not discuss choosing this over sending an emoji in a message, but that is not a strong competing alternative.

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

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

The description adds meaningful behavioral context beyond the annotations: the Manage Roles permission requirement, the role hierarchy restriction, and the concrete effect of idempotency (assigning an already-held role has no effect). These details are not present in the raw annotations, which only flag idempotentHint.

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

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

Three sentences, each earning its place: the action, the preconditions, and the idempotency/undo behavior. It is front-loaded with the core purpose and contains no filler.

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

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

For a straightforward role-assignment tool, the description fully covers the necessary execution context: required permission, hierarchy constraint, idempotent behavior, and the inverse sibling. No output schema exists, but the description covers the aspects that matter for invoking the tool correctly.

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

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

The schema already covers all four parameters with 100% description coverage, which sets a baseline of 3. The description adds extra meaning beyond the schema by clarifying that the role must be an existing role and must sit below the bot's highest role, directly constraining the valid role_id values.

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

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

The description uses a specific verb and resource: 'Assign an existing role to a member.' It also distinguishes from the obvious sibling by naming discord_remove_role as the undo operation, so an agent can immediately tell this tool apart from related role and member tools.

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

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

It states clear preconditions for use: requires the Manage Roles permission and the role must be below the bot's highest role. It also points to discord_remove_role as the inverse operation. It stops short of explicitly listing when not to use this tool versus other role-related tools, but the undo hint and role constraints provide solid guidance.

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

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

Annotations declare readOnlyHint true, and the description reinforces it with 'Read-only.' It adds meaningful behavioral context: only channels with overwrites are included, names are resolved, and the return shape is { channels: [...] } with channel, channelId, and overwrites. No annotation contradiction.

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

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

Four short sentences, each earning its place: purpose/scope, read-only nature, return shape, and routing to the sibling tool. The key action is front-loaded, and there is no redundant filler.

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

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

For a read-only audit tool with one schema-documented parameter and an output schema, the description covers the essential behavior, return payload, and alternative usage. An agent has everything needed to invoke and interpret the result 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 schema already fully documents guild_id. The description does not need to add parameter details; it simply aligns 'server-wide' with the guild scope. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

Opens with a specific verb and resource ('Generate a server-wide permission report') and precisely scopes its behavior to channels with overwrites, listing roles/members with allowed/denied permissions. This makes it clearly distinct from the many permission-related sibling tools.

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

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

Explicitly names the alternative tool for a narrower use case: 'Use discord_get_channel_permissions for a single channel.' It also implies when to choose this tool (server-wide audit) versus per-channel lookup, leaving no ambiguity.

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 destructiveHint=true and readOnlyHint=false, and the description adds exactly the kind of context the rubric asks for: what gets destroyed (recent messages via bulk-delete), the auth/permission requirement, the role-hierarchy constraint, and the audit-log side effect. Everything disclosed is consistent with the annotations; idempotentHint=true aligns with the 'blocking re-entry' state model. No contradiction.

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

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

Four sentences, each earning its place: core purpose and permanence, optional destructive behavior, prerequisites plus sibling routing, and the audit-log side effect. The most decision-relevant information is front-loaded before alternatives and side effects, with zero filler.

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

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

For a mutation tool with 100% schema coverage, annotations carrying the safety profile, and no output schema, nothing essential is missing. An agent knows what the operation does, what it destroys, what permissions are needed, how to reverse it, and the non-permanent alternative — all required to invoke it correctly.

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

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

Schema description coverage is 100%, so every parameter (reason, user_id, guild_id, delete_message_days) is already fully documented in the schema. The description loosely ties 'bulk-deletes their recent messages' to delete_message_days and 'audit log' to reason, but it adds no new semantic detail beyond what the schema provides. The baseline 3 for high coverage is appropriate.

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

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

The description opens with a specific verb and resource — 'Ban a user from the server' — and adds the defining effect, 'blocking re-entry until unbanned.' It also distinguishes itself from nearby siblings by name (discord_unban_member, discord_kick_member), so an agent can differentiate the operation without opening any schema.

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

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

The description explicitly routes to alternatives: 'Use discord_unban_member to reverse, or discord_kick_member for a non-permanent removal.' It also states the hard prerequisites upfront — 'Requires the Ban Members permission, and the bot's top role must outrank the target's' — leaving no ambiguity about when this tool is applicable.

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

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

Annotations already declare destructiveHint=true, so the description's safety warning reinforces rather than repeats it. The description adds valuable behavioral details: dry_run defaults to true for safe preview, requires Ban Members and Manage Server permissions, returns counts of banned vs failed users, and fails wholesale with an error if no user can be banned. This goes beyond what the annotations provide, though it doesn't specify the exact error shape or response format.

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

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

Four sentences, all information-dense with no filler. The critical safety instruction (dry_run default) is front-loaded, followed by permissions, return values, and the sibling comparison. Every sentence earns its place.

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

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

This is a destructive bulk operation, and the description covers prerequisites (permissions), safety workflow (dry-run), behavior (counts, wholesale failure), and routing (sibling tool for single bans). The output schema is absent, but the description's mention of returned counts and error behavior compensates enough. The 200-user max and delete_message_seconds bounds are already in the schema. Nothing critical 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 schema already documents all five parameters thoroughly. The description adds cross-parameter context: it explains the safe-by-default workflow tying dry_run to the overall call behavior, and mentions the 200-user API limit context. It doesn't add per-parameter details beyond the schema, but it highlights the most important behavioral parameter (dry_run) and the safety implications.

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 ('many users in a single call'), with an explicit intended use case ('raid mitigation'). It distinguishes itself from discord_ban_member by naming the sibling and the condition for choosing it (single ban with finer control).

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

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

Provides explicit when-to-use guidance: use for raid mitigation and bulk banning; use discord_ban_member for a single ban with finer control. It also gives a clear workflow: call with dry_run first to preview, then re-call with dry_run:false. This is actionable routing for an agent.

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

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

Goes well beyond the destructiveHint=true annotation by disclosing irreversibility, the dry_run safe-by-default behavior, the 14-day Discord restriction, the required Manage Messages permission, and the return value. This gives an agent a complete behavioral picture before invoking a destructive operation.

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

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

Four compact sentences, each carrying unique essential information: purpose, irreversibility, safe dry_run workflow, platform constraint, permission, and return value. 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?

For a destructive multi-parameter tool with no output schema, this description is complete: it covers prerequisites, constraints, safety workflow, side effects, and outcome. An agent has everything needed to invoke it correctly and avoid accidental deletion.

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 the description mostly reinforces the dry_run behavior already documented in the schema. It adds a useful preview-then-delete workflow, but does not substantially redefine or extend the parameter meanings beyond what the schema already provides.

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 action, resource, and scope: 'Permanently delete multiple recent messages in one call.' This clearly distinguishes it from single-message deletion tools like discord_delete_message and other message operations.

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 clear contextual guidance: use for bulk deletion of recent messages, respect the 14-day Discord limit, and run with dry_run first to preview before actual deletion. It does not explicitly name the alternative single-delete tool or state 'do not use for one message,' but the context is strong enough for an agent to choose correctly.

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

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

The description adds meaningful behavioral context beyond the annotations: the permission requirement, the returned payload (cloned channel's name and ID), and the precise copy scope including the explicit non-copying of messages. This supplements rather than contradicts the annotations — readOnlyHint=false aligns with creating, destructiveHint=false aligns with a non-destructive clone.

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

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

Three concise sentences deliver action, scope, prerequisite, and return value with zero filler. The action and scope are front-loaded, and every sentence earns its place.

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

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

With no output schema present, the explicit return value statement is a necessity and is provided. The only notable gap is that the description is silent on whether the clone preserves the source channel's type or category placement, which an agent might reasonably assume; this is a minor ambiguity for an otherwise well-covered 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%: both channel_id and new_name are already documented in the schema, including the default behavior of new_name. The description's mention of "name" in the copied scope loosely ties to new_name, but this is a marginal addition beyond what the schema already conveys, 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?

"Create a copy of a channel" states a specific verb and resource, and the description goes further by enumerating exactly what is included (name, topic, permission overwrites) and excluded (messages). This scope precision clearly differentiates it from siblings like discord_create_channel (new empty channel) and discord_copy_permissions (permissions only).

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 clear applicability context: the Manage Channels permission prerequisite and the explicit "but not its messages" boundary, which tells an agent when this tool will not satisfy a request (e.g., if message history must be duplicated). However, it never names alternative tools such as discord_create_channel or discord_copy_permissions, so when-not guidance remains implied rather than explicit.

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

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

Annotations already flag destructiveHint=true, but the description adds valuable specifics beyond them: exactly what gets destroyed ('The target's existing overwrites are overwritten'), the required permission, and the return behavior ('Returns a confirmation'). This is useful context the structured annotations cannot convey, and it does not contradict the annotations.

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

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

Three tight sentences, each earning its place: the core operation, the destructive consequence, and the permission/return note. The most decision-critical information is front-loaded, with zero filler or repetition of schema content.

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

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

For a 3-parameter tool with full schema coverage and no output schema, the description covers the essential operational context: what is copied, what is overwritten, the permission gate, and the return value. Minor gaps remain — e.g., behavior when source and target are in different guilds or are different channel types — but these are edge cases beyond the core call contract.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters including the reason audit-log field and both snowflake IDs. The tool description adds no parameter-level information beyond the schema, which is the baseline-3 case.

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

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

The description uses a specific verb ('Replace'), names the resource (target channel's permission overwrites), and specifies the source ('a copy of the source channel's'). It is immediately distinguishable from siblings like discord_lock_channel_permissions or discord_reset_channel_permissions because the direction, source, and target are all explicit.

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

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

The operation semantics make the use case clear — make one channel's permissions match another's — and the Manage Roles prerequisite is stated. However, no alternatives are named or excluded; an agent choosing among overlapping siblings such as discord_clone_channel, discord_set_role_permission, or discord_reset_channel_permissions gets no guidance on when this tool is preferred over those.

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

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

Annotations already establish this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable context beyond that: the auth requirement (Manage Channels permission) and the return payload ('Returns the new channel's name and ID'), which is especially useful since no output schema exists. It doesn't cover failure modes like duplicate-name conflicts, but the added context is solid.

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

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

Three sentences with no filler: purpose, permission prerequisite, sibling routing, and return value. Every sentence earns its place, and the most decision-relevant information (what it creates and where it doesn't apply) is front-loaded.

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

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

For a moderate-complexity tool with five params, a full schema, and no output schema, the description covers the essentials: scope, permission, alternative routing, and return format. It slightly under-specifies error conditions and duplicate-name handling, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents all five parameters including defaults and constraints. The description reinforces the 'type' enum values (text, voice, category) but adds no new parameter-level information, which aligns with the baseline-3 rule for high schema coverage.

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

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

The description uses a specific verb + resource ('Create a text channel, voice channel, or category in a server') and clearly enumerates the supported channel types, which separates it from the generic title 'Create channel'. It also explicitly distinguishes itself from discord_create_forum_channel by name, so an agent can disambiguate without opening any schema.

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

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

The description gives an explicit prerequisite ('Requires the Manage Channels permission'), an explicit exclusion ('For forum channels use discord_create_forum_channel instead'), and names the exact alternative tool. This covers when-to-use, when-not-to-use, and the alternative all in one sentence.

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

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

Annotations already indicate this is a non-read-only, non-destructive, non-idempotent action. The description adds useful context beyond that by disclosing the permission requirement ('Requires the Create Instant Invite permission') and stating the output ('Returns the invite URL'). It does not cover failure or rate-limit behaviors, but the added auth prerequisite is valuable.

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

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

The description is two sentences with no filler. The primary action and outcome are front-loaded, and the permission requirement and return value are stated without 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 well-documented parameters and no output schema, the description covers the key missing pieces: the permission needed, the invite's purpose, and the return value. The agent has enough to select and invoke this tool correctly without additional context from sibling descriptions.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters, including defaults, ranges, and special cases such as channel_id being required for external events. The description adds no additional parameter-level detail, which matches the baseline expectation of 3 for high schema coverage.

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

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

The description states a specific verb ('Create'), a specific resource ('shareable invite URL'), and a distinct target ('points to a scheduled event'). This clearly separates it from the sibling discord_create_invite, whose scope is a regular channel invite. The phrase 'so recipients land on the event when joining' further sharpens the purpose.

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

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

The description implies the use case by explaining that the invite points to a scheduled event and mentions the required 'Create Instant Invite' permission. However, it does not explicitly contrast this with discord_create_invite or state when a regular invite should be used instead, so usage guidance is inferred rather than explicit.

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

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

Annotations convey only readOnly=false, idempotent=false, destructive=false; the description adds beyond this by disclosing the authorization requirement ('Requires the Manage Channels permission') and the return payload ('Returns the new channel's name and ID'), which is valuable since there is no output schema. It does not cover failure behavior or rate limits, but the added context meaningfully exceeds 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?

Five short sentences, each earning its place: purpose, concept, permission prerequisite, sibling alternative, and return value. The core action is front-loaded and there is zero filler or 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 create operation with no output schema, the description provides the full picture: purpose, conceptual model, permission requirement, sibling routing, and return value, while the schema documents every parameter. Only minor details such as duplicate-creation behavior or rate limits are unmentioned, but annotations already signal non-idempotence.

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 name, topic, guild_id, and category_id are each already documented. The description adds no parameter-level guidance, but the baseline of 3 applies when the schema carries the full burden; no compensation is needed.

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

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

States a specific action and resource — 'Create a new forum channel in a server' — and clarifies the concept: 'A forum holds posts (threads) rather than a linear message feed.' It also names the sibling it is not (discord_create_channel for text/voice channels), so an agent can distinguish the tools 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?

Explicitly routes selection: 'Use discord_create_channel for text/voice channels instead,' and the forum-vs-linear-feed distinction defines the condition that selects this tool. The 'Requires the Manage Channels permission' prerequisite also tells the agent when the call is authorized. No inference is required.

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

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

Annotations already establish this as a write, non-idempotent, non-destructive operation. The description adds value beyond that by disclosing required permissions, the return payload (post name and thread ID), and the thread-plus-starter-message structure. It does not contradict any annotation, but failure behavior is not addressed, preventing 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?

Four short sentences, each carrying distinct value: purpose, prerequisites, alternative routing, and return value. The core action is front-loaded and there is zero filler or repetition of schema content.

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

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

Since no output schema exists, the description correctly takes responsibility for disclosing the return value (post name and thread ID), and it covers prerequisites and the most relevant sibling. Remaining gaps are minor — failure modes and invalid tag handling are not mentioned — but for a 4-parameter write tool this is largely 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 description coverage is 100%, so the baseline of 3 applies. The description adds no parameter-level detail beyond what the schema already documents — for example, title-as-thread-name and content-as-starter-message are both already stated in the schema property descriptions.

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

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

The description opens with a specific verb+resource: 'Create a new post (a thread with a starter message) in a forum channel.' The parenthetical clarifies that a forum post is a thread plus a starter message, distinguishing this tool from discord_send_message and discord_create_thread without needing to inspect 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 sibling alternative and the condition that selects it: 'Use discord_reply_to_forum to add follow-up messages,' which tells the agent when NOT to use this tool. It also states the prerequisite permissions (Send Messages and Create Public Threads) that gate invocation.

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

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

The description adds valuable behavioral context beyond the annotations: a security warning that anyone with the returned link can join the server, the required 'Create Instant Invite' permission, and the return payload. This goes well beyond the readOnlyHint/idempotentHint/destructiveHint flags and helps the agent anticipate side effects and failure conditions.

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

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

Three sentences with no filler: purpose, security caveat, permission requirement, and return value are all stated efficiently. Important warnings are front-loaded and every sentence adds information an agent needs.

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?

Despite having no output schema, the description covers the tool's purpose, key behavior, permission requirement, security implications, and return values. The remaining parameter details are fully documented in the input schema, so nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already explains each parameter thoroughly. The description's summary of 'lifetime, uses, and membership type' maps loosely to max_age, max_uses, and temporary, but adds no extra detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Create an invite link for a channel.' It clearly names the optional customization dimensions (lifetime, uses, membership type) and states what is returned (URL and code). This is enough to distinguish it from sibling tools like discord_create_event_invite.

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 communicates the clear context: invites are created for a channel, and the optional parameters control lifetime, uses, and membership type. It does not explicitly mention alternatives or say when not to use this tool, but the channel-focused wording implicitly separates it from event invites and DM tools.

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

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

Goes beyond the annotations by disclosing that the new role is placed below the bot's highest role and that the response returns the role's name and ID. Given there is no output schema, the return-value disclosure is especially 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?

Three dense sentences with no filler: the first states the action, the second covers permissions and placement, and the third provides follow-up routing and return information. Every sentence earns its place.

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

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

Provides the core operational constraints, permission requirement, follow-up step, and expected return value. It does not cover duplicate-role behavior or error cases, but the schema and annotations cover the rest sufficiently for a create operation.

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

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

Schema description coverage is 100%, so all six parameters are already documented. The description adds no parameter-level meaning beyond listing the mandatory ones, which is adequate but not exceptional.

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: 'Create a new role in a server.' It clearly distinguishes itself from sibling tools like discord_edit_role, discord_delete_role, and discord_add_role.

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 Manage Roles permission prerequisite and directs the agent to use discord_add_role for assigning the role afterward. It lacks an explicit 'do not use when' statement, but the context is clear enough for selection.

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

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

Beyond the annotations, the description adds that the Manage Events permission is required and that the response contains the new event's name and ID. Annotations already signal mutation (readOnlyHint=false) and non-idempotency, so the description appropriately fills gaps without contradicting them.

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

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

Three short sentences with no filler: the action, the key conditional parameter rules, the required permission, and the return value. Everything earns its place and the most important information is front-loaded.

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

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

For a 9-parameter tool with no output schema and conditional dependencies, the description covers the critical call-time facts: entity-type-specific requirements, the permission gate, and the return payload. The remaining details (max lengths, datetime formats, future-start requirement) are already fully documented in the input schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by synthesizing the conditional parameter relationships: 'VOICE'/'STAGE_INSTANCE' map to channel_id, and 'EXTERNAL' maps to location AND scheduled_end_time. This cross-parameter guidance is more useful than reading each schema property in isolation.

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

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

The description uses a specific verb+resource ('Create a scheduled event') and immediately clarifies the event-type branches, so the tool's purpose is unambiguous. It does not explicitly contrast itself with sibling tools like edit/delete, 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?

It gives clear conditional usage guidance: VOICE/STAGE_INSTANCE events need channel_id, while EXTERNAL events need location and scheduled_end_time, and it states the Manage Events permission prerequisite. It does not mention when-not-to-use or point to alternatives, but the conditions are concrete and actionable.

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

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

With annotations present (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description still adds substantial context: the required 'Create Public Threads' permission, the failure condition when channel_id is a thread, and the return value ('Returns the new thread's ID'). These are exactly the kind of behavioral disclosures that go beyond structured annotations.

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

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

Three sentences with zero filler: the first states purpose and mode selection, the second covers the constraint, and the third covers permission and return value. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a 4-parameter create tool with full schema coverage and a safety-relevant annotation set, the description covers everything an agent needs: the two invocation modes, the failure condition, the auth requirement, and the return value. With no output schema, disclosing the returned thread ID was an important gap that the description fills.

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

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

Schema description coverage is 100%, so the schema already fully documents all four parameters, including the enum values for auto_archive_duration and the optional semantics of message_id. The description adds only marginal value by clarifying the interplay between channel_id and message_id and the standalone-channel constraint, which warrants the baseline score of 3.

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

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

The description opens with a specific verb+resource ('Create a thread') and immediately distinguishes the two modes of operation: branching from an existing message via message_id versus standalone creation in a text channel. This clearly differentiates it from sibling tools like discord_create_channel and discord_create_forum_post without needing to name them.

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 clear operational context: when to pass message_id versus omit it, and it states an explicit constraint ('fails if channel_id is itself a thread'), which effectively warns against misuse. However, it does not point to any alternative tool (e.g., discord_create_forum_post for forum channels), so the exclusion 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?

Beyond what annotations declare (readOnly=false, destructive=false), the description discloses two non-obvious behaviors: the returned token grants unauthenticated posting power and must be treated as a secret, and the Manage Webhooks permission is required. The SECURITY warning is exactly the kind of behavioral context an agent needs to handle the result responsibly.

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

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

Three tight sentences, each earning its place: the core action and return value first, then the security caveat, then permission and downstream routing. No filler, and the most safety-critical information is given immediate prominence.

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

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

For a 3-parameter tool with no output schema, the description covers nearly everything an agent needs: purpose, return fields (id and token), the security implications of those fields, required permission, and the follow-up tool. The only minor gap is that the exact response structure/format is not spelled out, but naming 'ID and token' is sufficient for extraction.

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% — name, avatar, and channel_id each have meaningful descriptions in the schema. The tool description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies; it neither compensates nor detracts.

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

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

The description opens with a specific verb+resource pair ('Create a webhook on a channel') and states the concrete outcome (returns its ID and token). This cleanly separates it from the webhook sibling family — send, edit, delete, list — without needing to name any of them.

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 clear operational context: it names the required permission (Manage Webhooks) and explicitly routes the agent to the downstream consumer (discord_send_webhook_message) with the returned id+token. It does not state when-not-to-use or contrast with alternatives like discord_list_webhooks, but the workflow guidance is strong enough to count as clear 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?

Adds valuable behavioral context beyond the annotations: channel-type restriction, already-published precondition, permission nuances, and a returned confirmation. There is no direct contradiction with the annotations; the 'not already published' condition is a success precondition, not a claim about repeated side effects.

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

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

Three front-loaded, purposeful sentences: action, key preconditions, permissions, and return. No filler, repetition, or unnecessary detail.

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?

Complete for a two-parameter tool with no output schema. It covers what the tool does, where it works, when it cannot work, what permissions are needed, and what the caller should expect as a 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 input schema already documents both snowflake parameters with 100% coverage. The description reinforces that channel_id must be an announcement channel and message_id is the message to publish, but adds no substantial new parameter-level meaning.

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 ('Publish (crosspost)') and resource ('a message from an Announcement channel to every server that follows it'). This clearly distinguishes the tool from regular sending, forwarding, or following operations among the sibling tools.

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

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

Provides clear conditions for use: announcement channels only, message must not already be published, and required permissions. It does not explicitly name an alternative tool for non-announcement-channel messages, so it stops just short of fully explicit routing guidance.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description builds on this by specifying what is destroyed (the channel and all its messages), labeling the operation IRREVERSIBLE, describing the dry_run safeguard, and disclosing the audit-log side effect and permission requirement. It contradicts none of the annotations.

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

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

Three sentences with no wasted words: the destructive scope and irreversibility are front-loaded, followed immediately by the dry_run safeguard, then permission and audit-log context. Every sentence earns its place.

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

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

With no output schema, the description covers what the tool does, what it destroys, how to invoke it safely, who may use it, and what side effects it causes. The only gap is the return format of the dry-run preview and of the actual deletion, which is minor for a simple 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 100%, so the schema fully documents channel_id, dry_run, and reason. The description reinforces dry_run's safety role and the audit-log behavior but adds no new per-parameter meaning beyond the schema, keeping this at the high-coverage baseline of 3.

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

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

The description opens with 'Permanently delete a channel and all of its messages,' a specific verb and resource with explicit scope. The phrase 'all of its messages' disambiguates it from siblings like discord_delete_message and discord_bulk_delete_messages, which operate on messages rather than the channel itself.

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 an explicit two-step workflow: 'call it first to preview, then re-call with dry_run:false to actually delete,' and states the prerequisite 'Requires the Manage Channels permission.' It does not explicitly name alternatives or say when not to use it, so it falls just short of full routing guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the bar is lower. The description adds value by emphasizing 'IRREVERSIBLE,' the bot-only deletion constraint, and the 'Returns a confirmation' behavior. There is no contradiction with annotations.

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

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

Three short, purposeful sentences. The irreversible nature is front-loaded, followed by the critical scope limitation and return behavior. Every sentence earns its place with no redundancy or filler.

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

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

For a simple two-parameter destructive operation with no output schema, the description is complete: it identifies the exact target, states the permission boundary, warns about irreversibility, and describes the result. An agent has enough information to select and invoke this tool correctly.

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

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

Schema coverage is 100%, and both parameters already have clear descriptions in the schema. The tool description does not add extra meaning or usage details about user_id or message_id beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

States a specific verb ('Permanently delete') and a well-defined resource ('a DM message previously sent by this bot'). It clearly differentiates from generic delete_message by specifying the DM context and the bot-owned scope, so an agent can distinguish it from siblings like discord_delete_message or discord_bulk_delete_messages.

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

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

The description gives clear context for when this tool is appropriate: deleting DM messages sent by the bot. It also includes an explicit exclusion—'not the recipient's' messages—preventing misuse. However, it does not name sibling alternatives or state when to use a different tool such as discord_delete_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?

Beyond the annotations, the description adds meaningful behavioral context: the deletion is permanent and irreversible, it removes all messages in the post, and it requires the Manage Threads permission. This gives the agent important operational knowledge that annotations alone do not convey.

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

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

The description is compact and front-loaded: the core action comes first, followed by consequence, alternative, and permission. Every sentence adds distinct value and there is no redundancy or filler.

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

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

For a one-parameter destructive tool, the description is complete: it states the effect, scope, irreversibility, alternative, and required permission. The absence of an output schema is not a critical gap because the agent has enough information to invoke the tool correctly and understand the consequence.

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

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

The input schema already documents thread_id with type, pattern, and a clear description, so the schema carries the parameter semantics. The tool description adds no additional parameter-specific detail, which is acceptable given 100% schema coverage.

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

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

The description states a specific verb ('delete'), a specific resource ('forum post (thread)'), and the full scope of the action ('all its messages'). It also clearly distinguishes itself from the related update tool by naming the alternative.

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

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

The description explicitly says when to use this tool: when permanently deleting a forum post is intended. It also gives the exact alternative for a non-destructive action: discord_update_forum_post with archived:true. This is clear routing guidance with no ambiguity.

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

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

The description adds meaningful behavioral detail beyond the annotations: the operation is IRREVERSIBLE, the code is freed, it requires Manage Channels (or Manage Server) permission, and the reason is recorded in the audit log. This goes well beyond the destructiveHint and idempotentHint already provided.

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

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

Three short sentences, each carrying essential information: the primary action, the irreversibility warning, and the permission/logging context. No filler, no repetition of schema details, and key warnings are front-loaded.

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

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

The description is complete for a simple two-parameter destructive tool. It covers purpose, permission requirements, irreversibility, audit logging, and the parameter format is already fully documented in the schema. No output schema exists, but a successful delete response is not essential for an agent to invoke this correctly.

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

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

The input schema already has full (100%) coverage of both parameters, including the fact that reason is optional and recorded in the audit log. The description adds little parameter-specific meaning beyond referring to 'code' and mentioning the audit log, so the schema carries the load as expected.

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

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

The description states a specific action (revoke), the exact resource (an invite identified by its code), and the direct consequence (it can no longer be used). This clearly distinguishes it from sibling tools like discord_create_invite, discord_get_invite, and discord_list_invites.

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

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

The description provides clear context for when to use the tool: revoking an invite code that should no longer work. It also states the required permission, which helps the agent decide whether it can perform the operation. It does not explicitly name alternatives or exclusion conditions, 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?

Beyond the destructiveHint and readOnlyHint annotations, the description adds concrete behavioral details: the action is IRREVERSIBLE, permission depends on message ownership, and the optional reason is recorded in the audit log. These disclosures help an agent anticipate side effects without relying on structured fields alone.

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

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

All sentences are short and information-dense, with the core action and irreversibility warning front-loaded. The alternative-tool routing and permission note each earn their place; there is no fluff 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?

For a simple single-message delete operation, the description covers the action, destructiveness, permission requirements, the relevant alternative, and the audit-log side effect. No output schema exists, and none is needed for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, with all three parameters already documented with descriptions and patterns. The description only restates the audit-log effect of the reason parameter, already present in the schema, so it adds no new parameter-level meaning. 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?

Description opens with 'Permanently delete one specific message', a clear verb+resource+scope statement. It distinguishes itself from bulk deletion and other delete-related siblings by emphasizing 'one specific message'.

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

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

Explicitly names discord_bulk_delete_messages as the alternative for removing many messages at once. It also states the permission prerequisite: the bot can always delete its own messages, while deleting another user's message requires Manage Messages permission. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lowered; the description adds substantial context beyond that: the cascading removal from all members, explicit irreversibility, the Manage Roles permission requirement, and the hierarchy constraint relative to the bot's highest role. Nothing contradicts the annotations.

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

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

Three sentences, each earning its place: the core action, the cascade consequence, and the prerequisites/irreversibility warning. Front-loaded with the verb and resource; zero filler.

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

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

For a 3-parameter tool with full schema coverage, no nested objects, and no output schema (delete endpoints typically return nothing), the description covers every decision-critical fact: what is destroyed, side effects on members, irreversibility, permission, and hierarchy. An agent can determine whether and how to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents guild_id, role_id, and reason; the baseline 3 applies. The description adds only peripheral param context (the hierarchy constraint on role_id), not format or syntax detail beyond the schema.

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

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

States a specific verb and resource: 'Permanently delete a role from the server.' The cascade note ('automatically removed from every member who held it') disambiguates from sibling discord_remove_role, which unassigns a role from a member without deleting the role itself.

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 prerequisites ('Requires the Manage Roles permission, and the role must be below the bot's highest role') give clear conditions for when the call will succeed, and 'IRREVERSIBLE' warns against casual use. However, it never names alternatives (e.g., discord_edit_role to modify, discord_remove_role to unassign instead), leaving when-not-to-use to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description adds meaningful context: the operation is irreversible, requires the Manage Events permission, and offers a non-destructive alternative. It doesn't go into deeper edge cases, but it exceeds the minimum burden.

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

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

Three sentences, each with a purpose: statement of action, warning about irreversibility, and explicit routing to an alternative with a required parameter value. Front-loaded with the core behavior and no wasted words.

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

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

For a destructive mutation tool, it covers irreversibility, required permission, and the safer alternative. The output schema is absent, but the description need not explain return values. It could mention edge cases like 'event not found' but that's not necessary for basic invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description doesn't add syntax or format details beyond what the schema provides, but it doesn't need to. Baseline 3 is appropriate.

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

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

The description clearly states the action (permanently delete) and the resource (scheduled event). It differentiates itself from sibling discord_edit_scheduled_event by explicitly noting the alternative for cancellation, leaving no ambiguity about what this tool does.

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

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

It explicitly states when to use this tool and when not to: 'To cancel an event while keeping a record, use discord_edit_scheduled_event with status:'CANCELED' instead.' This directly guides the agent to the correct alternative and condition.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description goes beyond them meaningfully: it names what gets destroyed (the token), the consequence (integrations using the old token stop working), marks the operation IRREVERSIBLE, and surfaces the auth requirement. This directly adds the 'what gets destroyed' and 'auth needs' context the rubric credits. It is strong but not exhaustive — no mention of error behavior for invalid/nonexistent IDs or rate limits.

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

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

Three tight sentences, each earning its place: the action, the irreversibility warning with concrete impact, and the permission prerequisite. The action is front-loaded, and there is zero filler or repetition of the input schema.

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

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

For a low-complexity tool (one parameter, no output schema, annotations present), the description covers the essentials: what it does, what it destroys, irreversibility, and the required permission. The only gaps are error/return behavior (e.g., what happens on a second delete of the same webhook) and rate-limit info, which are minor for a simple destructive operation.

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

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

Schema description coverage is 100%: webhook_id is already documented as the snowflake ID of the webhook to delete, with a regex pattern. The description's phrase 'by its ID' merely restates the schema. Per the rubric, a baseline of 3 applies when the schema carries the load; the description adds no parameter-level detail 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 description states a specific verb and resource with precise scope: 'Permanently delete a webhook by its ID, invalidating its token.' The token-invalidation detail makes clear this targets the webhook resource itself, not a webhook message (discord_delete_webhook_message), so it is implicitly distinguishable. However, it does not explicitly name or contrast any sibling, falling just short of the top bar.

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 when to use the tool (when a webhook must be permanently removed) and states a clear prerequisite: 'Requires the Manage Webhooks permission.' But it offers no when-not-to-use guidance or alternatives (e.g., clarify that deleting a webhook message is a different tool). This is more than 'no guidance' but less than explicit exclusions.

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

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

Annotations already mark this as destructive (destructiveHint: true), and the description reinforces this with 'Permanently delete' and 'IRREVERSIBLE.' It also adds a meaningful prerequisite beyond the schema: the original webhook token must be used. No contradiction with annotations 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?

The description is brief and front-loads the core destructive action. There is slight redundancy between 'Permanently delete' and 'IRREVERSIBLE,' and the token requirement is repeated from the schema, but the overall structure is efficient and easy to parse.

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

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

Given the destructive annotations and complete parameter schema, the description provides enough context to invoke the tool correctly: the target resource, necessary credentials, and irreversibility. It does not describe response behavior or error cases, but no output schema exists and this is a simple delete operation, so the omission is not critical.

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

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

Schema description coverage is 100%, so all three parameters are already well documented. The description adds minimal semantic value beyond the schema, mainly clarifying that the token must be the original webhook token. This meets the baseline for fully-covered schema parameters without adding substantial meaning.

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

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

The description states a specific action — permanently deleting a message sent through a webhook — and identifies the required auth context (webhook ID and token). The phrase 'through a webhook' clearly distinguishes it from sibling tools like discord_delete_message, which handles non-webhook messages.

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

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

The description clearly implies this tool is for webhook-sent messages and emphasizes that the original webhook token is required. It does not explicitly name alternatives or say when not to use it, but the webhook-specific framing is strong enough to guide selection among the many sibling message tools.

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

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

The description adds meaningful behavioral detail beyond the annotations: partial-update semantics, text-channel-only restrictions for topic and slowmode, permission requirements, and a confirmation response. These are not visible in the annotations or schema and are especially valuable for a mutating tool.

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

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

Three short sentences with no filler. The main purpose and editable fields are front-loaded, followed by the partial-update caveat, permission requirement, and return behavior. Every sentence earns its place.

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

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

For a moderately complex edit tool with full schema coverage and no output schema, the description covers the editable fields, constraints, permission, partial-update semantics, and return value. Nothing essential 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 100%, so the baseline is 3. The description adds value by explaining cross-parameter behavior ('Only provided fields change') and the text-channel-only constraint for topic and slowmode, which the schema does not convey.

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

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

The description names a specific verb ('Update') and resource ('a channel'), then enumerates exactly which fields are editable: name, topic, slowmode, or NSFW flag. This clearly distinguishes it from sibling tools like move_channel, set_channel_position, and delete_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 makes the usage context clear: use it to update channel settings, only provided fields change, and topic/slowmode are text-channel-only. It also states the Manage Channels permission requirement. It does not explicitly name alternative sibling tools, but the field list effectively implies when this tool is appropriate.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description only needs to add context. It adds meaningful behavioral constraints: only the bot's own DM messages can be edited, and it returns a confirmation. No contradiction with annotations 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 concise sentences with no filler. The main action is front-loaded, followed by the ownership constraint, an alternative-tool pointer, and a return-value note. Every sentence earns its place.

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

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

For a simple edit operation with fully documented parameters and annotations covering safety/idempotency, the description covers the essential context: what it edits, who can edit it, when to use a different tool, and what the return is. No important calling context 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 schema already documents all three parameters, including content constraints and the max 2000-character limit. The description adds little beyond saying 'text content' and 'confirmation,' which is sufficient but not a significant enrichment.

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

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

The description states a specific action ('Edit the text content of a DM message'), identifies the resource (DM message previously sent by this bot), and scopes the tool clearly. It also explicitly distinguishes itself from discord_edit_dm_embed for embed messages.

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

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

The description gives a clear when-to-use condition ('DM message previously sent by this bot') and a when-not-to-use condition ('Only the bot's own DM messages can be edited'). It also names the alternative for embed messages: 'Use discord_edit_dm_embed for embed messages.'

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

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

The description discloses the full-replace behavior ('provided fields are applied and omitted fields are dropped'), which is a critical non-obvious trait. Annotations already indicate idempotentHint=true and destructiveHint=false, so the description's replacement semantics add meaningful context beyond annotations. It also states the return is a confirmation, which is useful. Slight gap: no mention of auth/rate limits or what happens if the message isn't found.

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

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

Three sentences with zero filler. The first sentence states the verb+resource, the second adds the critical ownership constraint, and the third crystallizes the most important behavior (full replace). Everything is front-loaded and earns its place.

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

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

Given the 100% schema coverage, the required params are clear, and the nested object shapes (author, fields) are fully documented. The description explains the full-replace semantic that the schema can't express, and the confirmation return. Minor omissions (error cases, not-found behavior) are acceptable for an edit tool with idempotentHint=true.

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

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

Schema coverage is 100%, so the schema already documents all 13 parameters. The description's 'full replace, not merge' is high-level and applies to all parameters collectively, but it doesn't add per-parameter meaning beyond the schema. This is baseline 3 territory since 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?

The description clearly identifies the specific verb ('Replace'), the resource ('the embed on a DM message previously sent by this bot'), and distinct scope ('DM message', 'previously sent by this bot'). It also differentiates from generic edit tools by specifying DM-only context and bot-owned messages.

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

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

The description states the critical when-not-to-use constraint: only the bot's own messages can be edited. It clearly implies this tool is for DM messages, distinguishing it from discord_edit_embed (which likely targets server messages). However, it doesn't explicitly name an alternative tool like discord_edit_embed or discord_edit_dm for non-embed edits, so it misses the full explicit alternative mapping.

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

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

The description discloses the critical behavioral nuance beyond the annotations: this is a full replace, not a merge, so omitted fields are dropped. It also states the bot-only restriction and that a confirmation is returned. The annotations already cover read/write and idempotency, and there is no contradiction.

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

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

The description is three sentences with no filler: purpose and restriction first, the essential replace-not-merge behavior second, and the return behavior third. Every sentence earns its place.

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

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

The schema thoroughly documents all 12 parameters, including nested objects and field limits, and the description covers scope, replacement semantics, and a return confirmation. Since there is no output schema, a slightly richer description of the confirmation payload would make it fully complete, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that omitted optional fields are cleared rather than preserved, which materially affects how an agent should construct arguments. It does not add per-parameter details beyond what the schema already provides.

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

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

The description states a specific action and resource: 'Replace the embed on a message previously sent by this bot.' It clearly differentiates this from sending a new embed or editing message text, and the 'Only this bot's messages can be edited' boundary adds precision.

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

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

The description provides a clear precondition: the target message must have been sent by this bot, which tells the agent when not to use the tool. However, it does not explicitly name alternatives such as discord_edit_message or discord_edit_dm_embed, so it stops short of full routing guidance.

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

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

Annotations only establish that this is a mutating, idempotent, non-destructive operation; the description goes well beyond them by disclosing the failure mode for non-bot messages, the threading scope, and the return value (edited message ID). Stating the return value is especially valuable given there is no output schema. No contradiction with 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?

Four short sentences, each carrying distinct information: core action, failure condition, alternative routing, and scope/return value. The primary purpose is front-loaded and there is zero filler.

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

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

For a 3-parameter tool with a fully documented schema, the description fills the gaps that structured data cannot: when it fails, which sibling to use instead, where it works, and what it returns. 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 description coverage is 100%, with each parameter already documented (snowflake patterns, bot-authorship requirement, max 2000 characters, full replacement semantics). The description adds only marginal reinforcement about channel/thread context, so it stays at the baseline 3 rather than compensating for any 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: editing the text content of a message previously sent by this bot. It additionally distinguishes itself from its closest sibling by noting 'Use discord_edit_embed for embed messages.' An agent can tell this tool apart without opening the schema.

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

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

Explicitly names the alternative tool (discord_edit_embed) and the condition that selects it (embed messages), and warns that the operation fails for non-bot messages. It also scopes where the tool works (text channels and threads). This is explicit when/when-not guidance with a named alternative.

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

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

Beyond the annotations, the description discloses critical behavior: partial updates are the default, but passing 'permissions' replaces the entire permission set. It also reveals authorization and hierarchy constraints. This is exactly the kind of behavioral context an agent needs to avoid unintended permission overwrites.

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 dense sentences with no filler. The first sentence states the tool's purpose and scope, the second explains the critical partial-update and replacement semantics, and the third covers permissions and hierarchy. Information is front-loaded and every sentence earns its place.

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

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

Given a 7-parameter mutation tool with no output schema, the description is complete enough for correct selection and invocation. It covers what changes, how partial updates work, the dangerous permissions-replacement behavior, and the required permission/position conditions. No critical gap remains.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the update contract: unspecified fields remain unchanged and permissions are replaced wholesale rather than merged. This is valuable semantic information not fully captured by the field descriptions alone.

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

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

Description uses a specific verb ('Update') and resource ('existing role'), and enumerates the exact mutable attributes: name, color, permissions, hoist, mentionable. This clearly differentiates it from sibling tools like discord_create_role, discord_delete_role, discord_set_role_position, and discord_set_role_permission.

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 clear operational context: it edits role settings, only provided fields change, and it states important prerequisites (Manage Roles permission and role position below the bot's highest role). It does not explicitly name alternatives or state when not to use this tool, but the scope is unambiguous.

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

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

Annotations already indicate this is a mutating, non-destructive, idempotent operation. The description adds valuable behavioral context beyond those hints: partial-field update semantics, status-transition restrictions, and the Manage Events permission requirement. This is meaningfully richer than the structured annotations alone.

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

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

Two sentences, front-loaded with the core action and update semantics, followed by the status-transition guidance and permission requirement. No filler or repetition of schema content.

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

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

For a complex mutation tool with 10 parameters and no output schema, the description covers the essential behavioral and permission context. Schema descriptions handle individual parameter meanings. It could be slightly more explicit about alternative tools, but it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying update semantics ('only provided fields change') and giving practical guidance on using the status field to control the event lifecycle. This adds meaning to the parameters collectively.

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 ('Update') and resource ('a scheduled event'), and adds the key semantic 'only provided fields change'. This clearly distinguishes it from sibling tools like discord_create_scheduled_event and discord_delete_scheduled_event.

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

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

The description provides clear guidance on when to use the status field for starting, ending, or canceling an event, and warns that Discord only allows certain transitions. It does not explicitly name alternatives like delete for removal, but the context is strong enough for an agent to infer the right 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?

The description adds meaningful behavioral context beyond the annotations: the Manage Webhooks permission requirement and the fact that it returns a confirmation. The annotations already signal a non-read-only, idempotent, non-destructive operation, and the description aligns with them—no contradiction.

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

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

Three short sentences, each earning its place: what the tool updates, partial-update semantics, and permission/return details. Information is front-loaded and there is no redundant wording.

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

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

For a simple 4-parameter edit tool with full schema coverage and no output schema, the description covers purpose, partial update behavior, permission, and response. It could be more specific about the confirmation's shape, but nothing essential is missing for 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?

The schema provides 100% coverage with descriptions for all parameters, so the baseline is 3. The description adds value by clarifying that only provided fields change, which is essential for understanding how to use parameters in combination. It does not restate schema details like max length or patterns.

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

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

The description states a specific verb ('Update'), a specific resource ('a webhook'), and enumerates the editable fields ('name, avatar, or the channel it posts to'). This clearly distinguishes the tool from siblings like discord_edit_webhook_message (which edits a message sent by a webhook) and discord_delete_webhook.

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 identifies what the tool does and the partial-update behavior ('Only provided fields change'), so an agent knows it can pass a subset of fields. It does not explicitly name alternatives or say when not to use this tool, but the context is clear enough for this straightforward edit operation.

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

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

Adds useful behavior beyond annotations: 'Replaces the provided fields' indicates partial replacement rather than full overwrite, and 'Requires the original webhook token' names the authentication prerequisite. Annotations already provide idempotent/read-only/destructive hints, and the description does not contradict them.

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

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

Four short sentences, front-loaded with the core operation and then the required context. There is no filler or unnecessary repetition of schema details; the token emphasis earns its place as an auth requirement.

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 three required parameters and a rich input schema, the description covers the key operational facts: target resource, replacement behavior, authentication need, and return behavior. It could be more complete with explicit sibling exclusions, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the individual parameter documentation carries the meaning. The description adds context about replacement semantics and token requirement, but does not explain specific parameters beyond what the schema already provides.

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?

Describes a specific action—editing a webhook-sent message using the webhook's ID and token—and clarifies it operates on a previously sent message. This distinguishes it from siblings like discord_edit_message and discord_edit_webhook.

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

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

Gives a clear use context: edit messages that were sent through a webhook, and states the prerequisite that the original webhook token is required. It does not explicitly name alternatives or exclusion cases, but the webhook-specific scoping makes routing unambiguous.

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

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

The readOnlyHint annotation already establishes safety, and the description's 'Read-only' line confirms it without adding new behavioral depth. It adds the return shape and pinned-message scope, but does not address pagination, rate limits, permissions, or failure behavior. This is acceptable but not exceptional given annotations already cover the key safety trait.

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

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

Three short sentences, each earning its place: the operation, the return shape, and the pointer to the mutation sibling. It is front-loaded with the core purpose and contains 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?

For a single-parameter read-only tool with a full input schema and output schema, the description covers everything needed: what it lists, what it returns, that it is safe, and which sibling to use for modifications. No critical information 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% and the single parameter channel_id is already described as a snowflake ID for a channel or thread. The description adds no additional parameter-level meaning, so the schema carries the full weight here, matching the baseline of 3.

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

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

The description uses a specific verb and resource: 'List all pinned messages in a channel.' It clearly identifies the tool's scope and differentiates it from mutation tools like discord_pin_message by explicitly stating this is read-only and directing to discord_pin_message for changing pins.

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

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

It explicitly states when to use the tool (to list all pinned messages) and gives an alternative for a related but different need: 'Use discord_pin_message to change which messages are pinned.' This is direct and leaves no ambiguity about the read-only intent.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description reinforces read-only behavior while adding valuable context: the requirement of the original webhook token and a summary of returned data (id, content, embed count, timestamp). No contradiction with annotations.

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

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

A single sentence delivers the operation, resource scope, return summary, read-only nature, and auth requirement with zero filler. Information is front-loaded 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 single-message fetch with 3 fully documented required parameters, an output schema, and safety annotations, the description covers the critical token prerequisite and operation scope. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the individual parameter descriptions already handle semantics. The tool description adds only the nuance that the token must be the 'original' webhook token, which is a minor enhancement over 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?

Clearly identifies the verb ('Fetch'), the resource ('a single message sent through a webhook'), and the scope ('using the webhook's ID and token'). The parenthetical return fields and the webhook-specific framing distinguish it from sibling tools like discord_read_messages or discord_get_message_attachments.

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 the key prerequisite 'Requires the original webhook token,' which is the primary condition for using this tool. It implicitly differentiates from non-webhook message tools, but does not explicitly name alternatives or when-not-to-use scenarios.

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 provide readOnlyHint=true and openWorldHint=true, and the input schema already documents the case-insensitive substring behavior. The description reiterates these rather than adding new behavioral context such as pagination, result limits, or error behavior. It slightly adds by stating the output shape, but with an output schema present that is already structured knowledge.

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

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

Three sentences, each earning its place: the core matching behavior, the return format, and the primary use case. No filler, front-loaded with the most important information, and well-structured for quick agent consumption.

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 annotations covering safety, the description provides everything an agent needs to decide when to invoke this tool: what it searches, how matching works, and why it is useful. There are no significant gaps for a simple read-only lookup 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 100%; both 'name' and 'guild_id' are fully described in the input schema. The description adds no extra parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Find'), a specific resource ('channels'), and a specific filter ('name contains a substring (case-insensitive)'), which clearly distinguishes it from sibling tools like discord_list_channels. It also mentions the return format and read-only nature, making the tool's scope 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 provides a clear context for use: 'Useful for resolving a channel_id when you only know the channel's name.' This gives an agent a concrete decision signal. It does not explicitly name alternatives or exclusionary conditions, but the intended scenario is clear enough.

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

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

Annotations already indicate this is a non-read-only, non-idempotent operation, so the bar for additional disclosure is lower. The description adds useful behavioral context: it requires Manage Webhooks in the target, causes published messages to be reposted, and returns a confirmation. It does not detail edge cases like duplicate follows, but that is not a major gap given the annotations.

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

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

Three short sentences front-load the core action and effect, then state prerequisites and the return value. No filler or redundant details; every sentence earns its place.

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

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

For a two-parameter tool with no output schema, this description is sufficient: it explains the operation, the required permission, the source constraint, and the response. An agent can invoke it correctly without needing additional context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's prose reinforces that the source must be an announcement channel and the target receives published messages, but it does not add substantial parameter-level meaning beyond the schema.

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

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

The description uses a specific verb ('Subscribe') and identifies the precise resource relationship: a target channel follows an announcement channel. It clearly distinguishes this from sibling tools like discord_crosspost_message by describing the subscription/reposting behavior rather than one-off publishing.

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

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

The description states the key precondition ('source must be an announcement channel') and the required permission ('Manage Webhooks'). It does not explicitly name alternatives or say when not to use this tool, but the context is clear enough for an agent to understand the appropriate scenario.

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 provide only basic flags (readOnlyHint=false, destructiveHint=false), so the description carries the burden of explaining behavior. It adds genuine value: the attribution-preservation trait of the native forward, the permission requirement, and the return behavior ('Returns a confirmation'). No contradiction with annotations exists; it could have gone further by noting failure modes, but it covers the key behavioral traits well.

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

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

Four sentences with zero filler: the core action and its defining trait come first, followed by scope, the routing alternative, and the prerequisite. Every sentence earns its place, and the return-value note is justified because there is no output schema to convey that information.

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

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

For a 3-parameter tool with no output schema, the description covers all essential decision and invocation information: what it does, where it works, the required permission, the return behavior, and the sibling to choose instead. It is slightly shy of perfect only because it omits edge-case caveats (e.g., restrictions on forwarding certain message types), but 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 description coverage is 100%, so the input schema fully documents all three parameters (channel/thread context, message ID, destination). Per the baseline rule, the description need not repeat parameter details. The small additions it makes — 'Works across text channels and threads' — merely confirm what the schema already states, so no compensatory credit is warranted.

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

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

The description opens with a specific verb and resource ('Forward an existing message to another channel') and adds the distinctive mechanism ('Discord's native forward, which preserves the original attribution'), which separates it from ordinary message-sending. It also explicitly names discord_send_message as the sibling it is not, making the purpose unmistakable even among 80+ sibling tools.

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

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

The description gives an explicit when-to-use (forwarding an existing message with attribution) and a when-not-to-use with a named alternative ('Use discord_send_message to compose new content instead'). It also states the operational prerequisite ('Requires the Send Messages permission in the target channel'), which is exactly the kind of precondition an agent needs before invoking.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only'. It adds useful behavioral context beyond the annotations by disclosing the permission requirement and the exact response shape: { entries: [...] } with named fields. This gives the agent a accurate expectation of what the call does and what it needs in advance.

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

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

The description is three compact sentences with no filler. It front-loads the core operation, then adds the permission requirement and return shape, each sentence contributing meaningful information without 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 read-only tool with one required parameter, a thorough input schema, and an output schema available, the description covers the essential operational details: what the resource is, the required permission, and the response format. Nothing needed for correct selection or 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 description coverage is 100%, so every parameter already has an explanatory description: guild_id, limit, and action_type. The tool description does not add much parameter-specific semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb and resource: 'Fetch the server's audit log', and explains what the log contains (administrative actions, who performed them, when). This clearly distinguishes it from the many sibling message/channel/member tools, since it is the only audit-log operation in the 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?

The description provides clear context for when this tool is relevant and states the required permission ('View Audit Log'), which is an important access prerequisite. It does not explicitly enumerate alternatives or exclusions, but no sibling tool offers a comparable audit-log capability, so that omission is minor.

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

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

The annotations already declare readOnlyHint=true, and the description adds meaningful behavioral detail beyond that: it discloses the exact structure of results (per role and per member, allowed and denied flags) and the comprehensive 'every permission overwrite' scope. This is useful context that annotations alone do not provide.

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

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

Two compact sentences with no filler. The core behavior is front-loaded first, the read-only property is stated briefly, and the alternative routing is in the second sentence. Every sentence earns its place.

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

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

For a single-parameter, read-only listing tool with an output schema present, this description is complete. It covers scope, result granularity, safety, and the main alternative tool. Nothing that an agent needs to select or invoke this correctly is missing.

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

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

The input schema has 100% description coverage for channel_id, including its snowflake pattern and purpose. The description only refers to 'a channel' generically, so it adds little beyond the schema. A baseline of 3 is appropriate because the schema already carries the parameter documentation burden.

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

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

Description states a specific verb ('List') and resource ('every permission overwrite on a channel'), and clearly explains the granularity: per role and per member, with allowed and denied flags. It differentiates itself from discord_audit_permissions by explicitly naming that sibling, so an agent can distinguish the tools.

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

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

It explicitly provides the alternative tool ('discord_audit_permissions') and the condition that should trigger its use ('server-wide report across all channels'). This gives clear routing guidance without needing to infer from tool names.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It goes beyond the annotation by disclosing the response shape ({ subscribers: [...], nextCursor }) and the pagination contract, including the 100-user page cap and how to pass nextCursor back as `after`.

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

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

Three concise sentences with no filler: the action is front-loaded, the response shape is stated, the pagination rule is actionable, and the read-only safety signal is included. Every sentence earns its place.

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

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

For a read-only paginated listing tool with a thorough input schema and an output schema, the description covers the essential behavior: what it returns, how paging works, and that it is safe. No critical usage aspect 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. The description adds value by explaining the relationship between the output's nextCursor and the `after` parameter, and by clarifying page-size behavior beyond the schema's default and max values.

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

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

The description opens with a specific verb and resource: 'List the users who marked themselves Interested in a scheduled event.' This clearly distinguishes it from sibling event tools like get_scheduled_event and list_scheduled_events, which target event metadata rather than subscriber lists.

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 clear context: it is for reading event subscribers, and the pagination instructions explain how to use it across multiple pages. It does not explicitly name alternatives or exclusion conditions, but the operation is specific enough that an agent can infer when to select it.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It adds behavioral context by stating the tool only returns forum channels and not tags or threads, which helps set expectations about scope. No hidden side effects or auth requirements are omitted for a simple read-only listing tool.

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

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

The description is two short sentences, front-loading the main purpose and output fields, then immediately providing read-only clarity and sibling tool alternatives. Every sentence earns its place with no fluff.

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

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

For a low-complexity read-only listing tool with a fully described parameter and an existing output schema, the description is complete. It explains what is returned, clarifies the read-only nature, and points to related sibling tools for adjacent use cases.

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

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

The schema fully documents the single parameter guild_id with a clear description and pattern. The tool description does not need to add much, and it doesn't—this is acceptable given 100% schema coverage.

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

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

The description uses a specific verb ('List') with a clear resource ('forum channels') and scope ('in a server'), and enumerates the returned fields (id, name, topic, parent category). It also distinguishes itself from sibling tools like discord_list_channels by narrowing to forum 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 explicitly tells the agent when to use alternatives: discord_get_forum_tags for a forum's tags and discord_list_forum_threads for its posts. This gives clear routing guidance beyond merely restating the tool's function.

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 declare readOnlyHint=true and the description reinforces it with 'Read-only' — no contradiction. It adds value beyond the annotations by disclosing the return shape (specific detail fields plus messages), the ordering behavior (oldest-to-newest), and that the result is a JSON object. It does not address edge behaviors like empty threads, but the output schema covers the return contract.

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

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

Four short sentences, all load-bearing: purpose with an itemized payload, ordering behavior, read-only safety, required input, and return type. Front-loaded with verb and resource; zero filler or 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 2-parameter read tool with an output schema, the description covers what it returns, what input is required, and its safety profile. An agent can invoke it correctly with only thread_id, and the limit constraints live in the schema. Nothing material 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 100% — both thread_id and limit already have descriptions covering the snowflake pattern, constraints, and default, so the baseline is 3. The description adds only marginal reinforcement by telling the agent to pass thread_id and linking 'recent messages' to the limit parameter; it does not carry the semantic burden.

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

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

States a specific verb ('Get'), a precise resource ('a forum post's details'), and itemizes the payload (title, archived/locked state, applied tags, message count, recent messages oldest-to-newest). This distinguishes it from sibling getters like discord_read_messages (general message reads) and discord_list_forum_threads (listing threads rather than fetching one post's details).

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 makes the use case clear — pull details plus recent messages for a single forum post — and gives a concrete invocation instruction ('Pass the post's thread_id') along with the 'Read-only' framing so an agent knows this is a safe fetch. It does not explicitly name alternatives or state when-not-to-use conditions, which keeps it just 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 readOnlyHint=true and openWorldHint=true, and the description restates the read-only nature rather than adding substantial new behavioral disclosures. It does add useful context about downstream usage and returned fields, but the output schema and annotations carry much of the behavioral burden.

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

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

Three short sentences, front-loaded with the primary action and followed by useful routing context. The 'Read-only' sentence is slightly redundant with annotations, but the description remains compact, scannable, and free of filler.

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

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

For a single-parameter read-only tool with an output schema and readOnlyHint, the description is complete: it identifies the result fields, names the dependent sibling tools, and clarifies the tag-management tool. No critical usage information 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% and forum_channel_id is already fully documented as a snowflake ID of the forum channel. The description only repeats 'forum channel' and adds no parameter-level 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?

The description uses a specific verb ('List'), identifies the resource ('tags available on a forum channel'), and enumerates the returned fields (id, name, emoji, moderated flag). It is clearly distinguished from sibling tools like discord_set_forum_tags and discord_create_forum_post by naming them in its usage guidance.

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

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

It explicitly frames the tool as read-only and tells the agent to use the resulting IDs with discord_create_forum_post or discord_update_forum_post, while directing tag-set management to discord_set_forum_tags. This provides clear routing among the forum-related siblings with no misleading exclusions.

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

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

Annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds a 'Read-only' statement that repeats the annotation and enumerates returned data, but does not disclose additional behavioral traits like rate limits or failure modes. This is acceptable but not exceptional.

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 with no wasted words: the first states the tool's purpose and scope, and the second points to the relevant alternative. The key information is front-loaded and every sentence earns its place.

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

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

The tool has a simple input schema, a complete output schema, and annotations covering side effects. The description covers the operation scope and even routes to the sibling tool for finer detail, making this definition complete for an agent 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%, and the single guild_id parameter is already documented with its type, pattern, and purpose. The description does not add parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get details about one server' and enumerates the returned fields (name, description, counts, boost tier, owner, creation date). It also distinguishes itself from discord_get_server_stats, so an agent can tell them apart.

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 clear context for when to use this tool and explicitly routes to discord_get_server_stats for a finer breakdown. It lacks explicit when-not-to-use conditions, but the alternative is named and the basic-vs-fine distinction is meaningful.

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