Server Quality Checklist

Tool Scores

• create_roleB
  3.3/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses that this is a WRITE operation and gated behind an environment variable, which is useful. However, it lacks details about permissions needed, reversibility, or side effects of creating a role. The transparency is partial but not negligible.

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

  Conciseness5/5

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

  The description is a single sentence, extremely concise and front-loaded. It conveys the core action and gate without any waste. This is ideally sized for a simple tool.

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

  Completeness2/5

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

  Although the tool has 5 parameters (2 required) and no schema descriptions, the description provides none of that missing context. The output schema exists, so return value explanation is not needed, but parameter semantics and usage guidance are absent. For a write tool with zero schema coverage, this is incomplete.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description adds no information about parameters. It does not explain the meaning of guild_id, name, color, hoist, or permissions beyond what the bare schema types show. The description fails to compensate for the lack of schema descriptions.

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

  Purpose5/5

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

  The description uses a specific verb and resource: 'Create a role in a guild.' This clearly states what the tool does and differentiates it from siblings like edit_role and create_channel. The purpose is unambiguous.

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

  Usage Guidelines3/5

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

  The description mentions the gating environment variable '[WRITE, gated behind DISCORD_MCP_ENABLE_WRITE=1]', which provides some usage context (write operations require this flag). However, it does not explicitly tell when to use this tool versus alternatives like edit_role or list_roles, nor does it list any exclusions.

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

• list_rolesB
  3.3/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure, but it only restates the action in slightly more detail. It does not mention required permissions, potential side effects, ordering, inclusions (e.g., @everyone), or any other behavioral traits beyond the name itself.

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

  Conciseness5/5

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

  The description is a single, concise sentence that immediately states the action and scope. Every word adds value, and there is no redundant or extraneous content.

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

  Completeness3/5

  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 and an output schema, the description is minimally adequate, but it lacks usage guidance and behavioral details such as permission requirements or context about what 'all roles' includes. The output schema likely explains the return shape, so that omission is acceptable, but the absence of usage context prevents a higher score.

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

  Parameters3/5

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

  The schema has 0% description coverage for guild_id, leaving the description to compensate. The phrase 'in a Discord guild' implies that guild_id identifies the guild, but it does not add any format, validation, or usage detail beyond what the parameter name already suggests. For a single obvious parameter, the description provides minimal but sufficient semantic support.

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

  Purpose5/5

  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 ('all roles in a Discord guild'), clearly distinguishing it from sibling tools like list_channels, list_categories, and get_member_roles. The scope is explicit ('all roles') and the target container is specified ('a Discord guild').

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use list_roles versus alternatives such as get_member_roles or list_channels. While the purpose is implicit from the name and context, there is no explicit context, exclusion, or mention of alternative tools.

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

• edit_channelA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses the write nature, the gating condition, and partial-update behavior, which is valuable. But it omits permission requirements, potential side effects on channel ordering, and reversibility, leaving gaps for a mutation tool.

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

  Conciseness5/5

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

  The description is a single sentence, front-loaded with the WRITE flag, and every word adds value. There is zero fluff, and it conveys core behavior efficiently.

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

  Completeness3/5

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

  For a 5-parameter tool, the description gives a high-level overview and notes partial updates, which is helpful. With an output schema present, return details are not needed. However, missing parameter constraints and prerequisites make it only minimally complete.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It maps actions to fields (rename->name, re-topic->topic, re-parent->parent_id, reorder->position) but does not explain constraints like position semantics, parent_id validity, or name rules. This is only partial compensation.

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

  Purpose5/5

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

  The description 'Rename/re-topic/re-parent/reorder an existing channel' clearly states the tool's verb+resource and specific operations. It distinguishes from siblings like create_channel, delete_channel, edit_role, and edit_guild by focusing on editing existing channels.

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

  Usage Guidelines3/5

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

  Implied usage is clear ('existing channel', 'only fields explicitly passed are changed'), and the WRITE gate provides a conditional prerequisite. However, there's no explicit comparison to alternatives or exclusions, leaving the agent to infer when to choose this over other edit/create tools.

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

