discord-mcp

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

Annotations already declare readOnlyHint=false (write), idempotentHint=false, destructiveHint=false. The description adds valuable context: upload requirements (file types, size, name pattern), the 2,000-emoji quota, and the optional `application_id` behavior. It also mentions the return format, which is partially covered by the output schema. This goes beyond the annotations without contradicting them.

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

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

The description is well-structured with clear headings (Purpose, When to use, When NOT to use, Upload requirements, Example, Returns). Each section is purposeful and adds value. It is slightly long but not verbose; every sentence contributes to effective usage.

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 3 parameters and an output schema, the description covers usage guidelines, constraints, alternatives, and return expectations. It does not mention rate limits or auth, but these are not typically expected in tool descriptions and are not critical for selection. The description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so all parameters are documented. The description adds marginal value: it clarifies that `application_id` is optional for the current bot and provides an example payload. While the schema already covers validation rules, the example and explicit optionality note enhance understanding beyond the schema.

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

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

The description clearly states the action ('Upload a new application-scoped custom emoji') and the specific scope (application-scoped), with a distinct resource. It also distinguishes from the sibling tool `emojis_create` for guild-scoped emojis. The verb 'Upload' is specific and unambiguous, and the scope is explicit, making it easy for an agent to differentiate.

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 explicit 'When to use' and 'When NOT to use' sections, naming the alternative `emojis_create` for guild-only emojis. It also gives clear conditions for omitting `application_id`. This leaves no ambiguity about when to select this tool over siblings.

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

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

Beyond annotations, the description discloses that deletion is irreversible, requires __confirm:true, depends on MCP_DRY_RUN=false, and returns the deleted object. This gives the agent the operational safety context needed to invoke destructive behavior correctly.

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

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

The description is well-structured with bolded section headers and bullet points, making it scannable. Every sentence serves a purpose, and the critical destructive warning 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 destructive 3-parameter tool with output schema, annotations, and sibling context, the description covers purpose, usage boundaries, confirmation flow, and return shape. Nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds useful context about omitting application_id to target the authenticated bot application and reiterates the confirmation requirement, but it does not need to add much more.

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

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

Description opens with a specific verb and resource: 'Delete an application emoji.' It distinguishes itself from the sibling tool emojis_delete by explicitly scoping to application emoji versus guild emoji. The destructive nature is highlighted immediately.

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

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

Provides explicit 'When to use' and 'When NOT to use' sections. Names the alternative tool emojis_delete for guild emoji, which removes ambiguity for an agent selecting the correct endpoint.

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 read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: it shows the return shape `{id, name, animated}` and explains that omitting application_id targets the authenticated bot's application. No contradiction with annotations exists.

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

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

The description is compact, well-sectioned, and front-loaded with purpose. Every sentence earns its place: use cases, optional parameter behavior, and return shape. There is no 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 simple read-only fetch tool, this is complete. An agent knows exactly what it does, when to use it, what the optional parameter means, and what it will get back. The existing output schema and annotations cover the remaining details.

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 both emoji_id and application_id already documented. The description's note about omitting application_id essentially restates the schema description and adds no new parameter meaning beyond what the schema provides, so the 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 states a specific verb and resource: 'Fetch a single application emoji.' It further clarifies the use case by saying it verifies existence and inspects the name/animated flag, which distinguishes it from list/create/modify/delete app emoji tools and from guild emoji 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?

A dedicated 'When to use' section provides explicit conditions: verify an app emoji exists or inspect its name/animated flag. It also explains the important optional application_id behavior. It does not explicitly name sibling alternatives or exclusion cases, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond the annotations: the app-level vs guild-level scoping and the hard upper bound of 2,000 emojis. This gives the agent useful expectations without conflicting with structured metadata.

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 well-structured with clear headings: Purpose, When to use, When NOT to use, and Returns. Each section is short, front-loaded, and contains only necessary information, making it easy for an agent to parse and act on.

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

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

For a simple read-only list tool with one optional parameter, full schema coverage, a present output schema, and explicit sibling differentiation, the description is complete. It covers scope, constraints, usage, and expected return shape, so no critical information 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 coverage is 100%, and the single parameter already has a clear description including the omission behavior. The tool description repeats the same 'omit application_id' guidance, so it adds no new semantic value beyond the schema. Baseline 3 applies since the schema carries the parameter documentation adequately.

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 ('List') and resource ('custom emojis registered against the application'), and explicitly distinguishes from guild-scoped emojis by clarifying 'per-app, not per-guild'. This makes the tool's purpose unambiguous and differentiates it from emojis_list_guild.

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 'When to use' section provides concrete inspection scenarios, and the 'When NOT to use' section explicitly routes to the sibling tool emojis_list_guild. It also explains the optional application_id behavior, leaving no ambiguity about how to invoke the tool 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?

Annotations already declare non-read-only, idempotent, and non-destructive behavior, so the description's safety burden is reduced. The description adds useful limitations—no byte editing, return shape—but does not add deeper context such as explicit permission requirements or error behavior. It is accurate and consistent with annotations, but not rich.

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 clearly structured with bold section headers, short purpose, focused usage rules, and a compact return hint. Every section adds value, and the operative meaning 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?

The description covers purpose, when to use, when not to use, alternatives, and return shape, which is enough for a simple rename tool with annotations and an output schema present. I minor gap is the lack of explicit mentioning permission/authorization requirements for modifying an app emoji, but this is not critical for a simple rename 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?

The schema already has 100% description coverage for all three parameters, including the omission behavior for application_id. The description mostly restates this and doesn't meaningfully enrich what an agent would already understand from the schema.

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

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

The description opens with a concrete statement — 'Rename an application emoji' — and distinguishes this tool from image-replacement flows by explicitly saying Discord does not allow editing emoji bytes. It also differentiates the 'app emoji' scope from the many sibling emoji tools without ambiguity.

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

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

There is a dedicated 'When to use' section and a 'When NOT to use' section that points to app_emojis_create and app_emojis_delete for image replacement. This gives the agent a clear decision rule and names the exact alternative workflow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, signaling a safe read operation. The description adds valuable context beyond annotations by noting the raw path workaround due to missing library types and explicitly listing the return fields. This gives the agent a solid behavioral model without contradicting 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?

The description is extremely concise and well-structured with clear sections: Purpose, Note, and Returns. Every sentence earns its place, providing essential information without any fluff 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?

The tool has a simple input schema (2 params), output schema present, and annotations cover safety. The description explains the purpose, the API path workaround, and return shape, making it complete for an agent to understand what this tool does and what it returns without ambiguity.

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 both parameters documented (application_id pattern and instance_id max length/description). The description doesn't add extra parameter semantics beyond what's already in the schema, so the baseline score of 3 is appropriate.

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

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

The description states the specific action: 'Fetch a running Activity instance by id' and explicitly mentions the Discord Activities API. This uniquely identifies the tool's purpose and clearly distinguishes it from the many sibling tools by resource type ('Activity instance').

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

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

