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?

Adds substantial context beyond the annotations: the tool is a no-op unless confirm:true (critical since readOnlyHint=false would otherwise suggest immediate writes), existing rules with the same name are skipped so re-running is safe (explaining the idempotentHint), and repeat offenders get timed out, meaning members are affected, not just config. Required permissions and the Community feature gate are also disclosed.

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

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

Front-loads what the tool creates, then immediately states the preview-by-default contract in caps, followed by idempotency and prerequisites. Every sentence carries distinct operational information with no filler.

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

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

Given an output schema (so return shape needs no explanation), three simple params, and mutation semantics, the description covers everything an agent needs: what gets created, that nothing happens without confirm, that reruns are safe, and what permissions the operation requires.

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

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

Schema coverage is 100%, so guild_id, confirm, and alert_channel_id are already documented in the input schema. The description reinforces the confirm/preview contract but says nothing about alert_channel_id or its omission semantics, adding no parameter meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb (create) and a precisely scoped resource (a baseline set of AutoMod rules), and enumerates exactly what the baseline contains: invite-link blocking, scam/phishing keyword blocking, mention-spam blocking, and timeouts for repeat offenders. This clearly separates it from sibling tools like discord_create_automod_rule (single rule) and discord_list_automod_rules.

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

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

Gives concrete conditions: use this to establish a whole baseline 'in one call', a preview is returned by default, and the caller must re-invoke with confirm:true to apply. Prerequisites (Manage Server and the Community/AutoModeration feature) and the re-run safety are stated. It does not explicitly name discord_create_automod_rule as the alternative for one-off rules, so routing to siblings is only implied by 'in one call'.

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 past the annotations: discloses that preview is the default, that renames happen one at a time with per-entity failure isolation and per-entity results, the permission requirements (Manage Channels, plus Manage Roles for roles), that only name text changes because Discord cannot apply a custom font, and that channel IDs/links survive renaming. None of this is recoverable from idempotentHint/destructiveHint/openWorldHint.

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

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

Front-loads purpose, then the critical preview-by-default constraint in caps in the second sentence. Each remaining sentence covers a distinct risk (partial failure, permissions, font misconception, link stability) with no 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?

An output schema exists, yet the description still flags per-entity results, which is the piece an agent needs to interpret that output. For a multi-entity mutation gated behind confirm, permission requirements and failure semantics are both covered, leaving nothing essential 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 baseline is 3; the description earns a bump by explaining the confirm gate semantics and the blast radius of what gets renamed. It adds little on theme enum values or keep_plain matching beyond the schema, but the confirm behavior is genuinely clarified.

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

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

States a specific verb, resource set, and scope: 'Rename existing channels, categories and roles in a server to a Unicode-styled theme.' That bulk, server-scoped framing distinguishes it from the singular styling siblings (discord_style_name, discord_style_preview) 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 preview-by-default / 'Re-call with confirm:true to apply' pattern is explicit workflow guidance an agent can act on immediately. It stops short of naming alternatives (e.g. discord_style_preview for a single name, discord_list_name_styles for palette choice), so routing between siblings is left to inference.

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

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

Goes well past the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): discloses name-based idempotency and skip semantics, execution ordering across the three plan sections, per-step failure isolation with resumability, required permissions, and a 60-second duplicate-suppression window. These are exactly the behaviors an agent needs before applying a mutation.

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

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

Front-loads the preview-by-default behavior, which is the single most decision-relevant fact, then layers idempotency, ordering, failure handling, permissions, and scope boundary. Six dense sentences, none redundant.

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

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

A destructive-capable mutation with a nested plan schema and an output schema; the description covers safety (preview default), reversibility (idempotent repair), failure semantics, auth prerequisites, and rate limiting. Return values are covered by the output schema, so no 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 75% and the nested plan object is heavily documented, so the baseline is 3. The description adds real semantics the schema does not carry: that confirm gates preview vs. apply, that plan entries are matched by name for idempotent skipping, and that section order dictates execution order.

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: builds server structure against a live guild from a plan, distinguishing it from planning-only siblings by emphasizing that it applies to the live server. The final sentence explicitly bounds scope ('cannot create a new Discord server') and routes to discord_architect_explain_limits.

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

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