• get_member_rolesA
  3.6/5.0
  Behavior3/5

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

  The description mentions 'currently assigned', which suggests it returns the live state of role assignments. Since there are no annotations, the description carries the burden, but it does not explicitly state that this is a read-only operation, nor does it disclose any permissions required or error behavior (e.g., what happens if the member is not found). The 'get' verb implies no side effects, and the specification of 'role ids' clarifies the return type, so it is minimally transparent but lacks deeper behavioral detail.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no unnecessary words. Every word contributes meaning: 'Get' indicates the action, 'role ids' specifies the output, 'currently assigned' adds temporal context, and 'one guild member' clarifies scope. It is appropriately concise.

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

  Completeness3/5

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

  For a simple tool with two clear parameters and an output schema, the description covers the core purpose. However, it lacks any guidance on usage relative to sibling tools (e.g., list_roles) and omits any mention of permissions or error handling. Since no annotations are present, the description alone is only partially complete; it tells what the tool does but not enough about when or under what conditions to use it.

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

  Parameters2/5

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

  The schema provides no descriptions for guild_id or member_id (0% coverage). The description does not elaborate on these parameters, leaving the agent to infer their meanings from the parameter names alone. While the names are self-explanatory, the description does not add value beyond the schema, and with no coverage, it fails to compensate. No information about formats, constraints, or relationships is provided.

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

  Purpose5/5

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

  The description clearly states the action ('Get') and the resource ('role ids currently assigned to one guild member'). It is specific about scope ('one guild member'), distinguishing it from sibling tools like list_roles (which likely lists all roles in a guild) and list_channels. The verb and target are unambiguous.

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

  Usage Guidelines3/5

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

  The description implies usage: if you need the role IDs of a specific member, this is the tool. However, it provides no explicit guidance on when to prefer this over alternatives like list_roles, nor does it mention any prerequisites or context. No exclusions or alternatives are named, so it relies on the reader to infer the appropriate use case.

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

• create_channelA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses the WRITE nature and the DISCORD_MCP_ENABLE_WRITE gate, which is useful, but it omits details about required permissions, failure behavior, or side effects beyond creation.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that packs the essential gate, verb, resource, and type flexibility without any fluff. Every word adds value.

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

  Completeness3/5

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

  The tool has moderate complexity with 5 parameters and no output schema description, but the existence of an output schema covers return values. The description lacks guidance on optional parameters and permission requirements, making it only minimally complete.

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

  Parameters2/5

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

  The schema has 5 parameters with 0% description coverage. The description partially explains `type` (any Discord-valid int) and implies `guild_id` via 'in a guild', but it does not clarify `name`, `topic`, or `parent_id`, leaving most parameters unexplained.

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

  Purpose5/5

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

  The description clearly states the tool creates a channel, a specific resource, and specifies the supported types (text/voice/category) via any Discord-valid `type` int. This distinguishes it from sibling tools like list_channels, edit_channel, and delete_channel.

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

  Usage Guidelines4/5

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

  The description clearly indicates the tool is for creating channels, and the write gate provides a prerequisite context. However, it does not explicitly mention when not to use it or reference alternatives like edit_channel for modifications.

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

• get_channel_permission_overwritesA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description must carry the transparency burden. It explains the data returned (allow+deny bitfields) and implies a read-only operation via 'Get', but does not explicitly state side-effect-free behavior, required permissions, or output format. The added bitfield context is useful but not comprehensive.

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

  Conciseness5/5

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

  The description is a single, tightly-written sentence that front-loads the verb and resource. Every phrase earns its place, explaining both what is retrieved and the structure of the data (bitfields). No redundancy or fluff.

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

  Completeness4/5

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

  For a simple single-parameter getter with an output schema present, the description adequately covers the tool's purpose. It mentions the key data structure (allow+deny bitfields) and implies the input. It is slightly incomplete in not explaining parameter specifics, but the output schema covers return details, and the tool's simplicity keeps it sufficiently complete.

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

  Parameters2/5

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

  Schema description coverage is 0% and the description does not elaborate on the channel_id parameter beyond implying it identifies a channel. It does not specify it's a snowflake ID, any format constraints, or how to obtain it. The description adds minimal value over the raw schema, leaving an agent to infer the parameter's exact semantics.

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

  Purpose5/5

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

  The description clearly states the verb 'Get' and the specific resource 'permission overwrites' with scope 'set on a single channel'. It distinguishes itself from siblings like list_channels or get_member_roles by focusing on overwrites for a channel, and adds clarity with 'role/member allow+deny bitfields'.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool: when you need the permission overwrites of a specific channel. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer appropriate usage. No direct mention of when-not-to-use lowers it from a 5.

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