The description makes it clear this tool is for fetching an activity instance by ID, providing direct context for when it would be used. It doesn't explicitly mention alternatives or when not to use it, but given there are no similar sibling tools for activity instances, the context is clear enough.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description's main job is to add meaning beyond that. It does so by disclosing that the returned object is a 'projected' shape, that name/description remain raw author data, and that untrusted_text provides a separately fenced copy—useful trust-boundary context.

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

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

The description is compact and front-loaded, using short labeled sections for Purpose, When to use, and Returns. Every sentence earns its place and there is no filler or repetition of schema/annotation data.

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 parameterless read-only getter with an output schema, this description is complete: it explains the endpoint, the typical use cases, and the important untrusted-text caveat. It could slightly expand on the exact fields or format, but the output schema makes that unnecessary.

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

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

The tool has zero parameters, so the parameter load on the description is minimal. The 100% schema coverage and empty input schema fully describe invocation; the description doesn't need to compensate and adds no unnecessary parameter details.

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

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

The description opens with an explicit statement of purpose: fetch the bot/app application object at /applications/@me. It lists concrete uses (confirm app identity, read flags, install URLs, tags, interaction endpoint), which makes the tool's scope unmistakable even among many siblings.

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

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

A dedicated 'When to use' section gives clear operational context: confirm app identity and inspect app-level data. It does not explicitly name alternatives or state when not to use it, but the read-only, self-scoped nature is clear enough to guide 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?

The annotations already declare readOnlyHint true and destructiveHint false, and the description complements this by detailing the return shape `{records, count}` and the enum range. This adds behavioral context without contradicting 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?

The description is two labeled lines, front-loading the purpose and then the return structure. No wasted words.

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

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

For a single-parameter list operation with rich annotations and output schema, the description covers the purpose and return shape sufficiently. It doesn't discuss pagination or edge cases, but these are not necessary given the simplicity.

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 `application_id` with description and pattern, and the description adds no further parametric information. Since schema coverage is 100%, the description provides no extra semantic value.

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 'List' as a specific verb and identifies the resource as 'application role-connection metadata records', clearly distinguishing this from the modify sibling. The parenthetical adds context about linked roles criteria.

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

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

The description implies its usage through the 'List' verb but does not explicitly state when to use it over siblings or exclude alternatives. There is no mention of the modify counterpart or any condition-based guidance.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the mutation behavior is known. The description adds value by explaining the return shape and the distinction between raw fields and untrusted_textais. It does not discuss auth, side effects, or rate limits, but with annotations covering the safety profile, this is acceptable.

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 brief, labeled sections (Purpose, Pass only fields, Returns) deliver maximum information with zero waste. The key usage rule is front-loaded and each sentence contributes unique value. Excellent structure.

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

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

The tool is moderately complex with 13 optional parameters and nested objects. The description gives general editing guidance and return information, but parameter semantics are mostly missing. The presence of annotations and output schema helps, but the low schema description coverage means the description does not fully equip an agent to call it correctly without prior knowledge.

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 8%, leaving 12 of 13 parameters without explanations. The description's 'all fields optional' is already conveyed by the schema, and it provides no meaning for parameters like integration_types_config or event_webhooks_types. The agent would need external API knowledge to use these correctly.

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

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

The description clearly states the action: 'Edit the bot/app application object' with a specific PATCH endpoint. This is a distinct verb-resource pair, and it is easy to differentiate from siblings like application_get_current (read) or application_modify_role_connection_metadata (different resource).

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

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

The description provides clear usage context: it is the tool for modifying the current application. 'Pass only fields you want to change' gives a practical invocation pattern. However, it does not explicitly mention alternatives or when-not-to-use, but the tool name and context make the appropriate use obvious.

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 (readOnlyHint false, destructiveHint false), the description adds key behavioral context: this is a wholesale replace, records are removed, and it returns '{records, count}'. This fully informs the agent of the side effects and result shape, exceeding what annotations alone 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 bolded sections in under 25 words: purpose, behavior warning, and return value. Each sentence earns its place, front-loaded with the core purpose, and there is no fluff.

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

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

The description covers the essential behavioral aspects (replace, removal, max 5, return shape) and the schema covers parameter details. It doesn't mention permissions or auth requirements, but for a two-parameter tool with a well-specified schema, it is nearly complete. The output schema signal also reduces the need to explain return values.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the 'wholesale replace' context but doesn't elaborate on individual parameters beyond what the schema already describes. It does reinforce that `records` is the replacement set, adding minor value.

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 'Replace the application role-connection metadata records' – a clear verb and resource. It further specifies a 'wholesale replace' semantics, distinguishing it from get/partial-update operations and aligning with the sibling tool application_get_role_connection_metadata.

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

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

The description clearly warns that 'any existing record not in records is removed', which is critical usage guidance for preserving existing entries. It does not name alternative tools explicitly, but the replace-vs-get distinction is clear and the behavior is unambiguous.

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

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