Gives the exact invocation path: call once for a preview, re-call with confirm:true to apply. States the precondition (Manage Channels and Manage Roles) and names the sibling tool to use instead when the intent is out of scope. There is also guidance on re-running after failures.

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' plus the crucial safety detail that unplanned server items are 'candidates for removal, never removed automatically.' That non-obvious guarantee is real added value beyond the annotations; it stops short of 5 only because it says nothing about scale, pagination, or cost of the diff.

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

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

Two tight sentences: the diff semantics and result buckets come first, the safety caveat second, the usage guidance last. No filler or restatement of the tool name.

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

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

An output schema exists, so return shape needn't be described, and the read-only profile is covered. The remaining gap is that the deeply nested plan format is left entirely to the schema, which is acceptable but means the description doesn't help an agent construct a valid plan.

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

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

Schema coverage is 50% and the nested plan object has no top-level description, so the description must carry weight. It does frame 'plan' as a desired-state spec being compared to live state, which helps, but it adds nothing about role keys, theme styling, categories, or system channel slots that the nested schema defines.

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: diffs a plan against the live server, and enumerates the three result buckets (missing/would-be-created, existing, present-but-unplanned). This clearly separates it from mutation siblings like discord_architect_apply and discord_architect_repair.

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

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

Gives concrete usage triggers: answer 'what would change?' and detect drift before repairing a half-finished build, which implicitly routes the agent to repair afterward. It does not explicitly name a sibling tool or state when not to use it, so it falls short of a 5.

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

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

Goes well beyond the annotations by disclosing the required permission level and the downstream limitation that a bot cannot consume the produced template code — neither of which is derivable from readOnlyHint/destructiveHint/openWorldHint. The return-value sentence is slightly redundant with the existing output schema, keeping it from 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?