• create_messageA
  4/5.0
  Behavior3/5

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

  With no annotations, the description must disclose behavioral traits. It mentions the write nature and the gating condition, adding value beyond the tool name. However, it does not describe potential failure modes, rate limits, or side effects, leaving room for more transparency.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the most critical information (write gate and action). Every part adds value, with no redundant or verbose content.

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

  Completeness4/5

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

  For a simple 2-parameter tool with an output schema, the description is nearly complete. It covers the purpose, a key usage constraint, and the access gate. It could mention prerequisites like valid channel ID, but that is largely implied, making it sufficiently complete.

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

  Parameters3/5

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

  The schema has 0% coverage, so the description must compensate. It provides meaningful constraints for 'content' (non-empty, max length 2000) but does not explain 'channel_id' beyond its obvious name. Partial compensation, but one parameter remains implicit.

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

  Purpose5/5

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

  The description clearly states the tool's action ('Post a message to a text channel') with a specific verb and resource. It is unambiguous and distinguishes itself from sibling tools, which are all channel/role management operations.

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

  Usage Guidelines4/5

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

  The description provides clear usage context, including the write gate (DISCORD_MCP_ENABLE_WRITE=1) and the content limit constraint. It does not explicitly mention alternatives or when not to use it, but given the sibling list, no alternative exists for sending messages, and the context is sufficient.

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

• delete_channelA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It explicitly warns that the operation is 'genuinely destructive and irreversible' and explains the write-gate requirement (DISCORD_MCP_ENABLE_WRITE=1). This goes beyond the schema and provides critical safety context, though it does not detail failure modes or permission requirements.

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

  Conciseness5/5

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

  The description is a single front-loaded sentence. It packs the essential information (what it does, the destructive nature, and the gating condition) without any redundant or tangential content. Every word earns its place.

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

  Completeness4/5

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

  The tool is simple (one parameter), and an output schema exists, so return values need not be explained. The description covers the most critical contextual aspect—irreversibility—and the write gate requirement. However, it omits details like error cases or permission needs, which might be expected for a destructive write operation. Overall, it is adequate but not exhaustive.

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

  Parameters3/5

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

  Schema coverage is 0%, so the description must compensate. It does not explicitly explain 'channel_id', but the tool name and phrase 'Delete a channel' make it clear the parameter identifies the channel to delete. For a single obvious parameter, this is minimally sufficient but adds no additional detail about format, constraints, or behavior.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb and resource: 'Delete a channel.' It is distinct from sibling tools like create_channel and edit_channel, and no other sibling performs deletion, so there is no ambiguity.

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

  Usage Guidelines3/5

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

  The description implies usage (when you need to delete a channel) but provides no explicit when-to-use guidance or comparisons to alternatives. The warning about destructiveness is context but not usage direction. It does not mention exclusions or prerequisites.

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

• list_channelsA
  4/5.0
  Behavior3/5

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

  No annotations provided, so description carries full burden. It implies a read-only operation by stating 'list', but does not explicitly disclose non-destructive behavior, authentication needs, or rate limits. For a simple list tool, this is adequate but not enhanced.

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

  Conciseness5/5

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

  One sentence that is clear, front-loaded with the main purpose, and contains no unnecessary words. Highly efficient.

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

  Completeness4/5

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

  Given the tool's simplicity (1 parameter, output schema exists), the description is nearly complete. It could mention behavior when no channels exist or pagination, but these are minor omissions.

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

  Parameters4/5

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

  The single parameter 'guild_id' is not described in the schema (0% coverage), but the description explains it by stating the tool lists channels 'in a Discord guild', effectively clarifying the parameter's role. The description compensates well for the lack of schema documentation.

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

  Purpose5/5

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

  Description clearly states the action (list), resource (all channels including categories and voice channels), and context (Discord guild). It's specific and distinguishes the tool from potential alternatives.

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

  Usage Guidelines3/5

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

  Description implies usage context (Discord guild) but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. Since no sibling tools are listed, the lack of exclusions is acceptable but still minimal.

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