Annotations already carry readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavior beyond that: descending-ID pagination semantics (pass 'before' as the last entry's oldest_id, repeat until empty) and a raw-data warning that structured 'reason' values are unfenced moderator-controlled input. This enriches what annotations alone provide. 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?

Bold section labels (Purpose, When to use, Example, Pagination, Returns) make it scannable and front-loaded. Each block earns its place — the Returns block slightly overlaps with the output schema that exists, but the raw-data fencing caveat adds non-redundant value. Slightly long but information-dense.

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 query tool with 5 parameters, an output schema, and full annotations, the description covers everything an agent needs: purpose, when to invoke, a concrete example, the non-obvious pagination flow, and a data-integrity caveat about reason values. The tricky parts (action_type mapping, 'before' semantics, descending order) are all handled explicitly.

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

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

Schema coverage is 100%, so the baseline is 3; the schema already documents every parameter. The description adds meaning beyond the schema: the action_type example maps 20 to MEMBER_KICK (concrete semantic), and the pagination section explains how 'before' works mechanically with oldest_id. This pushes it above baseline.

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

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

The description opens with a specific verb-resource pair ('Fetch audit log entries for a guild'), which is precise and unambiguous. The example with action_type 20 = MEMBER_KICK and the use cases ('who kicked X?', post-incident forensics) reinforce the purpose. No sibling tool handles audit logs, so it inherently stands apart.

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

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

The 'When to use' section gives concrete investigative scenarios and a worked example, giving the agent clear context. It explains pagination mechanics but does not explicitly name alternatives or state when NOT to use it (e.g., for live member state, prefer members_get). The guidance is clear though not exhaustive.

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 denote a non-read-only mutation and non-destructive behavior. The description adds valuable behavioral context by detailing the conditional dependency of trigger_metadata on trigger_type (e.g., '1 KEYWORD → keyword_filter, regex_patterns, allow_list') and specifying the return shape. This goes beyond the annotations without contradicting them.

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

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

The description is well-structured with bold headers, bullet points, and a clear returns line. It is concise—every sentence provides necessary information without repetition or fluff. The conditional mapping is presented compactly and is 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 tool with 10 parameters, nested objects, and complex conditional logic, the description covers purpose, usage, conditional metadata, and return value. It is complemented by full schema documentation, making it comprehensive. No critical missing context (e.g., permissions, errors) is apparent for the agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by mapping each trigger_type to the applicable trigger_metadata fields, which is not explicitly enumerated in the schema comments. This helps the agent decide which combinations to use, exceeding the bare 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?

The description opens with 'Purpose: Create an AutoMod rule', which is a clear verb+resource statement. It distinguishes this tool from siblings like automod_modify_rule, automod_get_rule, automod_delete_rule, and automod_list_rules by explicitly focusing on creation.

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 'When to use' section provides concrete examples (keyword filter, spam blocker, mention-raid guard) indicating the tool's intended scenarios. However, it does not explicitly mention alternatives or when not to use, but the context of sibling tool names offers enough differentiation.

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 destructiveHint=true, but the description goes further by stating the operation is irreversible, requiring __confirm:true and MCP_DRY_RUN=false for actual deletion, and specifying the return payload. This adds critical safety context beyond 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?

The description is well-structured with bolded labels, front-loaded purpose, and every sentence contributes meaning. It is compact yet comprehensive—five short sections covering purpose, usage, return, and security in fewer than 100 words.

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

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

For a destructive operation, the description covers all key aspects: purpose, alternative, irreversibility, confirmation mechanism, return format, and dry-run behavior. The sibling list and schema enrich the context further, making this fully self-contained for safe 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%, so the schema fully documents each parameter. The description adds value by explaining the purpose and triggering mechanism of __confirm, which is not obvious from the schema alone. It does not describe audit_reason, but the schema already covers it.

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

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

The description opens with a specific verb and resource: 'Delete an AutoMod rule.' It immediately flags 'DESTRUCTIVE - IRREVERSIBLE' and distinguishes from the sibling tool automod_modify_rule by explaining when to use the alternative. This makes the tool's purpose unambiguous and well-scoped.

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' and 'When NOT to use' sections, including a concrete alternative (automod_modify_rule with enabled:false) for temporary disabling. This is model behavior for guiding tool 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context about the return payload: 'name and trigger metadata remain raw user-authored data; untrusted_text provides a separately fenced copy.' This discloses data fidelity nuances beyond the safety annotations and helps the agent interpret results correctly.

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

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

The description is compact and well-structured with 'Purpose', 'When to use', and 'Returns' sections. It front-loads the core purpose and contains no redundant phrasing. Every sentence serves a functional role and the overall length is appropriate.

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

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

For a simple read operation with two well-documented parameters, an output schema, and strong annotations, the description covers all essential aspects: purpose, usage, and return shape nuances. It does not need to elaborate on return values beyond the note about raw data and untrusted_text, since an output schema exists.

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 both guild_id and rule_id having clear descriptions in the input schema. The tool description adds no extra parameter details, so it does not improve on the schema. Baseline 3 is appropriate given 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 explicitly states 'Fetch a single AutoMod rule' with a specific verb and resource, distinguishing it from sibling tools like automod_list_rules, automod_modify_rule, automod_create_rule, and automod_delete_rule. The purpose is unambiguous and precisely scoped to a single rule retrieval.

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

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

The description provides a clear usage context: 'Inspect rule config before editing.' This implies a specific workflow and aligns with the sibling automod_modify_rule tool. However, it does not explicitly mention alternatives or when not to use, so it lacks full exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context about the return format and a warning that rule names remain raw user-authored data, with untrusted_names fenced separately. This is useful beyond 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?

The description is well-structured with clear Purpose, When to use, and Returns sections. Every sentence provides value, and 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?

This is a simple read-only tool with one parameter and an output schema. The description includes the return shape and context about untrusted names, making it complete for the tool's complexity.

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% with the single guild_id parameter already described. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description states 'List all AutoMod rules in a guild' with a specific verb and resource, clearly distinguishing it from sibling tools like automod_get_rule (single rule) and automod_create_rule (write operation).

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 'When to use' section provides clear context: audit existing rules and find a rule ID before modifying/deleting. It implies alternatives (modify/delete tools) but does not explicitly name them or state when not to use.

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 readOnly=false, destructive=false, idempotent=true. The description adds valuable context beyond annotations: patch semantics (only provided fields are updated), immutability of trigger_type, and the return object shape. It does not mention permissions or rate limits, but the annotation coverage plus these extras are strong.

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, uses clear bold headers, and front-loads the purpose. The bulleted usage list and note are easy to scan, with no filler or redundant 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?

The description covers purpose, patch semantics, an important immutable constraint, and return shape. With the output schema present, this is sufficient for an agent to select and invoke the tool. It does not elaborate on parameter interdependencies (e.g., trigger_metadata fields valid per trigger_type), but the schema's nested descriptions partly cover that.

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%, and the description mentions only 'keyword list, actions, enabled' as examples, leaving other parameters (exempt_roles, exempt_channels, trigger_metadata, audit_reason) implied. It does add the critical patch semantics ('Pass only fields you want to change'), but it does not fully compensate for the schema's incomplete parameter 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 states 'Update an AutoMod rule's settings' with a specific verb and resource, and clarifies partial-update behavior with 'Pass only fields you want to change.' This clearly distinguishes it from sibling tools like automod_create_rule, automod_delete_rule, automod_get_rule, and automod_list_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?

The description includes a dedicated 'When to use' section listing concrete scenarios (tweak keyword list, change actions, toggle enabled). It also provides an explicit alternative for the immutable trigger_type field: 'delete and recreate.' This gives clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation is established. The description adds valuable context beyond that: 'extra fields are ignored by Discord' is a behavioral trait, and the return shape with optional tags is described. 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?

The description is well structured with bold headers, a usage list, an example, and return info. It is slightly long but each section earns its place; no filler. The front-loaded purpose and usage are especially effective.

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 19-parameter tool with a real output schema, this description covers the core decision factors: when to use, type mapping, field-behavior note, and return shape. It could mention required permissions (e.g., MANAGE_CHANNELS) or error conditions, but the schema and annotations already carry a lot of the burden.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by enumerating Discord channel type numeric values (0, 2, 4, 5, 13, 14, 15, 16) which the schema leaves as an open integer, and it adds a concrete example. This materially helps an agent choose the correct type and parameter combination.

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

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

The description clearly states the verb 'Create' and the resource 'a new channel in a guild', enumerating the channel types (text, voice, category, etc.). It explicitly distinguishes itself from thread-creation tools by naming the sibling alternatives, so an agent can immediately tell which tool to select.

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 explicit 'When to use' scenarios (programmatic guild bootstrap, tier-based channel provisioning) and a dedicated 'When NOT to use' section that points to `messages_create_thread`, `channels_forum_create_thread`, or thread-specific tools. This gives unambiguous 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?

Beyond the destructiveHint annotation, the description adds crucial behavioral context: irreversibility, the ConfirmRequired gate, the __confirm:true requirement, and the MCP_DRY_RUN=false condition for actual deletion. It also states the return shape. This enriches what annotations already convey without contradicting them.

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

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

The description is well-structured with clear headings (Purpose, When to use, When NOT to use, Returns, Security) and every line adds value. It is compact for a destructive tool and front-loads the critical warning.

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

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

Given the presence of an output schema, comprehensive annotations, and sibling context, the description still supplies the necessary operational details: the destructive confirmation flow, dry-run behavior, return value, and an explicit alternative. This is complete for a high-risk 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 baseline is 3. The description only reiterates the __confirm behavior that the schema already documents; it adds no new parameter-level semantics. It does not explain audit_reason beyond the schema.

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

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

The description opens with a specific verb+resource pair: 'Delete a channel (or close a DM).' It is immediately distinguishable from siblings like channels_modify and channels_delete_permissions because it names the destructive action and notes the alternative for permission hiding.

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?

Contains an explicit 'When to use' section ('tear down stale or compromised channels') and a 'When NOT to use' section that names the exact alternative tool (channels_modify_permissions). This is exactly the kind of decision guidance the rubric calls for.

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 behavioral context beyond the annotations: it explains the return format (`{deleted, channel_id, overwrite_id}`) and the idempotent behavior of treating non-existent overwrites as success, which aligns with `idempotentHint=true`. It does not mention auth requirements, but the annotations already cover safety (`readOnlyHint=false`, `destructiveHint=false`). No contradiction found.

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

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

The description is well-structured with clear sections (Purpose, When to use, When NOT to use, Returns) and every sentence provides necessary information without redundancy. It is concise and front-loaded with the main purpose.

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 relatively simple delete operation, the description covers purpose, usage boundaries, return behavior, and edge-case handling. The input schema is fully documented, and the output schema exists. The description is complete enough for an agent to select and invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add significant new meaning to the parameters beyond the schema, though the return format indirectly clarifies `channel_id` and `overwrite_id`. This is acceptable given the schema's completeness.

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

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

The description clearly states the action: 'Remove a permission overwrite from a channel.' It uses a specific verb and resource, and the 'When NOT to use' section explicitly distinguishes it from the sibling tool `channels_modify_permissions`, so there is no ambiguity about its 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 provides explicit when-to-use guidance ('Revert a channel back to inheriting role/category defaults') and when-not-to-use guidance ('Changing allow/deny bits → use `channels_modify_permissions`'), including a named alternative. This fully clarifies usage context.

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

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

Annotations already mark readOnlyHint=false and destructiveHint=false. The description adds behavioral context by disclosing that a delivery webhook is auto-created on the target and that Discord rejects non-announcement channels. This goes beyond the annotations without contradicting them.

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

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

The description is concise, well-structured with clear labels (Purpose, When to use, When NOT to use, Returns), and avoids any redundant filler. Every sentence adds 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 an output schema present and annotations covering key behavioral flags, the description sufficiently covers purpose, usage conditions, return value, and a critical constraint. It could mention permissions or rate limits, but these are not essential given the existing structured data.

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

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

Schema coverage is 100% and each parameter already has a meaningful description (channel_id as source, webhook_channel_id as target, audit_reason as audit log reason). The tool description does not add further parameter-level detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description states 'Cross-post messages from an announcement (news) channel into a target channel via a webhook,' which uses a specific verb, resource, and mechanism. This clearly distinguishes it from sibling tools like messages_crosspost or webhooks_create.

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 includes explicit 'When to use' and 'When NOT to use' sections, with a concrete use case (mirroring release announcements) and a rejection condition (source not type 5). It does not explicitly name alternative tools, so it misses the full 5 criterion, but the guidance is clear and actionable.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, so the description isn't required to restate those. It adds valuable context: the need for a nested message with at least one of content/embeds/components, the return shape including applied_tags, and the note that tag IDs are preserved. It doesn't contradict annotations and goes beyond them by describing the required body shape and return 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?

The description is well-structured with bold headers, front-loads the core purpose, and each sentence earns its place. It's concise yet covers purpose, exclusions, body shape, and return—no fluff.

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

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

Given the tool's complexity (nested message, 7 params, output schema present), the description is complete: it covers when to use, when not, body requirements, and return details. The output schema already documents return structure, so the description doesn't need to repeat it. Nothing essential is missing for an agent to call it correctly.

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

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

Schema coverage is 86%, so most parameters are already documented. The description adds meaning beyond the schema by stating the nested message requirement and the at-least-one constraint on content/embeds/components, which the schema's individual descriptions don't enforce. It also clarifies applied_tags behavior in the return, adding semantic value.

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 a new forum (or media) thread with an initial message in one request.' It clearly distinguishes itself from the sibling messages_create_thread by explicitly naming it and contrasting the anchored-thread use case, so an agent can tell them apart immediately.

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

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

Includes dedicated 'When to use' and 'When NOT to use' sections. It states the intended scenario (forum-channel onboarding, Q&A posts) and explicitly routes to messages_create_thread for anchored threads, plus warns against plain text channels. This is model usage guidance with exclusions and alternatives.

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

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

Even with readOnlyHint, idempotentHint, openWorldHint, and destructiveHint already present, the description adds substantial value: it discloses the exact return shape, edge cases around missing vs empty tag fields, the instruction to retain existing tag IDs when editing, DM behavior, and an untrusted-data warning about topic and tag names. This goes well beyond 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?

The description is dense but well-structured with bolded Purpose and Returns sections, front-loading the core intent before detailing edge cases. Every sentence adds operational value, and there is no filler or repetition.

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

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

For a single-parameter read tool with safety annotations, this description is complete: it explains when to use it, what it returns, how to treat tag fields, and important data-trust caveats. An agent can select and invoke this tool correctly without needing additional external context.

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

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

The input schema already documents channel_id with 100% coverage, so the baseline is 3. The description adds mild extra context by clarifying that the target may be a channel or forum post, but it does not meaningfully expand the parameter semantics beyond what the schema provides.

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

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

The description clearly states a specific verb ('Read') and resource ('a channel or forum post') with an explicit purpose ('before editing'). It does not explicitly name or differentiate sibling tools like channels_list or channels_modify, so it stops short of the strongest sibling-aware framing.

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

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

The phrase 'before editing' gives a clear when-to-use context, signaling this is a fetch-current-state operation. It does not provide explicit exclusions or name alternative tools such as messages_get or channels_list, but the intended usage is evident.

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

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

Annotations already mark this as read-only and idempotent, so the description does not need to repeat those. It adds valuable behavioral context by specifying the return shape, including optional forum/media tags with their nested fields, which goes beyond the schema.

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

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

The description is well-structured with bolded sections for Purpose, When to use, Example, and Returns. Every sentence contributes useful information without redundancy, making it easy for an agent to parse.

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

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

For a simple list operation with one documented parameter, the description covers purpose, usage context, an example, and the expected return structure. Annotations cover the safety profile, so nothing essential is missing.

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

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

Schema coverage is 100% and the only parameter, guild_id, is already described as 'Guild to list channels for.' The example reinforces the expected format, but the description adds no significant semantic meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: 'List all channels in a Discord guild.' This clearly distinguishes it from channel-specific operations like channels_get and from thread-listing siblings such as channels_list_active_threads_guild.

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 explicit use cases: 'discover channel IDs by name; audit channel layout and forum tags.' It does not explicitly say when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds behavioral context by stating it lists threads the bot can see (scope), and details the return structure including applied_tags and the raw nature of structured thread names. It does not contradict annotations and adds useful nuances beyond the schema.

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

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

The description is well-structured with bold headings, front-loaded purpose, and separate usage sections. Every sentence adds value—no fluff. It is concise yet comprehensive, making it easy for an agent to parse quickly.

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 list tool with one parameter, the description is complete. It explains the return shape ({threads:[...], count, guild_id}), the nuance of applied_tags, and raw Discord data handling. It also clearly scopes the operation. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the only parameter (guild_id) is already well-documented in the schema. The description does not add any further parameter-specific semantics, but none are needed given the schema covers it. 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?

The description explicitly states 'List every active thread the bot can see across an entire guild', which is a specific verb (list), resource (active threads), and scope (guild). It also distinguishes from archived thread tools by name, so the agent can clearly differentiate it from siblings.

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

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

The description provides a dedicated 'When to use' section (moderation, sweeping stale threads) and a 'When NOT to use' section that explicitly names the alternative tools (channels_list_public_archived_threads / _private_archived_threads) for single-channel archived threads. This is explicit, actionable guidance with exclusions.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description goes further by explaining the joined-thread scoping, the exact return object shape, `has_more` pagination, `applied_tags` preservation, and how structured names are fenced in text responses. These are meaningful behavioral details beyond the structured metadata.

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 tightly organized with bolded sections for purpose, usage, exclusions, and return value. Every bullet earns its place, and the most decision-relevant scoping and exclusion information appears early.

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 fully covers what an agent needs to call this tool correctly: what it returns, how it differs from the nearest sibling, and what data transformation caveats apply. Given the strong schema and annotation coverage, no important context is missing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The schema already documents `channel_id`, `limit`, and `before` with clear descriptions. The tool description adds no additional parameter semantics beyond what the schema already provides.

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

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

The description states a specific verb ('List'), a precise resource ('private archived threads the current bot user has joined under a parent channel'), and clearly separates this from the sibling that lists all private archived threads. The scope is immediately understandable and not a restatement of the tool name.

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

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

There is an explicit 'When to use' section and a 'When NOT to use' section that names the alternative tool, `channels_list_private_archived_threads`, and notes its MANAGE_THREADS requirement. This fully resolves selection between the closely related siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond annotations: the MANAGE_THREADS permission requirement and the behavioral quirk that structured names are returned raw while the human-readable response fences them. The return-shape detail is partially redundant with the output schema, keeping this at a 4 rather than 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 description is organized into Purpose, When to use, When NOT to use, and Returns sections, each earning its place with no filler. The most decision-relevant information (purpose + exclusion) 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 read-only list tool with an output schema and safety annotations, the description covers purpose, permission, usage context, sibling routing, and the has_more/applied_tags/fencing nuances. The only minor redundancy is the Returns section overlapping with the output schema, which the rubric says the description needn't have explained at all.

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 limit, before, and channel_id are already documented in the schema (with ranges, format pattern, and ISO 8601 timestamp semantics). The description adds no parameter-level detail, which is acceptable given the high coverage — 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 states a specific verb (list) and resource (archived private threads under a parent text channel), and the 'When NOT to use' section explicitly differentiates it from the sibling channels_list_joined_private_archived_threads. An agent can distinguish this tool from its closed variant 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?

Has explicit 'When to use' (moderation review of historical private threads) and 'When NOT to use' sections, with the alternative sibling tool named directly. This gives the agent a clear decision rule for routing between the two archived-thread listing 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?

Beyond the readOnly/idempotent/openWorld annotations, the description discloses pagination mechanics (before from archive_timestamp, limit, has_more), the exact return shape, and special handling of applied_tags and raw structured names. It does not add exclusions or a sorting guarantee, but the added behavioral detail is meaningful.

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 uses compact labeled sections (Purpose, When to use, Pagination, Returns) and every sentence carries information. It is front-loaded with the core purpose and does not pad with redundant phrasing.

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 read-only list tool with annotations covering safety and an output schema available, the description fully covers purpose, usage, pagination, and response specifics. There are no obvious gaps an agent would need to resolve before calling 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 coverage is 100%, so the baseline is 3, and the description goes further by explaining how `before` should be sourced from a prior archive_timestamp and how `limit` and `has_more` interact for paging. Channel_id remains straightforward, but the added pagination semantics provide real value beyond the raw schema.

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

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

The first line states a specific verb/resource ('List archived public threads') and constrains scope to parent text/announcement/forum/media channels and public threads, which separates it from sibling tools like channels_list_private_archived_threads. The purpose is immediately identifiable without relying on the tool name alone.

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 'When to use' section gives concrete use cases (recover stale discussions, audit archives) and the pagination section explains how to page further. It does not explicitly name alternatives or state when not to use it, though the 'public' qualifier implicitly distinguishes it from private-archived thread 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?

Beyond the annotations, the description reveals important runtime behavior: Discord ignores non-applicable fields, forum tag updates require reading the current set first and refuse incomplete states, verification readback occurs after PATCH, and verification failure still means PATCH succeeded. These are non-obvious behavioral details that materially affect correct invocation.

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 long but tightly organized with bolded sections: Purpose, When to use, When NOT to use, Field applicability, Forum tags, Emoji, Verification, and Returns. The purpose is front-loaded, and every section earns its place given the tool's complexity. No filler or redundant restatement of the schema.

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

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

For a 23-parameter mutation tool with low schema coverage, the description is remarkably complete. It covers purpose, exclusions, prerequisites (read channels_get first), complex forum-tag semantics, emoji constraints, verification behavior, and return shape. The existence of an output schema reduces the need to describe returns, but the description still provides useful verification-related return details.

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 35%, so the description carries significant weight. It adds crucial semantics for available_tags and remove_available_tag_ids (complete desired set, preserving omitted fields, requiring prior read), for emoji_id vs emoji_name (guild emoji IDs only, null clears), and for partial updates ('Pass only the fields you want to change'). Some parameters like bitrate, position, and default_forum_layout are not individually explained, but the cross-reference to channels_create_guild_channel partially compensates.

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

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

The description opens with a specific verb and resource: "Update an existing channel's settings." It clearly distinguishes itself from sibling tools by explicitly naming what it is not for (permission overwrites → channels_modify_permissions, deletion → channels_delete), so an agent can differentiate it without inspecting other 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?

The description provides an explicit 'When to use' section listing concrete scenarios (rename, move under category, toggle nsfw, change slowmode, retag forum channels) and a 'When NOT to use' section naming exact alternatives. This leaves little to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds useful context by clarifying that the tool replaces existing overwrites, explains the `type` encoding, and discloses the return shape `{updated, channel_id, overwrite_id}`. 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?

The description is well-structured with bold labels and bullet points, presenting the purpose, usage guidance, parameter notes, and return value in a compact format. No redundant sentences.

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

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

Given the tool's moderate complexity, the description covers purpose, usage guidelines, parameter semantics, and returns. It also references the sibling delete tool for exclusions. With an output schema present, it does not need to detail return values further; the description is sufficient for an agent to select and invoke the 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?

The input schema covers all 6 parameters with descriptions, so the baseline is 3. The description adds a concise explanation of `type` (0=role, 1=member) and that `allow`/`deny` are stringified bitfields, but this largely mirrors the schema descriptions. It provides minimal additional semantic value beyond the schema.

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

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

The description states 'Create or replace a permission overwrite for a role or user on a channel' with a specific verb and resource, and clearly distinguishes from `channels_delete_permissions`. It also specifies the scope (role or user) and the action (create/replace).

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 provides explicit 'When to use' examples like restricting a channel to a role or allowing moderators to manage messages, and 'When NOT to use' with a named alternative (`channels_delete_permissions`) for removing overwrites entirely.

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), the description explains that repeat calls extend the indicator, adding behavioral nuance. The ~10-second duration and the return shape ({ok, channel_id}) are additional transparency not found in structured data.

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?