The permission requirement and the human-only application caveat are front-loaded where an agent will read them first, and no sentence is filler. The final sentence about return values is mild duplication of the output schema, a minor economy loss.

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, low-destructiveness creation tool with an output schema, the description covers purpose, permission gate, and the most important failure mode (bots can't redeem the code). Only the sibling-alternative guidance is missing, which is what keeps it off a 5.

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

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

Schema coverage is 100% and all three parameters carry their own descriptions, so the schema does the heavy lifting. The description adds a little framing ('from the current server') but does not clarify the name-vs-guild_id relationship or note that guild_id is the source server rather than a target, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a Discord guild template') plus what the artifact captures (channels, roles, permissions) and what it produces (a shareable code). This clearly separates it from siblings like discord_architect_list_templates, discord_architect_delete_template, and discord_export_structure.

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

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

Gives an explicit precondition ('Requires Manage Server') and a critical usage boundary: the resulting code cannot be applied by a bot, only by a human in the Discord client. It does not, however, point to alternatives such as discord_export_structure or discord_architect_apply for bot-driven replication, so the sibling routing is left to inference.

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

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

Goes well beyond destructiveHint=true: it discloses that message history is permanently lost, that deleted roles are stripped from every member, that a literal 'CONFIRM DELETE' is required or nothing is deleted, that deletions are sequential with per-entity failure reporting, and which Discord permissions are needed. This is the kind of consequence detail an agent needs before an irreversible mutation.

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 tight sentences, front-loaded with the action and the irreversibility warning before mechanics and permissions. No filler; each sentence carries a distinct fact.

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

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

Covers consequences, gating, permissions, and failure behavior adequately for a destructive bulk operation, and an output schema exists so return values need not be described. The unexplained 'plan' mode, which has no corresponding parameter, is the one loose end.

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

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

Schema coverage is 100%, so the schema already documents guild_id, channel_ids, role_ids and the exact confirmation constant; the description mostly restates the confirmation behavior. It also references being 'driven by a plan', but no plan parameter exists in the schema, which adds ambiguity rather than 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 and resource set (delete channels, categories and roles) plus the two input modes (plan-driven or explicit IDs), so the agent knows it is a bulk structural delete. It never names the single-entity siblings discord_delete_channel or discord_delete_role, so the boundary with those tools is left to inference.

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

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

It implies when this tool is appropriate (bulk removal of structure, or applying a plan) and reveals the preview-vs-apply mechanism, but it gives no explicit exclusions or 'use X instead for a single channel/role' routing against discord_delete_channel, discord_delete_role, or discord_architect_apply.

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

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

Goes well beyond the annotations: it names the required permission, spells out the real-world consequence of destruction ('the template code stops working immediately for anyone who has it'), and notes the confirmation return. That is exactly the extra context the destructiveHint=true flag cannot convey on its own, and nothing here 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 short sentences: action, precondition, consequence/return. The irreversibility warning is front-loaded after the action, and no sentence is 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 two-parameter deletion tool with rich annotations and an output schema, the description covers the action, the permission gate, the blast radius, and the response shape. An agent has everything needed to decide and call 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 both parameters (guild_id pattern, code) are documented in the schema. The description only reflects 'code' via 'by its code' and adds no format or constraint detail beyond the structured fields, so the baseline of 3 applies.

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

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

States a specific verb and resource with the lookup key ('Delete a guild template by its code'), which is clearly distinct from the structure-manipulation siblings like discord_architect_delete_structure and from create/list template tools. It stops short of explicitly naming or contrasting any sibling, which keeps it out of the top band.

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?

'Requires Manage Server' gives a concrete precondition, but the description never says when to choose this over discord_architect_delete_structure or the other architect tools, nor when not to delete. Usage is only implied by the resource name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds the reason behind the limit (GET /@me/guilds and POST /channels are restricted) and restates read-only in prose. It stops short of describing the shape of the explanation returned, though the output schema presumably covers that.

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

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

Three sentences, front-loaded with the purpose, then the trigger, then the workaround. The final sentence is content-dense rather than padded, though it packs API endpoints and a multi-step workflow into one long clause that could be split.

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

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

For a zero-parameter, read-only explainer with an output schema, the description supplies everything needed to decide to call it: what it answers, when to call it, why the limitation exists, and the manual workaround. No gaps remain 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?

Zero parameters, so the baseline of 4 applies; there is no argument semantics to explain. The description correctly adds nothing about inputs, keeping the call signature unambiguous.

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 subject: 'Explain what this server can and cannot do about creating Discord servers', plus the reason (API restriction). It is unmistakably the capability-limits explainer among the architect_* family, which otherwise plans, reads, applies, and deletes structures.

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

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

Gives an explicit trigger: use this when asked to 'create a new server'. It also supplies the when-not path in the same breath — create manually or from a template, invite the bot, then use discord_architect_apply to build the structure — naming the concrete sibling to hand off to.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so 'Read-only' merely restates structured data. The description does add real context: the listing is scoped to templates this guild created, and results carry codes, sync status, and update times, but nothing about volume, ordering, or empty-state behavior.

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

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

Two short sentences with no filler; the scope constraint and return content are front-loaded before the read-only note. Every phrase carries information.

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

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

With a single fully documented parameter and an output schema present, the description needs little else. Mentioning the returned fields is a bonus, and only ordering/pagination guidance is arguably 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% (the guild_id snowflake pattern and description are fully documented), so the baseline is 3. The description adds no meaning beyond the schema about how guild_id constrains the template list.

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 (List) and resource (guild templates), and narrows the scope to templates this server created, which cleanly separates it from discord_architect_create_template and discord_architect_delete_template. It stops short of naming those siblings explicitly, so differentiation is inferential rather than stated.

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

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

Usage is only implied: an agent can infer this is the discovery step before creating, applying, or deleting templates. There is no explicit when-to-use, no prerequisites, and no mention of the sibling template tools by name.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false; the description adds the non-redundant parts: no Discord state is touched, the output is the exact ordered steps apply would run plus every detected problem, and the plan is declarative/convergent so re-applying converges instead of duplicating. That convergence behaviour is exactly the kind of semantics annotations cannot express.

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

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

Front-loaded with the action and the no-side-effects guarantee, then the return value, then usage routing, then the declarative contract. Efficient overall, though 'without touching Discord' and 'Read-only' restate the same fact.

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

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

Output schema exists, so return formatting needn't be spelled out, and annotations cover the safety profile. The description still supplies purpose, routing and idempotency semantics, which is sufficient. Only the omission of the top-level plan branches (theme/system_channels) keeps it from being fully 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?

The reported schema coverage is 0% at the top level (the single 'plan' parameter itself is undocumented), so the description has to carry meaning. It does characterise the shape well (roles, categories, channels, permission intents) and the role-key reference model, but it omits first-class branches such as theme, uncategorized and system_channels, leaving those to the nested schema 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?

States a specific verb pair (validate and normalise) on a specific resource (server-structure plan) with an explicit scope qualifier ('without touching Discord'). It also names the sibling it feeds (discord_architect_apply, which executes the returned steps), so an agent can separate the two without inspecting schemas.

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

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

Gives an explicit routing rule: 'the tool to call first for any "build me a server" request', plus the rationale (cheapest way to show the user what would happen). The alternative and its relationship are named rather than implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces 'Read-only' while adding useful context about the returned structure composition and its compatibility with planning. It does not discuss permission requirements or rate limits, but the output schema and read-only annotation carry much of that 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 compact sentences, front-loaded with the output shape and scope, followed by usage and the read-only property. Every sentence contributes information without 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 one-parameter read operation with an output schema and read-only annotations, the description supplies the purpose, conceptual return shape, and when to use it. Nothing critical 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?

There is only one parameter, guild_id, and the schema description coverage is 100%, including the snowflake pattern and description. The description adds no parameter-level guidance beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb ('Read') and resource ('live server structure'), enumerates the returned components (categories, their channels, uncategorised channels, roles), and ties the output to the 'same shape a plan uses'. This distinguishes it from generic siblings like discord_list_channels and discord_list_roles by framing it as an architect/plan-compatible structure read.

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

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

Gives explicit use cases: 'see what exists before building' and 'hand the result back to a model that will propose a plan'. It does not name alternative tools or exclusions, but the context for when to invoke it is clear.

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

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

Adds substantial context beyond the annotations: it discloses that the tool previews by default, that read-only behavior is conditional on confirm being false, and that only missing steps are applied (reinforcing destructiveHint=false and idempotentHint=true). This materially changes how an agent would call a tool whose readOnlyHint=false would otherwise suggest unconditional mutation.

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 tight sentences in a deliberate order: what it does, when to use it, the default safety posture, then the override. No repetition of the title or schema details, and the safety-critical default is capitalized and front-loaded in its sentence.

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

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

An output schema exists, so return-shape explanation is unnecessary; the description covers the only behavioral unknowns an agent needs (preview default, confirm override, missing-steps-only scope). For a 3-parameter, nested-plan tool with strong schema coverage, nothing essential is missing.

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

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

The description gives real semantics for `confirm` ('confirm:true applies the missing steps only') and for `plan` (it is diffed against the live server), which the schema alone does not make explicit. `guild_id` is left to its schema description, which is adequate at 67% coverage.

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

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

States a specific verb and resource chain: compares a plan against the live server, reports missing steps, optionally applies them. It clearly positions itself as the repair path after discord_architect_apply, but never distinguishes itself from the closely named sibling discord_architect_compare, which also does a plan-vs-live comparison.

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

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

Explicit trigger conditions are given: 'Use this after discord_architect_apply reports failures, or when a build was interrupted.' For a fresh, non-interrupted build the agent can infer to use apply instead, but the overlap with discord_architect_compare is not addressed, leaving one real ambiguity unresolved.

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?

Beyond the annotations (idempotentHint=true, destructiveHint=false, openWorldHint=false), the description discloses that the message will not be sent again, that the result reports whether the task existed, and that only in-process tasks are affected. Those scope and outcome details are exactly what an agent needs before calling a cancel operation; it does not contradict 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, front-loaded with the action and effect, then the return semantics, then the scope limitation. Every sentence carries distinct information with no filler.

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

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

Single required parameter, output schema present, and annotations covering the safety profile. The description still adds the non-obvious in-process scope caveat and the existence-check return behavior, which is more than 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 coverage is 100% and the task_id property already documents its origin ('Task ID returned by discord_schedule_message'), so the description adds no format or edge-case detail beyond restating 'by its task ID'. Baseline 3 is appropriate when the schema carries the semantics.

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

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

States a specific verb and resource ('Cancel a scheduled message by its task ID') and names the exact identifier used, which cleanly separates it from discord_schedule_message and discord_list_scheduled_tasks. An agent can identify the operation without opening the schema.

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

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

The scope note ('Only affects tasks created in this server process; a durable external scheduler is not reachable from here') is an effective when-not constraint that prevents wasted calls, and the parameter points back to discord_schedule_message as the source of the ID. It stops short of explicitly naming the sibling to use for other scheduler types, so not 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 and openWorldHint, so "Read-only" is redundant, but the description adds real behavioral context: a per-tool verdict is returned and channel visibility is checked alongside permissions. The fail-early framing explains the intended contract. No rate-limit or error-shape detail, but the output schema covers returns.

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

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

Front-loaded with the core behavior, followed by two short clauses on read-only and timing. Efficient overall, with only the redundant "Read-only." sentence not earning its place against the annotations.

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

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

For a read-only preflight check with fully documented params and an output schema, the description covers what is checked, on what scope, and when to call it. 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 coverage is 100% and all three parameters carry descriptions, so the schema does the heavy lifting. The description mirrors the parameters (guild, tool names, target channel) without adding format or semantics beyond them, which is the baseline 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?

States a specific verb and resource: for a guild plus a list of tool names, report per-tool whether the bot holds the needed permissions and whether the channel is visible. That is clearly distinct from channel-wide or bot-wide permission siblings, though no sibling is named explicitly.

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

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

"Use this before a multi-step operation to fail early with an actionable message instead of partway through" gives a concrete trigger condition. It doesn't state when not to use it or point at alternatives like discord_get_channel_permissions or discord_get_bot_permissions.

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

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

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?

The annotations already declare readOnlyHint=true and openWorldHint=true, and the description confirms read-only plus discloses exactly what the diff surfaces (presence deltas, role deltas, permission overwrite deltas). It does not cover behavioral edges the agent would want, such as what happens if guild_id does not match backup.guild_id, or whether required bot intents/permissions affect the comparison. Useful added context, but not complete.

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

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

Three short sentences: purpose and scope first, then the safety note, then the usage trigger. Nothing redundant and no filler.

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

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

With an output schema present, the description need not explain the diff response shape, and it correctly avoids doing so. For a tool taking a deeply nested backup object, the remaining gap is provenance/validation of that object, which the description leaves implicit.

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

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

Schema description coverage is only 50%: guild_id is documented in the schema, but the large nested 'backup' object is undocumented there, and the description only calls it 'a structure backup'. It never states the backup must carry format 'discord-mcp-ultimate/structure-backup@1' (typically produced by discord_export_structure) or whether the passed guild_id must match the backup's guild_id. It adds framing but does not compensate for the coverage gap.

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

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

States a precise verb and comparison ('Diff a structure backup against the live server') and enumerates the exact classes of change reported: channels/categories present in one but not the other, roles added or removed, permission overwrites that differ. That is well beyond tautology. It stops short of a 5 because it never differentiates itself from the near-identical sibling discord_architect_compare, leaving the agent to guess which comparison tool to pick.

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

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

Gives concrete when-to-use triggers: answering 'what changed since the backup?' and checking drift before restoring. That is clear situational context. No explicit when-not-use case or named alternative (e.g. 'use discord_read_structure to inspect without a backup'), so it falls short of a 5.

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

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

Annotations already 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 state that this is a non-read-only, non-idempotent, non-destructive write. The description adds meaningful behavioral context: the permission gate, feature availability requirement, trigger-type meanings, action requirements, and that the created rule is returned.

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 dense but front-loaded and every sentence carries useful information. It covers permissions, trigger types, action requirements, and return behavior without 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 complex 15-parameter tool with full schema descriptions and an output schema, the description supplies enough high-level context to call it correctly. It does not need to restate every schema-level parameter constraint.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds useful cross-parameter guidance: keyword triggers pair with keyword_filter/regex_patterns, mention_spam uses mention_total_limit, send_alert_message needs channel_id, and timeout needs duration_seconds.

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 AutoMod rule.' This clearly distinguishes it from sibling tools such as discord_edit_automod_rule and discord_delete_automod_rule.

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 important usage preconditions: Manage Server permission and the AutoModeration/Community feature. It does not explicitly name edit/list/delete alternatives, but the create context is clear.

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

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

Annotations already 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?

Beyond annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses the permission gate, a server-wide quota tied to boost tier, the failure mode ('rejects the upload with a clear error once the cap is reached'), and accepted image forms and size limit. That is exactly the operational context annotations cannot carry.

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

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

Front-loaded with the action, then constraints in roughly the order the agent will hit them (name rule, image input, permission, quota). Four sentences, no preamble, and the closing 'Returns the created emoji' is the only mild redundancy given an output schema exists.

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

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

For a mutating tool with a rich schema, output schema and annotations, the description covers permissions, quota, input formats and failure behavior, which is most of what an agent needs. The gaps are the undisclosed role_ids restriction (a real behavioral choice about who can use the emoji) and the 256 KB vs 10 MB size discrepancy that should be reconciled.

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 restates the name rule and the image format options but adds no new semantics. It also never mentions role_ids (scoping the emoji to roles) or reason (audit log), and its '256 KB' limit conflicts with the schema's 'max 10 MB', leaving the agent with two different size ceilings.

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: 'Upload a new custom emoji to the server.' The word 'new' plus the resource 'emoji' cleanly separates it from discord_edit_emoji, discord_delete_emoji and the parallel discord_create_sticker (different resource), so an agent can pick it without opening the schema.

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

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

It gives usable preconditions ('Requires Manage Expressions', boost-tier emoji cap with a clear error) which tell the agent whether the call can succeed. It stops short of naming alternatives (e.g., discord_list_emojis to check the current count/cap, discord_edit_emoji for modifications), so routing 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 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?

With only a title annotation, the description carries the full behavioral burden and does so well: it discloses the multi-step side effects (embed post, reaction adds, config write), the runtime dependency on the bot process, and the pre-flight role-hierarchy rejection before anything is posted. That is exactly the kind of context annotations would otherwise 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?

Three sentences, front-loaded with the core action and effects, followed by the operational prerequisite and the failure boundary. No filler; every sentence contributes.

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

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

An output schema exists, so return values need no explanation, and the description covers the mutation's key behavioral facts. It stops short of saying what happens on partial failure or whether existing mappings/menus on the message are preserved, which would matter for a config-writing 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 83%, so the schema already documents title, entries, emoji, label, description, and IDs. The description reinforces 'one or more emoji→role mappings' and ties the role-hierarchy rejection to role_id, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Attach one or more emoji→role mappings to a message so members self-assign roles by reacting', then enumerates the concrete side effects (posts embed, adds reactions, records mappings). This clearly separates it from siblings like discord_add_reaction (single reaction) and discord_list/delete_reaction_role_menu.

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 strong operational prerequisite: the bot must be running via `npm run bot`, and clarifies the tool only writes configuration. It also states a refusal boundary (roles at or above the bot's highest role are rejected). It does not explicitly name sibling alternatives such as discord_add_reaction or discord_delete_reaction_role_menu, so it falls short of a 5.

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

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

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?

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, open-world write. The description adds meaningful context beyond that: the Manage Events permission requirement and the shape of the return (new event's name and ID). It doesn't discuss duplicate-event behavior or what happens on permission failure, which keeps it below a 5.

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

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

Three sentences, no filler: action, conditional requirements, permission + return shape. The most decision-relevant 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?

No output schema exists, and the description compensates by naming the return fields. It covers the entity-type branching, permissions, and result. Minor gaps: no note on optional image/description fields or rate limits, though the schema handles the former.

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 every parameter, including the entity_type enum itself stating the same channel_id / location + scheduled_end_time conditions. The description restates that cross-field requirement in one place, which is mildly useful but largely duplicative of structured data.

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

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

Opens with a specific verb+resource ('Create a scheduled event'), which cleanly separates it from the list/get/edit/delete scheduled-event siblings. It doesn't explicitly name those siblings, but the create semantics are 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?

Gives clear conditional guidance tied to entity_type: channel_id for VOICE/STAGE_INSTANCE, location + scheduled_end_time for EXTERNAL. No explicit 'use X instead' routing against siblings, so it stops short of a 5, but the context is 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?

Annotations only declare it is a non-idempotent, non-destructive write; the description goes further by naming accepted and rejected media formats, the permission gate, the boost-tier quota, and that the created sticker is returned. That is exactly the kind of context annotations cannot express.

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

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

Front-loaded with the action, then constraints, then return behavior — every sentence carries information. The closing "Returns the created sticker" is slightly redundant given an output schema exists.

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

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

With 100% schema coverage, annotations, and an output schema, the description only needs to supply format rules, permissions, and quota limits, which it does. It omits any mention of the audit-log `reason` field and the guild_id scoping, both minor given the schema documents them.

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 name length, comma-separated tags, and image source formats are already documented; the description mostly restates them. The one genuine addition is the GIF-rejection constraint, and it says nothing about the optional `reason` or `description` parameters.

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

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

States a specific verb and resource: "Upload a custom sticker to the server," which unambiguously separates it from edit/delete/list sticker siblings and from emoji creation. It does not explicitly name an alternative tool, so it stops short of full sibling differentiation.

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

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

Gives real preconditions: "Requires Manage Expressions" and "Discord caps the sticker count by boost tier," plus the negative rule that GIFs are rejected at upload. It never states when to use a different tool (e.g., edit_sticker to modify an existing sticker) or what to do if the cap is hit.

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 and non-idempotency, but the description adds real context beyond them: the operation is irreversible with no Discord-side undo, a specific permission is required, and the tool reports which rule was removed. It also explains why the usual destructive-tool caution about lost member data doesn't apply here.

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

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

Three sentences, front-loaded with the action and the irreversibility warning, with no filler. The final sentence packs two ideas (no undo, returns which rule was removed) into one clause chain, which slightly muddies the closing point.

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

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

For a 3-parameter destructive tool with full schema coverage and an output schema, the description supplies exactly the missing pieces: permission requirement, irreversibility, absence of undo, and the safety rationale. Nothing an agent needs before invoking it is absent.

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

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

Schema description coverage is 100%, so guild_id, rule_id, and the optional audit-log reason are fully documented in the schema. The description adds no parameter-level detail such as snowflake format or what the audit-log reason is used for, so the baseline 3 applies.

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

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

The opening sentence names a specific verb and resource ("Delete an AutoMod rule"), which is unambiguous against siblings like discord_edit_automod_rule or discord_list_automod_rules. It never explicitly names an alternative tool, so it lands at clear-but-not-differentiated rather than 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 states the permission prerequisite ("Requires Manage Server") and pre-empts the obvious question of whether a confirmation step is needed by explaining why no preview exists. It stops short of explicitly routing the agent (e.g. "use discord_list_automod_rules first to obtain rule_id") or naming when to prefer edit over delete.

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?

Annotations already declare destructive=true and idempotent=false, but the description goes well beyond them: it explains the concrete blast radius (image gone, every :name: reference renders as unknown), the required permission, the managed-emoji rejection path, and the return value. That is precisely the context an agent cannot derive from hints.

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 action and the irreversibility warning before permissions and edge cases. No filler and no repetition of the title or annotation flags.

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 3-parameter mutation, everything an agent needs to call it safely is present: permission gate, managed-emoji failure mode, irreversibility, and outcome. An output schema exists, so the brief mention of the returned name is sufficient rather than required.

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 emoji_id, guild_id, and the audit-log reason are fully documented in structured data; the description adds no parameter-level detail. Baseline 3 applies since the schema is already carrying that 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?

Opens with a specific verb+resource pair ("Delete a custom emoji") that cannot be confused with siblings such as discord_edit_emoji, discord_create_emoji, or discord_delete_sticker. The scope is narrowed further to custom (non-managed) emojis, which is the exact distinction an agent needs.

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

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

Gives concrete preconditions and exclusions: requires Manage Expressions, and managed emojis created by an integration will be rejected so must not be attempted. It does not explicitly name a sibling as the alternative (e.g., discord_edit_emoji), 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 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?

With destructiveHint=true already declaring the safety profile, the description adds genuinely useful context: exactly what is destroyed (all mappings for one message), what is explicitly preserved (the message), and how to interpret a no-op result (returns 0 rather than a success signal). That last point is important behavioral nuance beyond the 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?

Three short sentences with zero waste. Scope comes first, then the preservation caveat, then the return-value nuance — all 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 destructive mutation with annotations and an output schema, the key behavioral facts are covered: what is removed, what is not, and how to read a zero result. The only missing piece is parameter-level explanation, which matters more here because schema coverage is 0%.

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

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

Schema description coverage is 0%, so the description must carry the burden of explaining the three parameters. It only hints at message_id via 'one message'; it says nothing about channel_id or the optional reason field, so an agent gets no added meaning beyond the parameter names and ID 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?

States a specific verb ('Remove') and resource ('reaction-role mapping') with explicit scope ('attached to one message'). It also distinguishes from the nearest alternative by clarifying 'The message itself is left alone', so an agent can tell this apart from discord_remove_reactions and discord_delete_message without opening either schema.

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

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

The context is clear: this targets reaction-role mappings for a single message, and the note that the message is preserved implicitly steers agents away from delete_message. It does not explicitly name sibling tools or state prerequisites/permissions, but the when-to-use condition is unmistakable.

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.