• edit_guildA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly labels the operation as [WRITE] and reveals the gating behind an environment variable. It also explains the image format expectations for icon_base64/banner_base64 and points to the README for limitations. This goes beyond a bare description, though it does not cover all side effects or permissions.

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

  Conciseness5/5

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

  The description is compact—two sentences—and front-loads the critical WRITE designator and gating condition. Every word adds information, with no fluff. The inline formatting of base64 parameters is clear and concise.

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

  Completeness4/5

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

  The tool has an output schema and 5 parameters, but no annotations. The description covers the core purpose, the write gate, and the image format nuance. It omits details like merge semantics (e.g., whether null leaves a field unchanged) and does not explicitly state return values, though the output schema may cover that. Overall, it is sufficiently complete for a typical use, with a pointer to the README for deeper limitations.

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

  Parameters3/5

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

  Schema coverage is 0%, so the description must compensate. It names the updatable fields (name/icon/banner/description) and explains the format of icon_base64/banner_base64 in detail. However, it does not describe the remaining parameters (guild_id, name, description) in a way that adds value beyond their names. The key ambiguous parameters are covered, but the others rely on self-explanatory names.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Update guild-level identity (name/icon/banner/description).' The verb 'Update' and the resource 'guild-level identity' are specific and distinguish it from sibling tools like edit_channel and edit_role. It leaves no ambiguity about what this tool does.

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

  Usage Guidelines4/5

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

  The description implies when to use this tool (for guild-level settings, not channel/role edits) but does not explicitly name alternatives or state when not to use it. The mention of the write gate (DISCORD_MCP_ENABLE_WRITE=1) adds context about availability, but there is no direct comparison to sibling tools.

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

• edit_roleA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the transparency burden. It explicitly discloses that this is a write operation, gated behind an environment variable, and that only fields explicitly passed are changed (partial update). This adds important behavioral context beyond what the schema alone provides, though it doesn't discuss permission requirements or failure scenarios.

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

  Conciseness5/5

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

  The description is one concise sentence with a leading gate indicator. It is front-loaded with the write warning and immediately states the operation and update semantics. Every word earns its place with no waste.

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

  Completeness4/5

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

  The tool has an output schema, so return values need not be described. The description covers the core behavior (edit existing role, partial update) and the write gating. It doesn't mention required IDs, but those are in the schema. Overall, it's sufficient for an agent to understand the tool's primary contract, though a bit more context about the role being modified would push it to 5.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. It adds the key semantic that only explicitly passed fields are modified, implying nullable parameters mean 'no change'. However, it doesn't explain individual parameters; while names like 'name' and 'color' are self-explanatory, 'permissions' as a string could be ambiguous without additional context.

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

  Purpose5/5

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

  The description states 'Edit an existing role' which is a specific verb+resource pair. It clearly distinguishes this from create_role by specifying 'existing' and from edit_channel by targeting roles. The scope is clear and unambiguous.

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

  Usage Guidelines4/5

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

  The description implies usage for modifying existing roles, not creating new ones, and notes it is gated behind DISCORD_MCP_ENABLE_WRITE=1. It doesn't explicitly name alternatives, but the phrasing 'existing role' combined with sibling tool names like create_role makes the appropriate context evident.

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

• list_categoriesA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the transparency burden. It discloses a key behavioral trait: filtering is done client-side because Discord has no categories-only endpoint. This gives the agent useful context about potential performance/implementation characteristics, though it doesn't detail return format or rate limits (output schema covers return).

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

  Conciseness5/5

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

  The description is a single, tightly written sentence that front-loads the primary action ('List only the category channels') and adds essential context. Every word contributes value, with no redundancy or fluff.

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

  Completeness5/5

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

  Given the tool's simplicity, an output schema is present to define return values. The description covers the purpose, scope (category channels), and the key implementation detail (client-side filtering). No critical information is missing for an agent to use it correctly.

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

  Parameters3/5

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

  The single parameter, guild_id, is not described in the schema (0% coverage). The description only mentions 'in a guild', which implicitly refers to the guild_id but does not explicitly explain the parameter's format or role. Since the parameter name is self-explanatory, this is adequate but not thorough.

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

  Purpose5/5

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

  The description clearly states the tool lists only category channels (Discord channel type 4) in a guild, using a specific verb and resource. It distinguishes itself from sibling tools like list_channels by explicitly scoping to categories only and noting the client-side filtering.

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

  Usage Guidelines4/5

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

  The description implies when to use this tool: when you need only category channels. It also explains the lack of a dedicated Discord endpoint, which justifies the tool's existence. However, it doesn't explicitly state when not to use it or mention alternatives like list_channels for all channels.

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