Structured in four short sections, each sentence provides distinct value—purpose, use cases, non-use case, and return info. No 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 low-complexity tool with one parameter, output schema, and full annotations, the description covers all needed context: when to use, what it returns, and idempotency behavior. It is 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 schema already provides a description for channel_id with 100% coverage, and the tool description does not add further detail. Per the baseline for high schema coverage, a 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 'Show the bot as typing in a channel for ~10 seconds,' a specific verb+resource statement. It clearly distinguishes from siblings like messages_send by focusing solely on the typing indicator.

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 'When to use' and 'When NOT to use' sections explicitly state when to invoke this tool (long-running operations) and when not to (replacement for messages). This provides clear guidance relative to sibling messaging tools.

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

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

The description goes well beyond the annotations by disclosing that the operation is atomic, that an empty array deletes every global command, that the operation is gated by ConfirmRequired, and that MCP_DRY_RUN=false is required to actually apply changes. This is valuable behavioral context beyond the destructiveHint=true 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?

The description is well-structured with clear sections: purpose, when to use, caution, security, and returns. It is front-loaded with the most important information and every sentence serves a purpose without unnecessary 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 destructive, confirm-gated bulk operation, the description covers purpose, usage context, safety precautions, security requirements, and return shape. Combined with the full schema and annotations, an agent has everything needed 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?

The input schema already provides descriptions for all three parameters, including the meaning of `commands` and `__confirm`. The description adds useful emphasis around the empty-array behavior and the confirm/dry-run gate, but does not substantially expand the semantics of `application_id` beyond what the schema states.

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 ('REPLACE') and resource ('the entire global command registry'), and clarifies the key behavior: commands not in the `commands` array are deleted. This clearly distinguishes it from related tools like commands_create_global, commands_modify_global, and commands_bulk_overwrite_guild.

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 identifies the primary use case ('CI deploy: re-sync the canonical command list from source-of-truth') and gives a practical caution to call commands_list_global first to confirm scope. It does not explicitly mention when not to use it or name an alternative for guild-scoped overwrites, but the context is clear enough for correct 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?

The description adds significant behavioral context beyond the annotations: it explains the atomic replace semantics, the empty-array deletion behavior, the confirmation requirement, and the dry-run behavior. The annotations already declare destructiveHint=true and idempotentHint=true, and the description aligns with these while adding the crucial detail about `__confirm:true` and `MCP_DRY_RUN=false`. It doesn't contradict the annotations. Minor deduction because it doesn't explicitly mention rate limits or partial failure behavior, but the added context is strong.

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 well-structured with clear sections (Purpose, Caution, Security, Returns) and front-loads the most critical information about the destructive replace behavior. Every sentence earns its place: the purpose, the caution, the security requirement, and the return format. No wasted words or redundant restating of the schema.

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

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

The description is complete for a destructive bulk operation. It covers the purpose, the destructive scope, the prerequisite check, the security gating, and the return format. The output schema exists, so the return format description is a helpful addition rather than a necessity. The complexity of this tool (atomic replace, confirmation, dry-run) is fully addressed within the description.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the `commands` parameter's replace semantics ('an EMPTY array deletes every command') and the `__confirm` parameter's role in authorizing the destructive operation. It doesn't add syntax details for `application_id` or `guild_id`, but those are already clear from the schema descriptions. This exceeds the baseline 3 for full 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 ('REPLACE') and resource ('guild-scoped command registry'), and explicitly distinguishes the behavior from other command tools by noting that commands not in `commands` are deleted. It also clearly differentiates from sibling tools like `commands_create_guild` and `commands_modify_guild` by emphasizing the atomic wholesale replace semantics.

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

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

The description explicitly tells the agent when to use this tool ('call `commands_list_guild` first to confirm scope') and provides a caution about the destructive nature. It also names the alternative (`commands_list_guild`) and explains the security gating (`ConfirmRequired`, `MCP_DRY_RUN=false`), giving clear context for when this tool is appropriate versus other command-related 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?

Adds meaningful detail beyond annotations: idempotent upsert semantics ('posting the same name+type updates'), a ~1 hour propagation delay, and that description is required for CHAT_INPUT but optional for USER/MESSAGE. These complement the idempotentHint and readOnlyHint=false annotations. Also provides a return shape. Lacks mention of side effects like overwriting, but upsert is explicit.

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?

Well-structured with bold headers, front-loaded purpose, and clear separation of concerns. Each sentence earns its place—purpose, body constraints, idempotency, and return. No fluff 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?

Incomplete for a complex 14-parameter tool. It covers only the basics (name, description, type) and idempotency, but omits the options structure, choices, permission fields, and other advanced parameters. While an output schema exists, the input semantics for most parameters are missing, making it insufficient for fully informed usage.

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 7% (2 of 14 parameters). The description clarifies name and description requirements and the type-dependent description constraint, but leaves options, choices, contexts, permissions, and other fields unexplained. The phrase 'standard command shape' is vague and does not compensate for the low 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?

States 'Create or upsert a global application command' with a specific verb and resource. The term 'global' clearly distinguishes from guild-scoped commands like commands_create_guild, though it doesn't explicitly name alternatives. It's clear but not as explicit as naming a sibling.

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

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

No explicit guidance on when to use this tool versus alternatives such as commands_create_guild or commands_modify_global. The propagation delay is a property, not a usage direction. No when/when-not or alternative recommendations are given.

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

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

Annotations already carry the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds writer-readable 'upser t' semantics that corroborate the idempotent hint, plus the propagation-timing behavior that annotations cannot express. 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?

Compact two-section layout with the purpose front-loaded and every line earning its place. Loses one point because the Returns block is likely redundant if the output schema already specifies the response shape.

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 15-parameter tool with a nested options object, the description covers the core decision (guild scope, propagation latency, return shape) but doesn't guide the complex optional surface or clarify type/options semantics. An agent can make the minimal required call, but richer command definitions risk being built incorrectly.

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 13%, so the description must compensate for 15 params — but it only implies guild scope (guild_id) and slash-command type. The large optional surface (options, contexts, intigration_types, dm_permission, nsfw, channel_types) and the nested option structure remain unexplained in both schema and description.

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

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

States a specific verb + resource: 'Create or upsert a guild-scoped slash command.' The contrast with global ('propagate immediately vs ~1h for global") also differentiates it from the sibling commands_create_global without needing to open that tool's schema.

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

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

Gives a concrete, decision-relevant context: guild commands propagate immediately versus roughly an hour for global commands, which tells an agent when the guild-scoped variant is preferable. But the guidance is imlied rather than an explicit when/when-not, and the overlap with commands_modify_guild for editing params is not addressed.

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 (destructiveHint, readOnlyHint false), the description discloses the full destructive scope ('removes the command from every guild'), a propagation time ('~1 hour'), and the explicit authorization gate ('Pass __confirm:true AND MCP_DRY_RUN=false to actually delete'). This adds critical safety context that annotations alone do not provide.

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

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

The description is tightly structured into three labeled lines: Purpose, Effect, Returns. Front-loaded with the core action, every sentence adds new information with zero filler. Extremely efficient for a destructive tool.

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 returns are already specified) and comprehensive annotations, the description still covers the essential safety and execution context: what gets deleted, the propagation delay, and the confirmation/dry-run mechanism. It is complete enough for an agent to use this tool correctly without additional documentation.

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 describes all three parameters with 100% coverage, including the __confirm confirmation parameter and the MCP_DRY_RUN requirement. The description adds no new parameter-level meaning beyond pointing to __confirm and mentioning the return object, so it meets the baseline but doesn't exceed it.

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

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

The description opens with 'Delete a global application command' – a specific verb ('Delete') and resource ('global application command'), clearly distinguishing it from guild-scoped siblings like commands_delete_guild. The effect statement 'removes the command from every guild within ~1 hour' further removes ambiguity.

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

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

The description implies usage for global commands ('global', 'every guild'), but does not explicitly compare against alternatives such as commands_delete_guild or state when not to use it. Usage is clear enough for an agent familiar with command scoping, but lacks direct exclusion 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?

The description goes beyond annotations by explicitly stating 'DESTRUCTIVE - IRREVERSIBLE' and detailing the confirmation mechanism ('Pass __confirm:true AND MCP_DRY_RUN=false'). It also discloses the return format, providing behavioral clarity beyond what readOnlyHint/destructiveHint annotations 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 concise, front-loaded with the purpose, and each sentence earns its place. It covers purpose, destructiveness, return value, and confirmation in under three short sentences with no redundancy.

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

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

Given the output schema exists and annotations cover safety, the description is largely complete. It explains the destructive nature, confirmation flag, and return object. However, it omits any mention of required permissions or error cases, which is a minor gap for a 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 coverage is 100%, so parameters are already well-documented. The description adds no significant new parameter semantics; it repeats the __confirm behavior already present in the schema. The mention of MCP_DRY_RUN is similarly in the schema, so baseline 3 applies.

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

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

The description states 'Delete a guild-scoped command' with a specific verb and resource, clearly distinguishing it from sibling tools like commands_delete_global. The 'guild-scoped' qualifier removes ambiguity and sets it apart from global command deletion.

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

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

The description implies when to use the tool (for guild-scoped commands) but does not explicitly contrast it with alternatives or provide a 'when-not-to-use' scenario. The destructive warning and confirmation requirement are more about how to invoke than when to choose this tool.

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

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

Annotations already indicate mutation (readOnlyHint: false) and idempotence. The description adds critical behavioral context: user OAuth token is required (not bot token), user must have manage-guild permission, and it returns the updated permission object. This exceeds what annotations alone 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?

Structured with bold section labels and every sentence earns its place. It covers purpose, auth, body format, and return value in a compact, readable format without 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?

Given that an output schema exists, the description appropriately focuses on the auth caveat, body structure, and expected response. It provides enough information for an agent to invoke the tool safely and understand the side effects, which is suitably complete for a 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 has 100% coverage with descriptions for all parameters. The description adds valuable semantics by explaining the permission type mapping (1=ROLE, 2=USER, 3=CHANNEL) which the schema only conveys as integer bounds, and clarifies the bearer_token requirement as a user credential.

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 ('Set per-command permission overrides') and identifies the exact resource (one command in a guild). It clearly differentiates from sibling permission read tools by focusing on editing rather than retrieving.

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 context on when to use (guild-managing user with OAuth) and what it does, but does not explicitly name alternatives or contrast with read-only permission tools like commands_get_command_permissions. The auth and scope guidance is clear but no exclusionary guidance is given.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive, so the description does not need to repeat safety details. The description adds the return structure `{id, application_id, guild_id, permissions:[{id, type, permission}]}`, confirming it returns permission overrides for one command. While it doesn't mention potential caveats like empty overrides or authorization requirements, the annotations and simple nature of the tool make this adequate.

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 just two sentences, with a front-loaded purpose and a separate returns section. There is no redundant or filler content; 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 straightforward read-only GET tool with fully described parameters and an output schema referenced in the description. The annotations and schema cover most contextual needs (safety, parameters, output), and the description adds the return shape. It could be more complete by explicitly naming the sibling tool for fetching all command permissions, but for its simplicity, it is adequately 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 input schema covers all three parameters with descriptions: 'Guild scope', 'Command ID (snowflake)', and 'Bot/app application ID,' achieving 100% schema description coverage. The description adds no additional parameter-level detail beyond reinforcing that the command_id is for a single command, so 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?

The description clearly states 'Get permission overrides for ONE specific command in a guild,' using a specific verb and resource while explicitly scoping to a single command. The emphasis on 'ONE specific' distinguishes this tool from the sibling commands_get_guild_command_permissions, which appears to handle all commands in a guild.

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

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

The phrase 'for ONE specific command' gives clear context that this tool is intended for querying a single command's permissions rather than all commands. However, it does not explicitly name alternatives or provide when-not-to-use guidance, leaving the differentiation to the agent to infer from sibling tool names.

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

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

The description adds value beyond the read-only annotations by detailing the return shape and the nuance that `name` and `description` are raw while `untrusted_text` is a separately fenced copy. This helps the agent understand what data to expect and how to handle it. It does not cover error cases or rate limits, but the core behavioral context is present.

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 concise and well-structured with bolded 'Purpose' and 'Returns' labels. It conveys the essential information in two short sentences with no repetitive or extraneous 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 simple fetch-by-ID operation, the description is fully complete: it states what the tool does, lists the return fields, and the schema covers the required parameters. Annotations cover the safety profile (read-only, idempotent, non-destructive). No critical information is missing.

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

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

Schema description coverage is 100% for both parameters (command_id and application_id), so the schema already documents their meanings. The tool description does not add any additional semantic detail about these parameters, so the baseline of 3 applies.

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

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

The description clearly states the verb ('Fetch'), the resource ('one global application command'), and the identifier ('by id'). This distinguishes it from sibling tools like commands_get_guild (which retrieves a guild command) and commands_list_global (which lists all global commands).

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 on when to use this tool: to fetch a single global command by its ID. It does not explicitly state exclusions or alternatives (e.g., 'for guild commands use commands_get_guild'), but the scope is unambiguous and the name reinforces the distinction.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context about the return format—specifically that name and description remain raw while untrusted_text is a separately fenced copy—which goes beyond the annotation-provided safety profile.

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

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

Two short paragraphs, each earning its place: the first states purpose, the second explains returns. No fluff, well-structured and 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?

Given the simple get-by-id nature, rich annotations, and full schema coverage, the description sufficiently covers the tool's operation. The return field explanation is a bonus even though an output schema exists, making the tool's behavior fully understandable.

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 describes all three parameters with clear meanings (guild scope, command ID, application ID), covering 100% of parameters. The description does not add new parameter-level details beyond the schema, so it meets the baseline expected 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 clearly identifies the action ('Fetch'), the resource ('one guild-scoped command'), and the identifier ('by id'). It distinguishes from sibling tools like commands_list_guild and commands_get_global by specifying the guild scope and the target being a single command.

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

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

The description implies usage when a specific guild command needs retrieval by its ID, but it does not explicitly state when not to use it or compare with alternatives such as commands_list_guild or commands_get_global. There is no explicit exclusion or alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'ALL commands' scope and the return structure, which is useful but does not go beyond what is obvious or already covered by the output schema. No additional behavioral context such as rate limits or required permissions is 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?

The description is extremely concise and well-structured with clear 'Purpose' and 'Returns' sections. Every sentence provides necessary information without any waste.

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

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

For a simple read-only list tool with two required parameters and good annotations, the description is complete. It states the purpose and return shape, and the output schema is available for detailed structure. No critical information is missing for an agent to decide when and how to invoke it.

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 both parameters having meaningful descriptions ('Guild scope' and 'Bot/app application ID'). The tool description does not add any further detail about the parameters, so it does not exceed the baseline provided by the schema.

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

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

The description clearly states the operation: 'List per-command permission overrides for ALL commands in a guild.' It uses a specific verb (List), identifies the resource (per-command permission overrides), and scopes it to all commands in a guild. This distinguishes it from sibling tools like commands_get_command_permissions (singular) or commands_edit_command_permissions.

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

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

The description implies usage by emphasizing 'ALL commands', but it does not explicitly state when to use this tool versus alternatives. There is no mention of when not to use it or references to other tools. The context is clear but not explicitly differentiated.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context beyond this by detailing the return shape and warning that names/descriptions are raw app-author data with untrusted_text as a separately fenced copy. This helps set expectations about data safety.

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 tightly structured with three labeled sections: Purpose, When to use, and Returns. Every sentence serves a clear function, and the return snippet is compact. No 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?

With an output schema present, the return value details are covered externally. The description supplies purpose, usage context, and a summary of the response. For a simple read-only list tool with two parameters and clear annotations, this is 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 input schema has 100% coverage, documenting application_id and with_localizations. The description does not elaborate on parameter usage, but the schema already provides sufficient meaning, so the baseline of 3 applies.

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

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

The description opens with 'List globally-registered application commands,' using a specific verb and resource. This clearly differentiates it from sibling tools like commands_list_guild (which lists guild-scoped commands) and commands_get_global (which fetches a single global command).

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 includes a dedicated 'When to use' section: 'audit global slash commands; before bulk-overwriting global registry.' This provides clear usage context, though it does not explicitly mention when not to use the tool or name an alternative tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds the return shape and hints at its non-destructive usage, but no deep behavioral traits (e.g., pagination, rate limits) are disclosed. It does not contradict 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?

The description is split into labeled sections (Purpose, When to use, Returns) with only 3 sentences total. 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 simple list tool with strong annotations, an output schema, and full parameter schema coverage, the description is complete. It covers purpose, usage context, and return format, leaving no critical gaps.

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 both guild_id and application_id described. The description adds no additional parameter context beyond the schema, so 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?

The description uses a specific verb ('List') and resource ('slash commands registered for a specific guild'), clearly distinguishing it from siblings like commands_list_global (global vs guild scope) and commands_get_guild (list vs single). The scope is explicit and 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?

Provides concrete when-to-use scenarios: 'audit which commands are registered; before bulk-overwriting.' It implies a non-global scope but does not explicitly name alternatives like commands_list_global, leaving slight room for confusion.

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 signal mutation and idempotency, so the description adds value by disclosing partial-update semantics: 'All command-body fields are optional - pass only what changes.' It also states what the response returns, giving useful behavioral context beyond the raw 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?

The description is compact and front-loaded: the purpose appears first, the partial-update behavior is stated next, and the return shape is provided. Both sentences earn their place with no redundancy.

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

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

For a complex tool with 15 parameters and low schema coverage, the description is thin. It covers purpose, scoping, edit semantics, and return value, but it does not explain the meaning of many parameters or provide guidance on when to choose this tool over related command tools. The output schema presumably covers return details, but the overall description leaves notable gaps.

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 13% with 15 parameters, and the description does not compensate. The only parameter-related guidance is the generic statement that command-body fields are optional; it adds no meaning for ambiguous fields like nsfw, handler, contexts, or integration_types. The two required IDs are self-explanatory in the schema, but most parameters remain semantically unexplained.

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 pair: 'Edit a global application command', and the word 'global' clearly distinguishes it from sibling guild-scoped command tools like commands_modify_guild. The purpose is immediately identifiable without needing to inspect 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 description clearly contextualizes usage to global application commands, implying it should not be used for guild commands. However, it does not explicitly name alternatives such as commands_modify_guild or state when to prefer create versus modify, so there is no explicit when-not guidance.

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

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

Annotations already cover read-only, destructive, and idempotent behavior. The description adds useful behavioral context: all command-body fields are optional, implying a partial patch rather than a full replacement, and it discloses the response shape. 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?

Two purposeful, front-loaded sections: Purpose followed by Returns. Every sentence adds value, with no filler or repetition of schema 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?

The description provides the core essentials: scope, optionality, and return shape, while annotations cover safety behavior and the output schema covers return structure. However, given the tool's complexity and low parameter documentation coverage, the description remains minimal and an agent would still need external knowledge to use several command-body fields 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 only 19%, so the description must compensate for the 13 undocumented command-body parameters. It only says 'all command-body fields are optional,' which is already inferable from the schema's required list. It does not clarify domain-specific fields like handler, contexts, integration_types, or default_permission.

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?