discord-mcp
Server Quality Checklist
Latest release: v0.22.0
- Disambiguation3/5
Each tool has a detailed description with clear when-to-use and when-not-to-use guidance, and most tools target distinct resources and actions. However, with 208 tools, there are many closely related pairs (e.g., webhooks_get vs webhooks_get_with_token, guild_get_widget vs guild_get_widget_settings) that an agent could easily confuse, and the sheer volume increases misselection risk.
Naming Consistency3/5The majority of tools follow a resource_action pattern (e.g., messages_send, channels_list, roles_modify), but there are notable inconsistencies: 'users_get_current' vs 'members_get_current_user', generic 'guild_modify' alongside specific 'guild_modify_widget', and non-standard names like 'intelligence_summarize_channel' and 'mcp_pipeline' that break the pattern. The overall mix is still readable but not uniform.
Tool Count1/5208 tools is an extreme number for any MCP server, far exceeding the 50+ threshold for a mismatch. While Discord's API is broad, this many tools creates an overwhelming selection surface for agents and suggests the server would benefit from consolidation or splitting into focused sub-servers.
Completeness4/5The tool set covers an impressively wide range of Discord resources: channels, messages, members, roles, permissions, webhooks, automod, commands, interactions, voice, stage, soundboard, onboarding, entitlements, and more. Minor gaps exist, such as lacking a dedicated private-thread creation tool (only forum threads or anchored public threads are supported) and no file-upload tool, but these are edge cases and most workflows are fully supported.
Average 4.4/5 across 200 of 208 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 181 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, destructive, and idempotent hints. The description adds the useful behavioral detail about immediate propagation and lists the return fields. However, it does not disclose permission requirements or the exact semantics of 'upsert' (e.g., whether an existing command is replaced).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with clear bold section headers. It front-loads the purpose and returns, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 15 parameters and extremely low schema description coverage, this description is too sparse. It provides no guidance on how to structure command options, permissions, or use cases, and the output schema does not compensate for the missing parameter context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, and the description adds virtually no parameter-level meaning. It mentions 'guild-scoped' but does not explain the required application_id, guild_id, name, or the many optional fields. The description fails to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Create or upsert a guild-scoped slash command.' It also distinguishes from the global variant by noting that guild commands propagate immediately, which aligns with the sibling tool commands_create_global.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use this tool versus the global alternative by highlighting the propagation timing difference. It does not explicitly exclude other alternatives like bulk overwrite, but the guild-vs-global contrast provides actionable usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is non-read-only and non-destructive. The description adds that it sends a message and returns message metadata, which is useful. It does not disclose additional side effects or failure modes, but the annotation coverage keeps the baseline at 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with bold section labels for Purpose, Templates, and Returns. Every sentence carries information, 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema, output schema, and annotations, the description is complete for a send-from-template tool. The only shortcoming is the confusing 'v1' reference, but this does not materially impact the agent's ability to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters with full coverage, including enums and descriptions. The description adds the note that each template declares a variables list, which helps understand the vars object, but this is marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('apply variables to a built-in V2 template and send the result') and lists the exact template names, which differentiates it from generic send or preview tools. However, the use of 'Templates v1' alongside 'V2 template' introduces minor 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use this tool (sending template-based messages with variable substitution), and the return format gives some context. However, it does not explicitly mention alternatives like components_v2_preview for previewing or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: auth requirements ('token-secured (NO bot token)'), body semantics ('mirrors webhook execute body'), and return value ('{message_id, channel_id}'). This supplements the idempotentHint and readOnlyHint 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured with labeled sections (Purpose, Auth, Body, Returns). Every line adds distinct value with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose, auth, body reference, and return shape, which is helpful for a complex 11-parameter tool. However, it omits usage guidelines and detailed parameter semantics, leaving gaps that an agent must resolve by referencing webhook execute schema or sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 27%, and the description does not explain individual parameters beyond referencing 'webhook execute body'. While this hint is useful, it lacks concrete details for the 11 parameters, especially for an agent not deeply familiar with Discord's webhook execute format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Edit a follow-up message' with a specific verb and resource. It distinguishes itself from sibling tools like interactions_edit_original_response and messages_edit by explicitly targeting follow-up messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance or comparison to alternatives is provided. The description does not mention when to use this tool instead of interactions_edit_original_response or webhooks_edit_message, making it hard for an agent to select between similar edit tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the return structure (skus array with fields and count), but does not mention pagination, filtering, or any rate limits. This is reasonable for a simple list tool, but the additional context is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two clear sections: Purpose and Returns. Every sentence adds value, and the key information is front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, rich annotations, and an output schema), the description sufficiently covers what the tool does and what it returns. The main missing element is usage context, but that is not critical for such a straightforward read-only listing operation. Could be improved by noting openWorld semantics, but it is already adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the only parameter (application_id) has a clear description in the schema. The tool description does not add any additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource as 'your application's SKUs (premium offerings)'. This clearly distinguishes it from related pricing/entitlement tools and makes the operation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as entitlements_list or subscriptions_list. The description only states what it does, not when it should be preferred, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the tool read-only, idempotent, and non-destructive. The description adds the scoping context ('on a SKU') and mentions the return shape, but does not disclose any additional behavioral traits such as authentication requirements or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two clearly labeled sections (Purpose, Returns) front-loaded. Every sentence is informative and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation, the description, combined with full schema coverage and rich annotations, is largely sufficient. However, it lacks any guidance on when to use this tool vs alternatives, which would have made it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are documented in the schema with descriptions ('Parent SKU', 'Subscription to fetch'), and the schema description coverage is 100%. The tool description adds no extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a single subscription on a SKU' – a specific verb (fetch), resource (subscription), and scope (SKU). The word 'single' differentiates it from subscriptions_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like subscriptions_list. The description provides no exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds useful behavior: 'All command-body fields are optional' and the return shape. However, it does not disclose permissions, rate limits, or error behavior, so it provides only moderate value 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tightly scoped sentences with clear 'Purpose' and 'Returns' labels. Every word earns its place; there is no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 16 parameters, complex nested option objects, and annotations like openWorldHint, the description gives only a one-sentence purpose and a brief return example. It lacks guidance on partial edits, field constraints, required IDs, or how the many optional parameters relate to the command body, making it insufficient for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 19%, and the description does not compensate for the many undocumented parameters. It says 'All command-body fields are optional', which conveys partial-update semantics, but it never defines what counts as a 'command-body field' or explains the roles of parameters like handler, contexts, integration_types, or nsfw.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Edit a guild-scoped command', a specific verb+resource+scope combination that clearly identifies the tool's function. This also distinguishes it from sibling tools like commands_modify_global or commands_get_guild by explicitly stating 'guild-scoped'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'guild-scoped command' provides clear context for when this tool is appropriate versus global-command tools. However, it does not explicitly mention alternatives or exclusions, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds 'Returns entitlement shape,' which is redundant given the output schema and does not provide additional behavioral context such as error behavior or permission requirements. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short lines, immediately gives the purpose, and avoids filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple getter with two fully documented parameters, an output schema, and annotations covering safety and idempotency. The description is adequate for the low complexity, though it could slightly benefit from an explicit usage pointer to sibling tools. Overall, it is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—both application_id and entitlement_id have descriptive text with patterns. The description adds no extra parameter-level meaning, so it relies fully on the schema, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Fetch a single entitlement'—a specific verb and resource, and the word 'single' clearly differentiates it from sibling tools like entitlements_list or entitlements_consume. It is unambiguous and front-loaded.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving one entitlement by ID but does not explicitly name alternatives or when-not-to-use. It contrasts with 'single' vs. list but never mentions entitlements_list or other sibling tools, leaving the guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the MANAGE_GUILD permission requirement and warns that template names and descriptions are raw Discord data that should be reviewed before treating as instructions, which is valuable security context. It also specifies the return structure. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three labeled sections (Purpose, Requires, Returns), each sentence earning its place. It's front-loaded with the purpose and uses clear formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, permission requirement, return shape, and includes a security warning about untrusted text. However, it doesn't explain how this tool differs from sibling template tools (e.g., when to use templates_get instead), which is a minor gap for an agent choosing among many template tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter (guild_id) with a description, so the description adds limited value. It clarifies that templates belong to the caller bot and applies to one guild, but this is largely redundant with the schema and purpose. Baseline 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists the caller bot's Guild Templates for one guild, with a specific verb, resource, and scope. It does not explicitly distinguish from sibling template tools like templates_get or templates_inspect, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the permission requirement (MANAGE_GUILD) and mentions the return shape, but it gives no explicit guidance on when to use this tool versus alternatives such as templates_get or templates_create. The usage is implied by the purpose, so it's a 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the burden. The description adds the endpoint location and a summary of returned fields, but adds no context about auth requirements, error conditions, or 404 behavior if the user is not in a voice channel.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly scoped sections (Purpose and Returns) with zero filler. The purpose is front-loaded in the first sentence, and the endpoint path provides immediate orientation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool, the combination of annotations (read-only, idempotent), full schema coverage, and an output schema covers most needs. The description adds purpose and return-shape context. A brief note on error cases (e.g., user not in a voice channel) would make it fully complete, but it is already adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both guild_id and user_id are documented as 'Guild to query' and 'Member whose voice state to fetch.' The description adds no further parameter detail beyond hinting at {guild.id} and {user.id} in the endpoint path, so it meets the baseline without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and names the exact resource ('a user's voice state in a guild'), backed by the full REST endpoint path. It clearly distinguishes this from siblings like voice_get_current_user_state (current user only) and guild_modify_user_voice_state (modification, not fetch).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the fetch verb and endpoint path — this tool queries a specific user's voice state in a specific guild. However, no explicit exclusions or alternatives are named (e.g., 'for your own state use voice_get_current_user_state'), so an agent must infer when to prefer this over the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and the description adds that name/description remain raw while untrusted_text provides a separately fenced copy, which is useful behavioral context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with purpose, followed by a brief usage instruction and return summary. No filler, each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema provides return structure and annotations cover safety, the description leaves many parameters unexplained and lacks details about field constraints or side effects. It covers core behavior but is incomplete for a 13-parameter mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 8%, and the description does not explain the meaning or usage of most parameters (tags, install_params, integration_types_config, etc.). It only mentions the return fields and generic partial-update guidance, so agents lack necessary semantic detail for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Edit the bot/app application object (PATCH /applications/@me)' with a specific verb and resource, distinguishing it from siblings like application_get_current and application_modify_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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit instruction to pass only fields to change and notes all fields optional, guiding usage. However, it does not explicitly contrast with alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-destructive behavior. The description adds that it returns an updated {id, name, description, type, application_id} and that only changed fields should be sent, which is useful 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sections, front-loaded with purpose, followed by return value. Every sentence adds value without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity (15 parameters, partial updates, global scope), the description omits parameter details, prerequisites, error behavior, or when to use it over alternatives. The return value is mentioned, but overall the description is too sparse for an agent to invoke this correctly without additional schema parsing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 13% with 15 parameters. The description mentions 'command-body fields' as a group but does not enumerate or explain specific parameters. It conveys that fields are optional for partial updates, which is helpful, but it 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Edit a global application command', which is a specific verb+resource. The word 'global' differentiates it from guild command modifiers, and the partial-update note clarifies the operation's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states the tool is for global application commands and gives usage guidance ('All command-body fields are optional - pass only what changes'). However, it does not explicitly name alternative tools (e.g., commands_modify_guild) or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the return shape ({entitlements:[...], count}), which helps the agent understand the output despite the output schema existing. It doesn't discuss pagination or filtering behavior beyond what the schema implies, but with strong annotations and a simple list operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short lines: a purpose statement and a return type declaration. Every word earns its place, and the use of bold labels ('Purpose', 'Returns') improves scannability. No fluff, filler, or repetition of schema contents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters, an output schema, and rich annotations. The description covers the purpose and return shape, which is the core. It doesn't elaborate on pagination behavior or the meaning of the less-documented optional parameters, but for a straightforward list operation with an output schema and clear annotations, it is mostly complete. The slight gap is the lack of guidance on filter combinations (e.g., using sku_ids vs user_id), which would be useful for complex queries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 56%, meaning several parameters (after, limit, before, exclude_ended, exclude_deleted) lack descriptions in the schema. The description does not enumerate or explain these parameters, so the agent must infer their semantics from names alone. However, the parameter names are domain-standard (Discord pagination fields like after/before/limit, boolean filters), and the core required parameter application_id is described. The description's mention of 'for an application' reinforces the main parameter but does not compensate for the undocumented optional parameters. Given 56% coverage, the description could add more, but it does provide the key return structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List entitlements for an application' with a specific verb and resource, and the phrase 'for an application' scopes it to the required application_id parameter. It distinguishes from sibling tools like entitlements_get by focusing on listing, though it doesn't explicitly name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage ('List entitlements for an application') but does not provide explicit guidance on when to use this instead of entitlements_get, entitlements_consume, or entitlements_create_test. There are no exclusions or alternative tool references, leaving it to the agent to infer from the tool name and general list vs. get patterns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only generic hints (readOnlyHint=false, openWorldHint=true). The description adds meaningful constraints (base64 data URI, max 512 KB raw) and return shape, which helps, but it doesn't disclose permissions, rate limits, or failure behavior. It carries some burden beyond annotations but not exhaustively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, well-structured with bold labels, and every sentence adds value: purpose, key constraint, and return. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7-parameter schema, output schema, and annotations, the description adequately covers the most complex parameter (sound) and expected returns. It doesn't discuss errors or prerequisites, but the essential details are present. It could mention alternatives to sibling tools, but that overlaps with usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 100% of parameters, but the description adds the crucial 'max 512 KB raw' constraint on sound not present in the schema. It also summarizes the return object, reinforcing parameter meanings. This goes beyond the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Upload a new soundboard sound to a guild' with a clear verb and resource. It naturally distinguishes from siblings like soundboard_modify_guild_sound and soundboard_delete_guild_sound by emphasizing 'new'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use it (creating a new sound), but it doesn't explicitly compare to alternatives like modify or delete. There's no 'when not to use' or mention of sibling tools, so guidance remains implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description adds crucial behavioral details: it is 'IRREVERSIBLE', requires a confirmation flag and MCP_DRY_RUN=false to execute, and states the return shape. This significantly informs the agent about execution constraints and consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured with clear labels: Purpose, Returns, Security. Every sentence conveys essential information (what it does, output shape, execution gate), with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action, the description covers the essential context: outcome (delete), irreversibility, confirmation gate, dry-run behavior, and response format. It does not mention needed permissions, but the annotations and schema offset that gap, making it sufficiently complete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for all parameters, including the IRREVERSIBLE note on sound_id and the purpose of __confirm. The description adds only minor emphasis (e.g., 'DESTRUCTIVE') without new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete a guild soundboard sound', providing a specific verb and resource. It clearly distinguishes this from sibling tools like soundboard_modify_guild_sound or soundboard_get_guild_sound by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly name alternatives or state when not to use this tool. While the destructive nature and confirmation requirement are clear, there is no guidance on e.g., using a modify operation for reversible changes. The purpose implies usage but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent, lowering the burden. The description adds useful behavioral nuance: the return object shape is stated, and the distinction that 'name remains raw Discord data; untrusted_text provides a separately fenced copy' is a non-obvious implementation detail that goes beyond annotations. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with clear bolded headings for 'Purpose' and 'Returns'. It front-loads the core purpose immediately and uses minimal, high-signal wording. Every phrase 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (simple ID-based fetch) and the presence of an output schema, the description is nearly complete. It even goes beyond the schema by explaining the raw-name vs. fenced untrusted_text nuance. A minor gap is the absence of error or edge-case behavior, but annotations cover the read-only safety profile, so this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (guild_id and sound_id) are already fully described in the input schema with string types and patterns, giving 100% schema description coverage. The description adds no additional parameter meaning or usage syntax; it relies entirely on the schema. This meets the baseline of 3 but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear specific verb+resource: 'Fetch a single guild soundboard sound.' This directly distinguishes it from siblings like soundboard_list_guild_sounds (list) and soundboard_create_guild_sound (create). The 'single' qualifier reinforces that this targets one item by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating 'Fetch a single guild soundboard sound'—this suggests using it for a specific sound rather than listing. However, it does not explicitly contrast with alternatives or state when not to use it. No exclusion criteria or when-to-use guidance is provided beyond the inherent singular nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the mutation behavior is known. The description adds that it starts a Stage instance and the return payload, but it does not disclose additional behavioral details such as permission requirements, side effects like notifications, or the fact that only one stage instance can be active per channel. This is acceptable given 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose, when to use, and returns. Every section earns its place, and it is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a moderate parameter count (6) but the schema thoroughly documents each parameter, and the output schema is defined. The description covers usage and return fields, making it complete enough for an agent to invoke correctly. Minor omissions like error scenarios do not significantly diminish completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are explained in the input schema. The description only mentions the return object and not the parameters, so it adds no parameter-level meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Start a Stage instance (live event in a Stage channel)' with a specific verb and resource. It distinguishes from sibling tools like stage_instances_get, stage_instances_modify, and stage_instances_delete by indicating a create operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section provides a clear use case ('Begin a public talk/AMA in a stage channel'), giving context for when to invoke this tool. It does not explicitly exclude other scenarios, but for this straightforward creation tool, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context: partial-update semantics ('Pass only fields you want to change') and a security note about 'untrusted_text' being a separately fenced copy of raw user-authored topic. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with bold section labels, and front-loaded with the purpose. Every sentence adds value: purpose, usage guidance, and return/security information, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation tool with an output schema and annotations, the description covers purpose, partial-update behavior, return shape, and a security note. It lacks explicit alternative guidance and privacy_level value details, but these are partially addressed by schema and siblings; overall it is complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with topic and privacy_level lacking descriptions. The description names these as the modifiable fields and clarifies partial updates, but it does not explain privacy_level allowed values or topic constraints beyond the schema's bare type. It partially compensates for the coverage gap but leaves semantic gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Modify' and the resource 'live Stage instance (topic / privacy_level)', providing a specific action and scope. This distinguishes it from sibling tools like stage_instances_create, stage_instances_get, and stage_instances_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for changing an existing Stage instance but does not explicitly state when to use this tool versus its siblings or provide exclusions. 'Pass only fields you want to change' is a parameter-level guideline, not a tool-selection guideline, so clarity on alternatives is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds a useful detail about the 'description' field being raw user-authored data and that the human-readable response fences it, but otherwise does not provide rich behavioral context beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with clear sections: Purpose, When to use, Returns. Every sentence adds value, no padding or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple public get tool with strong annotations, an output schema, and one parameter, the description covers purpose, usage context, and return fields. It lacks error/edge-case details but these are not necessary at this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter sticker_id has a description in the schema. The tool description adds no significant parameter meaning beyond that, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Public lookup of a single sticker by ID'. It also distinguishes from siblings by noting 'no guild context', which separates it from stickers_get_guild_sticker and other sticker tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a 'When to use' section specifying to resolve sticker IDs from messages or pack responses. It also implies exclusion of guild stickers via 'no guild context', but does not explicitly name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the read-only nature. The description adds the return shape ({subscriptions:[...], count}) and the SKU scoping, which 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with only two sections: purpose and return. Every sentence is informative and front-loaded, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description provides the essential purpose and return shape. Annotations and schema cover safety and parameters, so the description is complete enough. It doesn't mention pagination, but the schema's limit/after/before parameters implicitly cover that, and an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so most parameters are already described in the schema. The description adds no additional parameter context, which is acceptable since the schema carries the burden. No param info is provided in the description, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List subscriptions for a SKU,' which is a specific verb and resource. It distinguishes this tool from siblings like subscriptions_get (single subscription) and entitlements_list (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose statement implies when to use the tool (listing subscriptions for a SKU), but it does not explicitly mention alternatives or exclusion criteria. No guidance is provided on when to use another tool like subscriptions_get instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds the return shape and a 'verify exists' use case, but no additional behavioral context like error handling or permissions. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, front-loaded with the purpose, and well-structured with clear sections for purpose, when to use, and returns. Every sentence serves a functional role with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation with complete schema, rich annotations, and an output schema, the description provides adequate context including purpose and practical use cases. It is fully complete 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters (application_id and emoji_id) with descriptions, providing 100% coverage. The description does not add any extra meaning beyond what the schema already includes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Fetch a single application emoji' with a clear verb and resource. It distinguishes itself from sibling tools like app_emojis_list by focusing on a single item and from guild emoji tools by specifying 'application' scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section provides clear scenarios (verify existence, inspect name/animated flag). However, it does not explicitly mention alternatives or when not to use it, such as when to prefer emojis_get or app_emojis_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 scope ('all channels') and return format, but the return format is also present in the output schema, so it adds limited extra behavioral 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with bold section labels for Purpose, When to use, Example, and Returns. Every sentence is purposeful and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description covers purpose, usage, example, and return shape. It is fully sufficient for an AI 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a full description for guild_id with 100% coverage. The description includes an example value but not additional semantic detail beyond what the schema already offers, so it does not raise the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all channels in a Discord guild' using a specific verb and resource. This distinguishes it from sibling tools like channels_get, which retrieves a single channel, and channels_list_active_threads_guild, which lists threads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases: 'discover channel IDs by name; audit channel layout'. This gives clear context for when to use the tool, though it does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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 context about the type (17) and the return value being a nestable node, but it does not add richer behavioral detail (e.g., validation behavior or side effects), which is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, uses clear labels (Purpose, When to use, Returns), and front-loads the main purpose. Every sentence earns its place with no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a pure builder tool with good annotations, a complete schema, and an output schema, the description is fully adequate. It explains what it builds, when to use it, and exactly where to use the returned node (inside components_v2_send). No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter descriptions are already detailed (e.g., 'Wrap container in spoiler tag', 'Hex RGB integer (0xFF0000 = red)'). The description reinforces the roles of accent_color and components ('accent color + multiple sections/separators') but does not meaningfully add beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Build'), names the exact resource ('Components V2 Container (type 17) JSON node'), and clearly distinguishes this from siblings like components_v2_build_section and components_v2_build_media_gallery. It also clarifies the output is meant for components_v2_send.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section provides a clear context: 'compose a card with accent color + multiple sections/separators.' It does not explicitly name alternatives or say when not to use this tool, but the context is specific enough to differentiate from sibling builders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent write operation. The description adds valuable behavioral context about the irreversible IS_COMPONENTS_V2 flag and that only messages sent by this bot can be edited, which is beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two labeled sections. It front-loads the purpose and includes a concise return type without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, key behavioral constraint, and return format. Given the tool's moderate complexity and the presence of an output schema, the description is largely complete, though it could elaborate on components structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers channel_id and message_id with descriptions, but the components parameter has no description in either the schema or the tool description. The description does not explain the expected structure or content of components, leaving a significant gap for the core input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Edit a Components V2 message previously sent by this bot,' clearly identifying the action and target. It also differentiates from siblings like messages_edit and components_v2_send by noting the V2 specificity and the irreversible flag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for editing existing V2 messages sent by the bot, implying it is not for sending new ones or editing regular messages. However, it does not explicitly name alternatives or state when-not-to-use, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds examples of integration types and the return shape, but no additional behavioral context like auth requirements or rate limits. This is acceptable 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-organized with Purpose/When to use/Returns, and every sentence adds value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter list tool with strong annotations and a described return structure, the description covers purpose, usage, and output adequately. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% ('Guild to query' for guild_id). The description does not add extra parameter meaning beyond the schema, which is fine given the schema's clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), resource ('integrations attached to a guild'), and adds clarifying examples (Twitch, YouTube, application bots). This distinguishes it from sibling tools like guild_delete_integration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear context for use ('Audit which third-party integrations exist before deletion'). It doesn't explicitly name alternatives or exclusions, but the audit-before-deletion use case gives practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 return shape details (regions with id, name, optimal, deprecated, custom) and notes VIP regions, but does not disclose rate limits, permissions, or other behavioral traits. This is a modest addition 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinctly organized with bolded Purpose, When to use, and Returns sections. It is front-loaded with the main purpose and contains no unnecessary words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only list operation with one parameter. The description covers purpose, usage, and return format, while annotations cover safety and idempotency. It is fully complete for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, guild_id, is fully described in the schema as 'Guild to query' with 100% coverage. The description adds no additional parameter-specific information, so it remains at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List voice regions available to a guild (incl. VIP regions)' with a specific verb and resource. It distinguishes from the sibling 'voice_list_regions' by explicitly mentioning guild scope and VIP inclusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section gives a concrete scenario: 'Pick an rtc_region for a voice/stage channel.' This provides clear context but does not explicitly mention alternatives or when not to use the tool, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 established. The description adds a useful limitation (only one emoji at a time; use messages_get for all) and return shape, but does not discuss pagination iteration, ordering, rate limits, or other runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with focused sections for purpose, usage, exclusions, example, and return value. It is not bloated, though the 'Returns' section partially duplicates what an output schema would provide.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema, complete annotations, and clear usage guidance, the description covers nearly all necessary context. It could be slightly improved by explicitly stating that results are paginated and that 'after' should be used to fetch subsequent pages, but the schema already documents the cursor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All six parameters already have full descriptions in the schema (100% coverage), so the baseline is 3. The description's example and inline emoji mention add no semantic meaning beyond the schema, which already documents after, limit, type, channel_id, message_id, and emoji constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening 'Purpose' line names an explicit verb ('List'), a resource ('users who reacted'), and a scope ('with a specific emoji'), clearly distinguishing it from sibling tools like messages_get that return all emojis. It also reinforces the one-emoji scope in the 'When NOT to use' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated 'When to use' section with concrete use cases ('Inspect poll results; identify upvoters') and a 'When NOT to use' section that explicitly names messages_get as the alternative when all emojis are needed. This gives the agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the return structure but does not disclose additional behavioral traits such as pagination, permission requirements, or ordering. It adds moderate value 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured with bolded labels for Purpose, When to use, Example, and Returns. Every sentence adds value and there is zero wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 required parameter and an output schema, the description covers everything an agent needs: what it does, when to use it, an example call, and the return shape. Annotations cover safety, so nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter guild_id, which is documented as 'Guild to list roles for'. The description provides an example JSON usage, but that does not add meaning beyond the schema's type and pattern. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List all roles in a guild', using a specific verb and resource with clear scope ('all roles'). This clearly distinguishes it from sibling tools like roles_create, roles_modify, and roles_delete, which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a dedicated 'When to use' section listing concrete use cases: discover role IDs, audit hierarchy + permissions. It does not explicitly mention when not to use or name alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by specifying the 'DESTRUCTIVE - IRREVERSIBLE' nature, the lack of an Authorization header, the need for __confirm:true and MCP_DRY_RUN=false to actually delete, and the return shape. These are actionable behavioral details not present in 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded sections (Purpose, When to use, Auth, Returns) and is concise. Every sentence adds value, and it is front-loaded with the core purpose and destructiveness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive webhook operation, the description covers the purpose, trigger conditions, auth specifics, return value, and the mandatory confirmation flow. It is nearly complete, but it does not mention typical edge cases (e.g., message not found, rate limits) or explicitly guide towards alternative tools in different auth contexts. Given the output schema presence, this is sufficient but not perfect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 repeats some parameter details already in the schema (token as secret, __confirm behavior, MCP_DRY_RUN), but adds no new parameter-level semantics beyond that. It is simply redundant with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Delete a message previously sent by this webhook.' This is a specific verb+resource pairing. However, it does not explicitly differentiate from sibling tools like messages_delete or webhooks_delete_with_token, so it misses the top score for sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear 'When to use' section with concrete examples (retract stale alerts or accidentally posted content). This gives context but does not mention when not to use this tool or name alternative tools, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnly=false, idempotent=true, destructive=false. The description adds the platform constraint that Discord does not allow editing emoji bytes, and it specifies the return shape. This goes beyond the annotations, though it doesn't discuss permissions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headers (Purpose, When to use, When NOT to use, Returns). Every section is concise and informative, with no wasted words. The length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, exclusions, and return value. The presence of an output schema and annotations reduces the burden on the description. Still, it could mention whether any permissions are required or what happens if the name is omitted, but these are minor gaps for a simple rename tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds minimal semantic value beyond the schema, though it implies the 'name' parameter is essential for renaming. It does not clarify why 'name' is not listed as required in the schema, which is a slight gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Rename') on a specific resource ('application emoji'), which distinguishes it from related tools like emojis_modify (guild emojis) and app_emojis_create/delete. The purpose is direct 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear 'When to use' section and a 'When NOT to use' section with a concrete example (replacing image bytes). It does not explicitly name alternative tools, but the context is sufficient to infer when this tool is appropriate. The exclusion is valuable and prevents misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing that Discord rejects a Section without an accessory, which is a key behavioral constraint. It also states the return type is a Section JSON node, which is helpful. The annotations already mark the tool as read-only and idempotent, and the description does not contradict that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections: Purpose, When to use, and Returns. Each sentence earns its place, and the key information is front-loaded. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (2 params, one complex accessory schema) and the existence of an output schema, the description covers the essential context: what the tool does, when to use it, and what it returns. It does not explain the accessory variants in detail, but the schema fully covers that, so the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already described in the schema ('1-3 markdown text lines' and 'Required Thumbnail (type 11) or Button (type 2)'). The description essentially restates this, adding only the emphasis on the accessory being REQUIRED. No new parameter-level meaning is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear action verb 'Build' and specifies the resource 'Components V2 Section (type 9)'. It further differentiates from sibling tools by noting the section requires 1-3 TextDisplay lines plus a Thumbnail or Button accessory, which is distinct from container or media gallery builders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides a 'When to use' section: 'card-like content with header + supporting text + image'. This gives clear context, though it does not explicitly state when not to use or name alternative tools. It is still enough to guide selection among the sibling builder tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds valuable context that this creates a test entitlement for simulation, and it also specifies the return format. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two clear sections: Purpose and Returns. There is no wasted text; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, full parameter schema, and annotations, the description provides sufficient context. It covers purpose, use case, and return format, leaving little ambiguous for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all four required parameters. The description does not add additional parameter-level meaning, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Create a test entitlement (dev tool). Lets devs simulate that a user/guild owns a SKU.' This distinguishes it from sibling tools like entitlements_list, entitlements_consume, and entitlements_delete_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is for development/simulation purposes, implying when to use it. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations cover read-only, idempotent, and non-destructive behavior, so the description correctly avoids repeating that. It adds valuable details about pagination cursors and the return shape, which are behavioral traits not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with bold section headers. Every sentence earns its place: purpose, when to use, pagination, and return format. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's read-only nature, the description covers the essential aspects: purpose, usage context, pagination behavior, and return format. An output schema is present, so detailed field explanations are not required. Missing permission/error details are minor for this simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the baseline is 3. The description reinforces the pagination semantics and limit range, but does not introduce additional meaning beyond what the schema already provides. The return format is helpful but not parameter-related.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List users subscribed (RSVP)') and the resource ('scheduled event'), making it easy to distinguish from sibling tools like events_list or events_get. The purpose is specific 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated 'When to use' section explaining the primary use case (inspect attendance/interest). It does not explicitly mention alternatives or when not to use it, but the context is clear enough for an agent to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and destructive=false. The description adds important behavioral context beyond annotations: it uses the client's LLM and makes no Discord API call, which implies token costs and internal processing rather than API side effects. This is meaningful but does not cover potential LLM non-determinism or error cases, so a 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured with bolded 'Purpose', 'When to use', and 'Returns' sections. Every sentence earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich output schema (indicated), so the Returns section is redundant but harmless. The description covers purpose, usage, and return shape completely. It could mention prerequisites (e.g., client LLM availability) or limitations, but given the annotations and schema, it is sufficiently complete 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: 'content' is described as 'Text to moderate' and 'policy' as 'Moderation policy in plain language' with a default. The description's mention of 'plain-language moderation policy' adds no new parameter meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Apply') and resource ('a plain-language moderation policy to a piece of text'), and explicitly distinguishes it from Discord API calls and other intelligence tools by calling it 'purely a moderation utility' and naming the return decision (allow/flag/block). This differentiates it from siblings like intelligence_classify_messages and intelligence_summarize_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists three explicit scenarios: pre-check user-submitted content, second-opinion on AutoMod decisions, and classifying ambiguous messages. This gives clear context but does not mention when NOT to use or alternative tools, so it falls 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: it specifies token-secured auth with NO bot token, and details the return format including the raw content vs separately fenced `untrusted_messages`. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is remarkably concise and well-structured with bolded labels (Purpose, Auth, Returns). Every section delivers necessary information without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation, the description is quite complete: it explains the purpose, auth requirements, and return format. It could mention error scenarios or prerequisites (like needing to have created a response first), but these are minor gaps given the strong schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with detailed descriptions for both parameters (application ID and interaction token as a scoped credential). The description does not add additional parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches the original interaction response message created by `interactions_create_response`. This specific verb+resource combination with the reference to the creating function distinguishes it from follow-up retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to retrieve the original response), but it does not explicitly state when not to use it (e.g., for follow-ups) or name alternatives like `interactions_get_followup`. Usage context is clear but exclusionary guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that only 'nick' is currently supported, and importantly notes that no MANAGE_NICKNAMES permission is needed—information not present in the annotations. It also indicates the return value, adding behavioral context beyond the readOnly/idempotent hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise, with clearly labeled sections (Purpose, When to use, Returns). No fluff or redundancy; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with an output schema, the description covers the tool's scope (nick only), key use case, and return value. It doesn't discuss error cases or the audit_reason parameter, but the schema covers those; overall it's sufficiently complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds little beyond the schema, merely restating that 'nick' is the primary field and can be set or cleared, which aligns with the schema's anyOf string/null.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Modify' and identifies the exact resource: 'current bot user's own guild member entry.' It also scopes the operation to 'currently only nick,' clearly distinguishing it from sibling tools like members_modify which handles other members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit 'When to use' section: 'Set/clear the bot's nickname in a guild without needing the MANAGE_NICKNAMES permission.' This gives clear context for when this tool is preferred, though it doesn't explicitly list alternative tools or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly=false, openWorld=true, idempotent=true, destructive=false. The description adds important context: it clarifies full-replace behavior, warns about the safe disabled configuration, and notes requirements for enabling. This goes beyond the annotations' boolean hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three short sections) and uses bold labels for quick scanning. It includes a relevant documentation link and no filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex modify operation, the description covers purpose, full-replace semantics, enabling requirements, and return shape. Given the rich output schema and annotations, this is sufficient, though it omits permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 6 parameters with descriptions, so baseline is 3. The description adds a link to Discord docs for prompt structure and mentions the default channel requirements, but doesn't elaborate on individual parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear action: 'Replace a guild's onboarding configuration (PUT - full replace).' This is specific and distinguishes the tool from sibling `onboarding_get` and other modify tools. The full-replace semantics are explicitly stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by stating it is a full-replace operation and lists enabling requirements (at least 7 default channels, 5 with @everyone), which helps an agent know prerequisites. However, it does not explicitly name alternatives or when-not-to-use, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the agent knows the safety profile. The description adds value by disclosing the exact return shape, including the `untrusted_text` field and the note that usernames are raw Discord data, which is behavioral 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with bold labels for Purpose, Path, and Returns. It front-loads the core purpose, keeps the path separate for clarity, and the return summary is concise with no filler or redundant statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent operation with complete parameter documentation and an output schema, the description covers the essential operational context. It explains the return format and adds the `untrusted_text` caveat, though it does not mention pagination behavior beyond the schema's `after` and `limit` parameters, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for all five parameters, so the baseline is 3. The description adds minimal extra semantics by echoing the non-snowflake nature of `answer_id` and showing the path structure, but it does not meaningfully deepen parameter understanding beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The purpose line 'List users who voted for a specific answer on a poll' clearly states a specific verb and resource, and it distinguishes the tool from siblings like polls_end (which ends polls) and other list tools. The scope is precise, referencing a specific answer, channel, and message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a critical usage hint by explicitly noting that `answer_id` is a poll-local integer rather than a snowflake, preventing a likely invocation error. It does not explicitly discuss alternatives or when-not-to-use, but no direct alternative exists among the siblings, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, non-destructive, idempotent operation. The description adds meaningful behavioral context: Discord renumbers other roles automatically and the tool returns the full role list after change. This goes beyond the annotation-provided safety profile without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headings (Purpose, When to use, Body, Returns) and contains no filler. Every sentence contributes to understanding the tool's action, usage context, request format, and return value, making it highly scannable and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage trigger, request body, and return shape, which is sufficient for tool selection and basic invocation. It does not detail permissions or rate limits, but given the moderate complexity and the presence of schema and annotations, these are not critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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's body note ('array of {id, position?}') largely mirrors the schema descriptions, which already explain that roles are auto-renumbered. The description adds minimal extra semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Bulk-reorder guild roles' via a specific PATCH endpoint. It uses a specific verb and resource, and the term 'bulk-reorder' distinguishes it from sibling tools like roles_modify, roles_create, and roles_delete. This is an unambiguous, well-differentiated purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section with an explicit example ('swap two adjacent roles') and clarifies it is for moving several roles in one transaction. However, it does not explicitly mention when not to use it or name alternative tools for single-role changes, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutating, idempotent, and non-destructive behavior. The description adds value by specifying that only metadata is modified, fields omitted remain unchanged, and the updated object is returned. This goes beyond the annotation hints 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded purpose, no fluff. The return type is briefly summarized, and the description earns its place with actionable guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations, output schema, and self-explanatory parameters, the description covers the core behavior, update semantics, and return value. It lacks explicit permission/error details, but that is not essential for this straightforward modification tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (43%), but parameter names are largely self-explanatory (name, volume, emoji_id, emoji_name). The description adds the key partial-update instruction, but does not explain nullable fields or other constraints beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Modify') and resource ('guild soundboard sound's metadata'), clearly distinguishing it from sibling tools like create/delete/get/send. It also clarifies partial update semantics with 'Pass only fields you want to change.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose statement and partial-update note imply when to use: when existing sound metadata needs changing. It does not explicitly name alternatives or exclusions, but the context is clear from the description and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, etc.), the description discloses the return format and the error behavior when the gateway prerequisite is not met. It adds useful context about the operation's side effects without contradicting the annotations. The description could further detail permission requirements or rate limits, but it provides meaningful additional behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using three labeled sections (Purpose, Pre-requisite, Returns) that are front-loaded and directly useful. Every sentence earns its place, with no redundant or filler content. It is easy to scan and immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with a complete output schema and annotated safety profile, the description is sufficient. It covers the key operational prerequisite, the return structure, and the core purpose. It could optionally mention how to obtain a valid sound_id or note that source_guild_id is optional, but the schema already indicates this, making the description contextually complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter clearly described. The description adds minimal parameter-specific semantics beyond the schema, only referencing channel_id in the prerequisite. Since the schema already carries the full burden, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Play a soundboard sound in a voice channel.' This clearly distinguishes it from sibling tools like soundboard_list_guild_sounds or soundboard_create_guild_sound, which manage sounds rather than send them. The purpose is immediately obvious 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a strong prerequisite: the bot MUST be voice-connected to channel_id, and warns that without --gateway enabled, Discord will return an error. This gives clear context for when to use the tool and a key failure condition, though it does not explicitly name alternative tools or enumerate when-not scenarios beyond the connectivity prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by specifying the return shape and noting that the 'description' field is omitted from list output, suggesting retrieval via stickers_get_guild_sticker for that detail. This adds behavioral context without contradicting the readOnly/destructive annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: Purpose, When to use, and Returns. It is concise, front-loaded with the core purpose, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 covers the essential aspects: purpose, usage, and a notable return behavior (omission of description). It could potentially mention pagination or sorting, but this is not strictly necessary and the given details are adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the only parameter (guild_id) with the description 'Guild to inspect'. The tool description does not add additional parameter-level semantics, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List custom stickers belonging to a guild.' This uses a specific verb (List) and resource (custom stickers in a guild), and it distinguishes from sibling tools like stickers_list_packs and stickers_get_guild_sticker by focusing on guild stickers. The 'When to use' section reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context ('Inventory guild stickers; pick one for a message') under 'When to use'. It does not explicitly mention when not to use the tool or alternative tools, but the context is sufficiently clear for an agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by disclosing the permission requirement, warning that the output contains untrusted_text, and advising inspection before sharing. This supplements the annotations (readOnlyHint=false, idempotentHint=false) without contradicting them, though it does not mention rate limits or duplicate creation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with three labeled sections (Purpose, Requires, Returns), each sentence earning its place. It is front-loaded, scannable, and free of redundancy, making it easy for an agent to quickly extract key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential context: purpose, permission, return shape, and a safety warning about untrusted text. Since an output schema exists, it does not need to detail every return field. It could mention non-idempotency or duplicate creation, but the idempotentHint=false annotation already signals this, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all four parameters (name, guild_id, description, audit_reason) already explained in the input schema. The description does not add significant parameter-level meaning; it only implies the guild context through 'caller bot's current guild layout', which aligns with guild_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase 'Snapshot the caller bot's current guild layout as a new Discord Guild Template', clearly identifying the action and resource. It distinguishes itself from sibling template tools like templates_get/list/modify by emphasizing 'new' and creating a shareable snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear context is provided via the required MANAGE_GUILD permission and the note to inspect before sharing the use_url, which implies a safe usage workflow. However, it does not explicitly name alternative tools or state when not to use this tool, relying on the 'new' keyword to differentiate from template modification tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful context beyond annotations: the returned webhook record lacks a token, and 'name' remains raw creator-controlled data while 'untrusted_name' is a fenced copy. This alerts the agent to security considerations. No contradiction with annotations; readonly=false, idempotent=true, destructive=false align with an update operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured with Purpose, When to use, and Returns sections. Every sentence adds value; no redundancy or fluff. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple modification tool with an output schema and 100% parameter coverage, the description covers purpose, a key usage scenario, and return behavior. It could be more complete by explicitly contrasting with webhooks_modify_with_token, but the provided information is sufficient for correct tool selection and invocation in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description adds a small amount of extra meaning, e.g., channel_id is bot-auth only. This is helpful but not crucial; most parameter meaning comes from the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a webhook, specifying the concrete actions (rename, re-avatar, move to a different channel). It distinguishes itself from siblings by noting the channel_id change is only available on the bot-auth path, which differentiates from webhooks_modify_with_token.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
A 'When to use' section is present, giving a specific scenario: changing the channel. However, it does not explicitly mention alternatives or when to use the token-based sibling. The guidance is clear for one case but lacks comprehensive when-to-use/not-use coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral details: name is null for DMs, position/parent_id are absent for threads and DMs, and topic is raw user-controlled data that is fenced in text responses. These edge cases go beyond the annotations and help the agent predict response variations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with bold section headers (Purpose, When to use, Returns). Every sentence adds useful information, and the return format is presented clearly without fluff. It is front-loaded and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and strong annotations, the description is complete. It explains not only what the tool returns but also the conditional presence of fields and the handling of raw topic data, covering potential edge cases an agent would need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has full description coverage for channel_id ('Target channel ID'), and the parameter is a simple ID. The description does not add extra meaning about the parameter itself, but none is needed given the schema coverage and simplicity. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Fetch full metadata for a single Discord channel.' It clearly distinguishes from siblings like channels_list (plural listing) and messages_get (messages), and the emphasis on 'single' narrows the operation scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly identifies the context: 'inspect topic, slowmode, nsfw of a known channel.' This gives clear context for when the tool is appropriate, but it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds that it returns a `{component}` JSON node and specifies 'type 12', clarifying the nature of the operation as a pure builder that produces a structured output. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two bolded lines covering purpose and return value. Every word provides value, with no fluff or repetition. The structure is front-loaded with the core purpose, making it scannable for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple builder tool with a single parameter and full output schema, the description is complete. It specifies the media gallery type, item count range, and return type. Combined with the rich schema and annotations, the agent has all necessary context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the schema fully describing the 'items' parameter including its properties (url, spoiler, description) and constraints (1-10 items). The description merely repeats '1-10 media items', adding no additional meaning beyond what the schema already provides. Therefore, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Build a Components V2 MediaGallery (type 12)' with a specific item limit. It uses a specific verb ('Build') and resource ('MediaGallery'), distinguishing it from sibling component tools like container or section builders. The return value is also defined, leaving no ambiguity about what the 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose statement inherently communicates when to use this tool: when you need to construct a MediaGallery component. While it doesn't explicitly name alternatives or exclusions, the context is clear enough from the tool name and sibling list. No explicit when-not-to-use guidance is provided, but the narrow scope makes misuse unlikely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the return shape and mentions the role-restriction list, giving useful behavioral 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with clear bold headings and a bullet list. Every sentence serves a purpose: purpose, when to use, and return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only fetch tool with two well-documented parameters and an output schema, the description is complete. It even includes the return structure, which exceeds the minimum requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover both parameters with 100% coverage ('Emoji to fetch' and 'Guild owning the emoji'). The tool description adds no additional parameter detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a single guild emoji by ID' with a specific verb and resource. It distinguishes from siblings like emojis_list_guild and app_emojis_get by specifying 'guild emoji' and 'by ID'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' scenarios: verify an emoji exists and inspect role-restriction list. It doesn't mention alternatives or exclusions, but the use cases are clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive, idempotent operation. The description adds context beyond annotations: the 'consumable SKU only' constraint and the effect on the purchase lifecycle. It does not detail error conditions, but this is adequate given the idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sections with bold headers, front-loading the purpose immediately. Every sentence adds value: purpose, constraint, effect, and return shape. No unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool, the description is complete: it states the purpose, the constraint, the return fields, and combined with the annotations covers safety and idempotency. The sibling list provides enough context for alternative operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the schema (coverage 100%), so the description does not need to add much. It does not enhance parameter semantics beyond what the schema provides, but remains at the baseline for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (mark as consumed), the resource (one-time entitlement), and the constraint (consumable SKU only). It explains the business effect (user's purchase recognized so they can buy again), which distinguishes it from sibling tools like entitlements_get or entitlements_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear when-to-use context: for consumable SKUs when a one-time entitlement needs to be marked as consumed. It includes an explicit exclusion ('consumable SKU only'), though it does not name alternatives such as entitlements_get for checking status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by specifying the return object shape and noting that creator_id is absent for events created before October 2021. Annotations already indicate it is not read-only and not idempotent, so the description complements rather than contradicts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured with bold section headers (Purpose, When to use, Entity types, Returns). Every sentence carries useful information without redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with nested objects, the description covers purpose, usage, entity-type constraints, and return format. Combined with high schema coverage and annotations, it provides sufficient context 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so the baseline is 3. The description repeats entity type requirements already present in the schema (e.g., channel_id required for STAGE/VOICE) and does not add new parameter-level meaning beyond what the schema documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Create a new scheduled event for a guild.' It also lists entity types, clearly distinguishing from sibling tools like events_list, events_get, events_modify, and events_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear 'When to use' section: 'Schedule a stage, voice, or external event in a guild.' It gives contextual constraints for entity types but does not explicitly mention when not to use or name alternatives, which is acceptable for a create operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe read-only operation. The description adds valuable context about the return shape `{events:[...], count}` and the distinction between raw structured data and fenced text responses, going 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three labeled sections (Purpose, When to use, Returns), no filler, and front-loaded content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 parameter and an output schema, the description adequately covers purpose, usage, and return format without needing to duplicate schema details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the single parameter guild_id as 'Guild to query', and the description's purpose reaffirms its role. Description adds no additional parameter semantics, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List scheduled events for a guild' with a specific verb and scope, distinguishing it from sibling tools like events_get (single event) and events_list_users (event users).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'enumerate upcoming voice/stage/external events'. It does not mention when not to use or alternatives like events_get for a single event, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description reveals that status transitions are server-validated, the return shape is a 'projected event shape,' and there is a notable quirk about creator_id absence for pre-October 2021 events. It also notes the raw/untrusted_text handling, adding useful behavioral 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded sections (Purpose, When to use, Status, Returns) and front-loaded with the core purpose. It is mostly concise, though the 'Event text remains raw; untrusted_text provides a separately fenced copy' detail feels slightly tangential and may distract without adding clear value for modification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters, nested objects) and the presence of an output schema, the description covers purpose, usage scenarios, status values, and return quirks. It is reasonably complete for typical use, but it omits prerequisites such as required permissions or field interdependencies (e.g., entity_type/channel_id alignment), which would strengthen completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps high-level actions to parameter groups (reschedule implies scheduled_start_time/end_time, rename implies name, change location implies channel_id/entity_metadata.location, status transitions imply status), adding some meaning beyond the schema. However, with schema coverage at only 29%, many parameters (image, description, entity_type, privacy_level, recurrence_rule, audit_reason) remain unexplained, so compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update fields of an existing scheduled event,' which clearly identifies the verb and resource. It further distinguishes the tool from siblings by specifying actions like 'reschedule, rename, change channel/location, or transition status,' making it clear this is for modifying, not creating or deleting events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly lists scenarios such as rescheduling, renaming, changing location, and status transitions. However, it does not mention when not to use this tool (e.g., creating events) or name alternatives like events_create, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds a meaningful behavioral nuance: structured name/description remain raw server-owner data while the human-readable response fences them—information not present in annotations. This goes beyond the baseline but doesn't cover auth or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with three bold sections, using only two sentences that each earn their place. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given rich annotations, an output schema, and a single required parameter, the description fully covers purpose, usage, and an important output nuance. It is complete for a simple read-only fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for guild_id ('Guild to fetch'). The description adds no additional parameter-level semantics beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Fetch guild metadata') and clearly distinguishes this from sibling guild_get_* tools (e.g., widget, welcome screen, prune count) by focusing on the core metadata object. The listed return fields further reinforce its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section provides clear use cases ('server overview; compute boost-tier-dependent caps'), which gives solid context. However, it does not explicitly name alternative tools or state when not to use, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds valuable context: the return shape {code, uses} and the note that code is null if no vanity URL is configured. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured, using markdown headings for Purpose, When to use, and Returns. Every sentence adds value with no redundancy or fluff, and it is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, full schema coverage, and the presence of an output schema, the description covers all necessary aspects: purpose, usage scenario, and return behavior including the null case. It is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the guild_id parameter described as 'Guild to query'. The description does not add any additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the guild vanity URL invite' with a specific resource, and qualifies it as a 'Community/Partner perk', which distinguishes it from general invite tools like invites_get or invites_list_channel. The verb and object 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is an explicit 'When to use' section stating 'Display the configured discord.gg/<code> shortcut and how many times it has been used.' This provides clear context for use, though it does not explicitly mention when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful context by noting that descriptions remain raw server-owner data and that untrusted_text provides a separately fenced copy. This warns about untrusted payloads, which is valuable 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.
Conciseness5/5Is 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 useful information without unnecessary fluff, making it both concise and highly readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter, an output schema, and comprehensive annotations, the description fully covers purpose, usage context, and return semantics, including a security-relevant note on untrusted text. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the sole parameter guild_id fully described by the schema. The description does not add parameter-level details beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and a clear resource ('configured Community welcome screen'). This precisely identifies the tool's function and naturally distinguishes it from sibling tools like guild_modify_welcome_screen or onboarding_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section clearly states the primary use case: 'Inspect onboarding before tweaking it.' This provides strong contextual guidance, though it does not explicitly name alternatives or exclusions. It implies the complementary modify tool exists, earning a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly=false, destructive=false, idempotent=true; description avoids contradiction. Adds behavioral context: 'Pass only fields you want to change' (partial update) and return shape details, including caveat that name and description remain raw with untrusted_text as separately fenced copy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and uses bold headers and bullet lists to separate purpose, usage, and returns. No filler; each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the 22-parameter complexity and low schema coverage, the description covers core scenarios, returns shape, and important data-safety caveats. However, it doesn't enumerate all parameters or their semantics, so completeness is solid but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 23%, the description must compensate but only offers thematic examples (rename, verification level, channels, premium bar) without mapping to parameter names. Most of the 22 parameters (banner, splash, features, owner_id, afk_timeout, system_channel_flags, etc.) are left unexplained, so agents cannot infer valid values or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Update' and noun 'guild-level settings', and enumerates example fields (rename, verification level, channels, premium progress bar). It distinguishes from sibling tools by explicitly naming channels_modify, roles_modify, and guild_modify_welcome_screen.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Has dedicated 'When to use' and 'When NOT to use' sections. The NOT-to-use section identifies exact alternative sibling tools (channels_modify, roles_modify, guild_modify_welcome_screen), giving clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description is not burdened with the safety profile. It adds valuable behavioral context beyond annotations: the classification is performed 'using the client's LLM' (implying cost/latency), it covers 'recent messages,' and the return value includes 'sampling_used,' which hints at possible sampling behavior rather than full classification.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear 'Purpose,' 'When to use,' and 'Returns' sections. Each section earns its place, and the most important information is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema provided, the description does not need to explain return structure in detail, but it still summarizes the return object and adds sampling_used. Combined with annotations and clear usage guidance, the description is complete 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters (channel_id, categories, limit) are already well-documented in the schema. The description does not add parameter-specific semantics beyond the general suggestion of 'provided categories' and 'recent messages,' which is acceptable given the high schema coverage; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Classify') and resource ('recent messages') plus category labels, clearly distinguishing it from sibling tools like intelligence_summarize_channel and intelligence_extract_entities. It also adds the unique detail that each classification carries a 0-1 confidence score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly lists concrete use cases: triage spam vs. question vs. discussion, bucket support requests, and segment conversations. It does not explicitly name alternatives or state when not to use, but the provided context is clear enough for an agent to select the tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds value by noting the use of the client's LLM and by including 'sampling_used' in the return shape, which hints that sampling may occur for large inputs. This provides behavioral context beyond the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, well-structured with bold labels (Purpose, When to use, Returns), and front-loaded with the core purpose. Every sentence provides useful information without waste, making it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, use cases, and return shape, and is supported by strong annotations and a complete schema with an output schema. It sufficiently explains the tool's role within the intelligence suite, so the agent can select and invoke it correctly. Minor omissions like explicit limitations are not necessary given the schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all three parameters. The description lists entity types in the purpose, which overlaps with the schema's entity_types enum, but it does not add additional param-level semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Pull structured entities' and names the resource ('recent Discord messages') with concrete entity types (decisions, action items, dates, mentions, URLs, code). This clearly distinguishes it from sibling intelligence tools like summarize or classify, which serve different outcomes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists three concrete use cases (post-meeting recap, audit log of decisions, weekly digest builder), giving clear context for when the tool is appropriate. It does not explicitly mention alternatives or when not to use it, so it misses the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: optionality of fields (premium_since and pending absent when Discord omits them), the null possibility for joined_at, and the note about nick being raw data with human-readable text fencing. This is strong supplemental 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded sections for Purpose, When to use, and Returns. It is concise, front-loaded, and every sentence carries useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only fetch with rich annotations, output schema, and clear usage guidance, the description is complete enough. It covers what the tool does, when to use it, and important return-value nuances, leaving no significant gaps for tool selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, with descriptions for user_id and guild_id. The description's mention of 'by user ID' reinforces the key parameter, but it does not add meaningful 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.
Purpose5/5Does 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 guild member by user ID.' This clearly distinguishes the tool from siblings like members_list and members_search, and the mention of inspecting roles, nick, and joined_at further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a dedicated 'When to use' section: 'inspect roles, nick, joined-at of a known user.' This gives clear context, though it does not explicitly name alternatives or state when not to use it, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavior beyond this by specifying the return format `{user_id, username, reason}` and the 404 response when a user is not banned, which is useful for error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with three labeled sections (Purpose, When to use, Returns) in under 60 words. It is front-loaded with the purpose and contains no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-ban lookup, the description covers purpose, usage context, return shape, and not-found behavior. Combined with full schema annotations and the presence of an output schema, no critical information is missing for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described as 'User to look up' and 'Guild to inspect.' The description does not add further parameter syntax, constraints, or relationships beyond what the schema already provides, so it stays at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Look up a single ban entry by user ID' with a specific verb and resource, clearly distinguishing it from sibling tools like members_list_bans, members_ban, and members_unban. The 'When to use' section reinforces the specific purpose of confirming ban status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly says 'Confirm whether a user is currently banned and why,' providing a clear use context. However, it does not name alternatives or exclusions, such as noting that members_list_bans should be used for retrieving all bans, so it falls short of full differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 description carries a lighter burden. It adds valuable context about pagination cursor behavior and the exact return shape, which goes 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely compact with four labeled sections: Purpose, When to use, Pagination, and Returns. Every sentence earns its place and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers purpose, usage context, pagination semantics, and return structure. Combined with strong annotations and full schema coverage, the description is complete for a paginated read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions. The description's 'before/after are user-id cursors' and 'limit 1-1000' largely restate schema constraints, adding marginal semantic value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List bans in a guild (paginated)', a specific verb+resource statement. It clearly distinguishes this from sibling tools like members_get_ban (single ban) and members_ban (create ban).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'Audit moderation history; export ban list.' It doesn't name alternatives or exclusions, but the use cases provide clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, restrictiveHint=false, and readOnlyHint=false. The description adds the no-op behavior and return shape, but these are either implied by the idempotency hint or already covered by the output schema. No additional behavioral context like permissions or failure modes 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, bullet points, and no redundant sentences. It efficiently covers purpose, usage, exclusions, return value, and key behavior in a compact format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, the annotations, and the full schema coverage, the description adequately covers purpose, selection guidance, and return behavior. It also points to the correct alternative for bulk role replacement, making the context complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all 4 parameters with 100% coverage, so the baseline is 3. The description does not add new parameter-level meaning beyond what the schema already gives; it only clarifies that the operation removes a single role, which is evident from the name and schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Remove a single role from a guild member') and clearly distinguishes from the sibling tool members_modify, which is for replacing the entire role set. It also implicitly contrasts with members_add_role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' and 'When NOT to use' sections are provided, including a concrete example (revoke @verified) and a named alternative tool (members_modify with roles). This gives the agent clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a rate limit ('5/sec/guild') and the exact format of matches, providing useful behavioral context beyond what 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with bold headings (Purpose, When to use, Example, Returns, Rate limit). Every sentence contributes valuable information, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with rich annotations, a fully documented schema, and an output schema, the description covers purpose, usage context, example invocation, output shape, and rate limiting. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already well-documented. The description reinforces the query semantics and gives an example, but does not add new meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Fuzzy-search guild members by username/nick prefix' with a clear verb, resource, and scope. This distinguishes it from sibling tools like members_list and members_get, which are not fuzzy or search-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
A 'When to use' section provides concrete contexts: 'convert "find @alice" or "users named bob" into snowflake IDs.' It gives an example call but does not explicitly mention when not to use or name alternative tools, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which already indicate non-read-only, non-destructive, and idempotent), the description adds concrete behavioral details: the return shape `{unbanned, user_id, guild_id}` and the idempotency edge case that unbanning a non-banned user returns 404 from Discord. This enriches the agent's understanding 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a short purpose statement, a one-item usage list, and a one-sentence returns/idempotency note. Every sentence serves a clear function, and the structure is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple unban operation with a well-defined output schema, full parameter coverage, and relevant annotations, the description covers all necessary context: what it does, when to use it, what it returns, and a critical edge case. There is no significant missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with clear descriptions for all three parameters (guild_id, user_id, audit_reason). The description does not add additional parameter semantics, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Remove a ban') and the specific resource (a user's ban), with the consequence 'allowing them to rejoin'. It is immediately distinguishable from sibling tools like members_ban, members_list_bans, and members_get_ban.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section gives clear context: 'Restore a previously-banned user.' It does not explicitly mention alternatives or when not to use, but the guidance is unambiguous and adequate for choosing this tool over similar ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral detail that a channel with 50 pins returns a 400 error, which goes beyond the annotations. It also discloses the return format. This supplements the idempotentHint and readOnlyHint annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with bold section headers for Purpose, When to use, When NOT to use, and Returns. It front-loads the purpose and each section earns its place without redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple pin operation with full schema coverage, an output schema, and annotations, the description covers purpose, use cases, a key edge case, and return values. It is sufficiently complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes all three parameters (channel_id, message_id, audit_reason) with 100% coverage, so the description adds no additional parameter semantics. The mention of channel_id and message_id in the return format is not parameter documentation. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Pin a message in a channel' with a specific verb and resource, clearly distinguishing it from sibling tools like messages_unpin and messages_list_pins. It also ties the action to a concrete use case (highlighting announcements/FAQ), which adds contextual clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit 'When to use' section with a concrete scenario and a 'When NOT to use' section that warns about the 50-pin limit returning a 400 error. It does not name alternative tools explicitly, but the conditions are clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context about the return format (raw vs. fenced content) and a security warning about untrusted Discord data, which goes 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Purpose, When to use, Example, Returns, Security). Every sentence provides distinct value, and it is compact without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 rich annotations, the description covers all necessary context: purpose, use cases, example invocation, return shape, and a security note. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a description (e.g., 'Get messages after this ID (newer)'). The description's example ({channel_id, limit:50}) adds a concrete usage illustration but does not explain any 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read recent messages from a Discord channel' – a specific verb, resource, and scope. It also mentions two concrete use cases (catching up and locating a specific message), which differentiates it from siblings like messages_get and messages_search_recent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section provides two clear scenarios: catching up on a channel and locating a specific message by content/author. However, it does not explicitly state when not to use this tool or name alternative tools, so it stops short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds that it adds the bot's own reaction, returns a specific object, explains emoji format (unicode or name:id), and notes URL-encoding handled by @discordjs/rest. This goes beyond the annotations, though it doesn't discuss rate limits or broader side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded sections: Purpose, When to use, When NOT to use, Example, Returns. Each section is concise and informative, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple with three required parameters, full schema coverage, and an output schema, the description is complete. It covers return values, emoji input formats, a concrete example, and a limitation. This is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters, including patterns and emoji format. The description adds an example with concrete values and restates the emoji format, but does not significantly add meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states "Add the bot's own reaction to a message," providing a specific verb, resource, and scope. It distinguishes from sibling reaction tools like reactions_delete_own and reactions_list by explicitly limiting the action to the bot's own reaction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a "When to use" section with concrete use cases (acknowledge, vote/poll, quick affirmation) and a "When NOT to use" section stating that reacting on behalf of another user is not possible via REST. However, it does not explicitly name alternative sibling tools for other reaction operations, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by detailing the return shape and warning about raw, untrusted names, which is useful 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, split into two short labeled sections. It front-loads the purpose and provides return information in a compact, structured format with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter tool, strong annotations, and existing output schema, the description is complete. It even adds helpful details about untrusted names and return structure, so no important context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for guild_id. The description does not need to add further parameter detail; the schema fully explains the only parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List a guild's custom soundboard sounds' with a specific verb and resource. It clearly distinguishes from sibling tools like soundboard_list_default_sounds by specifying 'custom' and 'guild's'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool lists a guild's custom sounds. It does not explicitly name alternatives or exclusions, but the purpose is sufficiently clear to differentiate from default soundboard lists and individual sound retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false; the description adds valuable context about the return data, specifically that 'topic remains raw user-authored data' and 'untrusted_text provides a separately fenced copy'. This goes beyond the structured hints to warn about data trust levels.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with 'Purpose' and 'Returns' sections. Every sentence earns its place, providing essential information without any fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and an output schema, the description gives purpose, return structure, and a caveat about data trust. It is minimally complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter channel_id is documented in the schema with description 'Stage channel', achieving 100% schema coverage. The tool description adds no additional parameter semantics, so the baseline score of 3 applies since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch the live Stage instance for a channel') with a specific verb and resource. It distinguishes this from sibling tools like stage_instances_create, modify, and delete by focusing on the read operation for a specific resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose statement implicitly defines when to use this tool (when retrieving a Stage instance) and there are no competing get tools for this resource. It lacks explicit alternative references, but the unique verb-resource mapping makes the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing the return fields and the special behavior that 'description remains raw moderator-authored data; the human-readable text response fences it.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses three compact labeled sections: Purpose, When to use, Returns. Every sentence earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two parameters and an output schema present, the description covers purpose, usage, and return behavior. The annotations and schema cover the remaining context, making the description fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both guild_id and sticker_id explained. The description does not add much beyond implying a known sticker ID, but the baseline of 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Fetch a single guild sticker including description and tags,' which is a specific verb and resource. It clearly distinguishes from sibling list tools like stickers_list_guild by emphasizing 'single' and the inclusion of tags/description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly says 'Inspect description / tags / availability of a known sticker,' giving a clear usage context. It does not name alternative tools or exclusions, but the context is sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the return shape and the 'globally' scope, but does not disclose additional behavioral traits such as auth needs or rate limits. With annotations present, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured with Purpose, When to use, and Returns sections. Every sentence contributes value, 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with comprehensive annotations and an output schema, the description is fully complete. It clarifies the scope ('globally') and usage context, and no additional details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. The description correctly implies no input is required. With 100% schema coverage and no parameters, a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List'), a resource ('Nitro sticker packs'), and a scope ('globally'), which distinguishes it from sibling sticker tools like stickers_list_guild (guild-specific) and stickers_get (single sticker).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear 'When to use' section: 'Discover available default sticker packs.' This gives context but does not explicitly exclude alternatives or mention when NOT to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: template data is untrusted, `use_url` is a human-opened link rather than a bot action, and the tool never creates a guild. This enriches the readOnlyHint and idempotentHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with Purpose, Safety, and Returns sections. Every sentence serves a purpose, providing essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one well-documented parameter, an output schema, and strong safety/behavioral context, the description is fully sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single parameter as a template code or canonical URL (100% coverage). The description merely restates this without adding new parameter-level details, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Inspect a public Discord Guild Template by code or `discord.new` URL without changing a guild,' providing a specific verb and resource. However, it fails to differentiate from the sibling tool `templates_inspect`, using the same verb 'inspect' and potentially overlapping in purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: inspecting a template safely before using it, with the safety note about untrusted data. It clarifies that the tool never creates a guild, but it doesn't explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable context by specifying the returned fields and the 404-shaped error when the user is not a member, though it does not mention the with_member parameter's effect on the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Purpose, When to use, Returns) and uses minimal words. Every sentence adds value, including the error behavior, without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with complete schema annotations, an output schema, and a description covering purpose, usage, return fields, and error cases, the description is fully complete. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters ('User to query', 'Thread to look up', 'Include the underlying guild member object'). The description reinforces the overall purpose but does not add meaning beyond the schema for individual parameters, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Look up') with a clear resource ('one user's thread-membership record') and scope ('join timestamp, flags'). This distinguishes it from siblings like threads_join, threads_leave, and threads_list_members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Verify a user is in a thread before performing thread-only actions.' It provides clear context but does not name alternatives or exclusions, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the annotations: it specifies the endpoint is user-scoped and does not accept `audit_reason`, and it discloses the return shape. Since annotations already indicate it's a write operation (readOnlyHint=false) and not destructive (destructiveHint=false), the extra details about the endpoint limitation and return format provide meaningful transparency. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with bold labels (Purpose, When to use, Note, Returns). Every sentence adds value: the purpose is upfront, use cases are specific, the note clarifies a limitation, and the return shape is mentioned. No filler or redundant information, achieving an efficient size for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has only 3 optional parameters, no required parameters, and an output schema, the description is sufficiently complete. It covers the purpose, appropriate usage, a key constraint (no audit_reason), and the expected return shape. The presence of an output schema means the returned fields don't need exhaustive explanation, but the description still previews the projected shape, making it self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all 3 parameters (avatar, banner, username) with descriptions, achieving 100% schema description coverage. The description's 'rename the bot, change avatar/banner' maps directly to these parameters but adds little beyond what the schema provides. Therefore, a baseline score of 3 is appropriate, as the description does not significantly enrich parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update the authenticated bot/user profile' with the specific endpoint `PATCH /users/@me`. It uses a specific verb ('Update') and resource ('bot/user profile'), and it differentiates from siblings like `users_get_current` and `members_modify_current` by focusing on the current user's profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear 'When to use' section listing concrete use cases: 'Rename the bot, change avatar/banner.' It also notes a key limitation ('does NOT accept audit_reason') which helps set expectations. However, it doesn't explicitly mention alternatives when the tool is not appropriate, such as using `members_modify_current` for guild-specific profile changes, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by listing the returned voice state fields (channel, mute/deaf flags, request_to_speak_timestamp), which goes beyond the schema and annotations. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two labeled sections ('Purpose' and 'Returns') that front-load the core intent. Every sentence adds value, and there is no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, clear endpoint, output schema), the description provides complete coverage: purpose, return shape, and endpoint are all included. Annotations and output schema handle safety and return details, so no additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents guild_id with a description ('Guild to query') and pattern, achieving 100% coverage. The description's endpoint mention (/guilds/{guild.id}/voice-states/@me) reinforces that guild_id maps to the guild path parameter, but adds no new semantic meaning 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Fetch the bot's own voice state in a guild') and identifies the resource via the endpoint path. It distinguishes from the likely sibling voice_get_user_state by specifying 'bot's own', making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'bot's own' conveys when to use this tool (when needing the bot's state rather than a specific user's), which implicitly differentiates from the sibling voice_get_user_state. However, it does not explicitly state alternatives or exclusion conditions, though the context is clear enough for an agent to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds that only provided fields are updated, that Discord ignores non-applicable fields, and the return shape. This extends beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with Markdown headers and bullets. Every sentence adds value: purpose, usage, exclusions, field behavior, and return value. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 21 parameters, an output schema, and rich annotations, the description covers the core behavior, usage boundaries, and return value. It lacks permission requirements and error scenarios, but these are not essential for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (24%), and the description does not individually explain each parameter. However, it does add the crucial general semantics of partial updates and field applicability, which partially compensates for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing channel's settings' with a specific verb and resource. It further distinguishes from siblings by explicitly listing 'When NOT to use' with channels_modify_permissions and channels_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a 'When to use' list of concrete scenarios and a 'When NOT to use' with alternative tool names. Also explains field applicability mirrors channels_create_guild_channel, helping the agent know which params apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses upsert semantics ('posting the same name+type updates the existing command') which goes beyond the idempotentHint annotation. It also reveals propagation delay and type-specific requirements for description, adding behavioral context not visible in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is clearly structured with bold labels (Purpose, Body, Idempotent, Returns) and each sentence provides distinct information. It is appropriately sized for the tool complexity and front-loads the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core usage, idempotency, propagation, and return shape, which is substantial given the output schema and annotations exist. However, it does not elaborate on the complex options structure or many optional parameters, leaving some gaps for a 14-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 7% schema description coverage, the description adds meaning for key parameters: `name` is required, `description` is conditionally required based on `type`, and `type` values are mapped to CHAT_INPUT/USER/MESSAGE. However, 11 parameters remain undocumented, so the description only partially compensates for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or upsert a global application command' with a specific verb and resource. It distinguishes from guild commands by specifying 'global' and mentions the ~1 hour propagation time, which separates it from sibling commands like commands_create_guild.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about global command propagation delay but does not explicitly name alternatives or state when not to use this tool. The 'Idempotent' and propagation notes imply usage considerations, but there is no exclusion such as 'use commands_create_guild for instant propagation.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint=true annotation, the description warns 'DESTRUCTIVE - kicked members must rejoin manually', explains timeout avoidance with compute_prune_count=false, and details the ConfirmRequired/__confirm/MCP_DRY_RUN security gate. This adds substantial behavioral context that annotations 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded sections and a front-loaded purpose, but the include_roles paragraph duplicates the schema description word-for-word, making it slightly less concise than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 6 parameters, the description covers purpose, usage context, destructive consequences, role-pruning semantics, return shape, timeout behavior, and security gating. This is comprehensive 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.
Parameters3/5Does 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 largely restates the schema (especially include_roles, which is verbatim), but adds minor clarifications like compute_prune_count=false 'returns null' and that __confirm is gated by ConfirmRequired. This is not enough to meaningfully exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Kick inactive members', a specific verb+resource statement that clearly distinguishes this tool from siblings like members_kick (kicks a specific member) and guild_get_prune_count (previews the prune count).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
An explicit 'When to use' section states 'Reduce inactive bloat in large communities', giving clear context. However, it does not mention alternatives such as guild_get_prune_count for previewing the prune before committing, so it lacks full when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes the tool returns `{ok, guild_id}` and that Discord returns 204 (no body). With annotations declaring readOnlyHint=false and idempotentHint=true, this adds behavioral detail about the response. It does not mention permissions or prerequisites, but the annotation coverage reduces the need.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with bolded Purpose, When to use, and Returns sections. It fits in a few lines with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, has an output schema, and annotations for safety/idempotency. The description covers the primary use cases and return format, making it sufficient for an AI agent to select and call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the key parameters by example: `request_to_speak_timestamp = now` for raising hand and `suppress = true` for stepping down, adding meaning beyond the schema's field descriptions. Since the schema covers 75% of parameters, the description adds useful semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Update' and identifies the resource as 'the bot's own voice state in a stage channel', with examples of raising hand and toggling suppress. It clearly distinguishes from sibling 'guild_modify_user_voice_state' by scoping to the bot itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section specifying the bot wants to raise its hand or step down. It does not explicitly name alternative tools for other users, but the 'bot's own' wording implies the boundary. This provides clear context but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and idempotentHint=true, so the description doesn't need to restate those. It adds the return format '{enabled, channel_id}' and clarifies the exact mutation (toggle/change channel). However, it doesn't mention the nullable behavior of channel_id for removal, but this is partially covered by 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with bolded sections. Every sentence adds meaningful information: purpose, when to use, and return value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, output schema, annotations), the description is reasonably complete. It covers purpose, usage, and returns. Missing minor edge cases (e.g., null channel_id), but overall sufficient for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, and the description compensates by explaining the meaning of 'enabled' (toggle) and 'channel_id' (set invite channel). The other parameters (guild_id, audit_reason) have adequate descriptions in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and the resource ('widget settings'), and specifies the actions ('toggle enabled, set invite channel'). This distinguishes it from sibling tools like guild_get_widget_settings, which is a read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete scenarios for use ('Toggle the public widget on/off, change which channel an embed-invite points at'). It doesn't explicitly contrast with alternatives, but the context is clear enough that an agent would know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only=false, idempotent=true, destructive=false. The description adds valuable behavioral details beyond those flags: 'Auth: token-secured (NO bot token)' clarifies credential requirements, 'null clears' discloses the effect of null values, and 'Body mirrors a webhook execute body' formats expectations. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four labeled, single-purpose lines (Purpose, Auth, Body, Returns) with zero filler. Every sentence adds distinct value, and the most important information is front-loaded. Excellent structure for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, nested objects, and an output schema, the description covers the essential invocation knowledge: what, when, auth, body shape, null semantics, and return value. It could more explicitly point to interactions_edit_followup for non-original responses, but the name itself resolves that ambiguity. Overall complete enough for reliable tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 30%, so the description carries significant weight. It lists all writable body fields and adds crucial semantics: 'reusable' fields mirror a webhook execute body and 'null clears' each one. This compensates for the sparse per-parameter descriptions in the schema. Required params application_id and interaction_token are already well-described in the schema, so the gap is largely closed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: 'Edit the original interaction response'. The example 'fill in a deferred reply' adds concrete context. The word 'original' distinguishes this from sibling follow-up tools like interactions_edit_followup, making the purpose 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'e.g. fill in a deferred reply' gives a clear, concrete use case. It does not explicitly mention alternatives or exclusions (e.g., 'use interactions_edit_followup for follow-ups'), but the 'original' qualifier plus the example provide enough contextual guidance. This meets the 'clear context, no exclusions' bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds the 'unique' nuance and stream-target capability, but these are also present in the schema. It does not disclose prerequisites like permissions, rate limits, or the fact that without unique=true the API might reuse an existing invite (implied but not explicitly stated).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with bold section headers (Purpose, When to use, When NOT to use, Example, Returns) and is extremely concise. Every sentence provides actionable information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and an output schema, the description covers purpose, usage boundaries, an example, and return fields. It doesn't exhaustively explain all parameter combinations, but the 100% schema coverage and output schema fill those gaps. The main use cases are well represented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds a concrete example with typical values and highlights the stream-target combination (target_type=1, target_user_id), going slightly beyond the schema's individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new invite for a channel' with a specific verb and resource. It further distinguishes itself from siblings by explicitly mentioning stream-target invites and by listing when NOT to use (reuse existing invite → invite_list_channel).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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. It names an alternative tool (invites_list_channel) for reusing existing invites, giving clear decision-making guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation; the description adds concrete constraints: 'multipart', 'File MUST be a base64 data URI', and a return 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Each section (Purpose, When, When NOT, Example, Returns) is tight and information-dense, using bold headers for scannability with no redundant prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool, it covers purpose, usage, exclusions, a worked example, and return shape. It lacks permission/error details, but output schema exists and complexity is modest, making this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 7 parameters with descriptions, including file_format enum mapping and file_data base64 requirement; the description's example provides a concrete sample but doesn't add new semantic insight beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Upload a new custom sticker to a guild (multipart)' which clearly states the action (upload) and object (new custom sticker), and explicitly distinguishes from modifying via sibling tool references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 name the alternative `stickers_modify_guild_sticker` and note format mismatch rejection, giving clear guidance on 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds valuable behavioral context beyond annotations by warning about rate limits for mass-adds and specifying the return structure {added, thread_id, user_id}. It does not cover permission requirements or error cases, but the provided context is sufficient for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured with bold section headings (Purpose, When to use, When NOT to use, Returns). Every sentence serves a clear purpose, and the most essential information is front-loaded. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 params), the presence of annotations, and an output schema (noted but not detailed), the description covers the key aspects: purpose, usage scenarios, exclusions, and return format. It omits some details like required permissions or edge cases, but the overall context is sufficient for a straightforward operation. The description is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for both parameters ('User to add', 'Thread to add the user to'). The tool description does not add any additional semantic detail about the parameters, such as how to obtain the IDs or constraints. Since the schema is complete, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a guild user to a thread (private or public).' The verb 'add' is specific and distinguishes this from self-join tools like threads_join or removal tools like threads_remove_member. It also notes the thread type scope, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section gives an explicit scenario ('loop a moderator or expert into an existing discussion'), and the 'When NOT to use' section warns against mass-onboarding, recommending an alternative action ('mention them in the parent channel instead') with a reasoning (rate limits). This provides clear decision guidance relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it explicitly marks the operation as 'DESTRUCTIVE - IRREVERSIBLE', explains the confirmation mechanism (__confirm:true) and the MCP_DRY_RUN=false requirement, and describes the return value. This complements the annotations (destructiveHint=true) by explaining how the destructive nature is guarded, which is valuable beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized with bold headers for Purpose, When to use, and Returns. Every sentence is purposeful: it states the action, its irreversibility, a use case, the return value, and a critical execution requirement. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with 3 params, an output schema, and annotations, the description covers the essential usage guidance, the safety requirement (dry-run/confirm), and return value. It fully equips an agent to decide when and how to invoke the tool, including the required environment condition. The only minor omission is lack of error handling details, but these are typically not required for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and each parameter has a meaningful description. The description adds extra semantic value by explaining the __confirm parameter's role and the MCP_DRY_RUN condition, which is not present in the schema. This goes beyond the baseline of 3, though the schema already covers the basics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a webhook by id.' with the verb 'delete' and resource 'webhook by id'. It is specific and distinguishable from sibling tools by the 'by id' phrasing, but it does not explicitly differentiate from webhooks_delete_with_token, which also deletes webhooks. Overall, purpose is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear 'When to use' with a concrete use case: 'Decommission a stale or compromised webhook.' This gives a clear context for when the tool is appropriate. However, it does not mention exclusions or alternatives (e.g., webhooks_delete_with_token), so it misses the 'when-not-to-use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While destructiveHint already signals danger, the description adds crucial behavioral detail: the deletion is irreversible, and actual deletion only occurs when both `__confirm:true` and `MCP_DRY_RUN=false` are set. It also states the return shape. These additions go beyond the structured annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, well-structured with bold headers, and every sentence carries essential information. No filler or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, when to use/not use, safety conditions, and return format. Combined with rich annotations, a complete input schema, and an output schema, the tool is fully contextualized for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (including `__confirm`) already documented. The tool description largely reiterates the `__confirm` semantics rather than adding new parameter-level meaning. The 'Returns' line concerns output, not parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an application emoji' with a specific verb and resource, and distinguishes it from the sibling `emojis_delete` by explicitly noting 'Guild emoji → use `emojis_delete`'. This leaves no ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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, naming the alternative tool (`emojis_delete`) for guild emoji. It also gives operational context (requires `__confirm:true` and `MCP_DRY_RUN=false`) for invoking the destructive action correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 context beyond this by clarifying the app-level scope and stating the return shape ({emojis:[...], count}). No contradiction exists, and the added detail helps set expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured with bold headers for Purpose, When to use, When NOT to use, and Returns. Every sentence earns its place, and it remains concise with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 parameter, explicit annotations, and an output schema, the description covers purpose, usage, scope distinction, and return format. It is fully sufficient for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage and a clear parameter description ('Application owning the emojis'), the description doesn't need to add more. It does specify the return format in the description, but param semantics are already adequately handled by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('custom emojis registered against the application'), and explicitly notes 'per-app, not per-guild', which distinguishes it from the sibling tool emojis_list_guild. This makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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, with the alternative tool emojis_list_guild named for guild-scoped emojis. This gives the agent clear, actionable selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool safe (readOnlyHint, idempotentHint, destructiveHint false), lowering the bar. The description adds valuable behavior details about the return value: it's a 'projected application shape', `name` and `description` remain raw author data, and `untrusted_text` is a separately fenced copy. This goes beyond annotations and helps the agent interpret results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured with bolded headers ('Purpose', 'When to use', 'Returns') and is only three sentences long. Every sentence provides necessary information with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, rich annotations, presence of an output schema), the description is complete. It covers what the tool does, when to use it, and what to expect in the return value, without needing to explain structured fields already present in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline is 4. The description mentions the endpoint `/applications/@me`, confirming there are no user-supplied arguments. No additional parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('bot/app application object') with the exact endpoint (`/applications/@me`), making the tool's function crystal clear. It also distinguishes itself from sibling tools like `application_modify_current` and `application_get_role_connection_metadata` by focusing on the current application object.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 use cases (confirm app identity, read flags, install URLs, tags, interaction endpoint). It lacks explicit exclusions or named alternatives, but the context is clear enough for an agent to decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds a behavioral caveat about 'reason' values being raw moderator-controlled data and fenced in human-readable text, which is valuable 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections (Purpose, When to use, Example, Returns) with no fluff. Each section earns its place and is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, when to use it, an example, return shape, and a data-safety caveat. With an output schema present and read-only annotations, nothing significant is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters. The description adds a concrete example mapping action_type 20 to MEMBER_KICK and shows usage of guild_id and limit, which enriches the bare schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Fetch audit log entries for a guild,' using a specific verb and resource. It clearly distinguishes this from sibling tools by focusing on audit logs and mentions the guild context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly frames this for investigating moderation actions like 'who kicked X?' and post-incident forensics. It provides clear context but does not mention alternatives or exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, non-idempotent, non-destructive behavior. The description adds useful behavioral constraints beyond annotations: the nested message requirement, the content/embed/component condition, and the 'Plain text channels - Discord rejects' caveat. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded section labels, concise bullet points, and no filler. Every sentence contributes actionable information, keeping the length appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and a nested message object, the description covers purpose, when/when-not, body shape requirements, and return shape. It provides sufficient context for an agent to select and invoke the tool correctly, complementing the rich schema and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (86%), and the schema already documents the key parameters including message's requirement for content/embeds/components. The description reinforces the nested body shape but does not add significant meaning beyond what the schema provides. Some parameters like rate_limit_per_user lack detail, but the description does not compensate for that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-object statement: 'Create a new forum (or media) thread with an initial message in one request.' This clearly identifies the tool's unique scope and differentiates it from the sibling messages_create_thread by explicitly calling out the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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. It names the alternative tool (messages_create_thread) for anchored threads and states that plain text channels are rejected, giving an agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the description adds extra value by disclosing the MANAGE_THREADS permission requirement and the output formatting nuance (raw Discord data vs. fenced human-readable text). It doesn't repeat annotation info and adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold labels, front-loads the purpose, and keeps each section tight. No wasted words; every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the presence of robust annotations and an output schema, this description covers purpose, usage, permissions, and return format. It is complete for an agent to confidently invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The tool description doesn't add extra parameter meaning beyond what the schema provides, but it also doesn't need to. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List archived private threads under a parent text channel.' It clearly distinguishes this from the sibling tool channels_list_joined_private_archived_threads in the 'When NOT to use' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use ('Moderation review of historical private threads') and when NOT to use, naming the alternative tool. This is exactly the kind of guidance that helps an agent select among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description adds critical behavioral details: the atomic wholesale replacement, the deletion of unspecified commands, the empty-array danger, the ConfirmRequired gate, the MCP_DRY_RUN requirement, and the return shape. This fully discloses what gets destroyed and what conditions are needed to apply changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headers (Purpose, When to use, Caution, Security, Returns). Every sentence earns its place, covering all essential aspects without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 explains the atomic replacement semantics, the use case, the danger of empty arrays, the confirmation/dry-run flow, and the return value. Combined with rich annotations and output schema, it provides all necessary context for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 repeats __confirm semantics and empty-array behavior already present in the schema, adding no new information about the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'REPLACE' with the resource 'entire global command registry' and clarifies that commands not included are deleted. This clearly distinguishes it from siblings like commands_create_global (single create) and commands_bulk_overwrite_guild (guild-scoped).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete use case (CI deploy re-sync) and a caution to call commands_list_global first to confirm scope. It does not explicitly list when-not-to-use or name alternative tools, but the context is clear enough for an agent to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint, idempotentHint), the description reveals critical behavior: any commands not listed are deleted, an empty array deletes every command, the operation is atomic, and it requires __confirm:true combined with MCP_DRY_RUN=false to apply. It also discloses the dry-run preview fallback and the exact return shape. This goes well beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured with bold labels (Purpose, Caution, Security, Returns) and every sentence carries meaningful information. It is compact yet complete, front-loading the core purpose and then layering caution and security details. No filler or redundancy exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, high-impact bulk operation, the description covers the purpose, safety confirmation, dry-run behavior, and return format. The schema covers all parameters, and the description's caution about confirming scope addresses the main companion tool. Together with annotations, this leaves no significant operational gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for all four parameters, including descriptions for commands, guild_id, __confirm, and application_id. The description adds no new parameter-level detail beyond what the schema states; it only restates the replace semantics already in the schema's commands description. Baseline 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Atomically REPLACE the guild-scoped command registry.' It clearly distinguishes from global bulk overwrite and per-command create/modify/delete siblings by emphasizing the guild scope and wholesale replacement semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Caution' line explicitly instructs to call commands_list_guild first to confirm scope, which is direct guidance for safe usage and names an alternative. It implies when to use this tool (full replacement) but doesn't enumerate all when-not scenarios. This is clear context with one named alternative, short of exhaustive exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations by revealing that the output is an ASCII string representing the layout and that the tool does not send anything. This complements the declared readOnlyHint and idempotentHint. It could go further by mentioning any limitations, but it is sufficient for a safe, read-only preview operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise with two sentences: one for purpose and usage, one for the return value. It is front-loaded with 'Purpose' and includes all essential information without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only, idempotent), the description is complete. It explains the purpose, the offline workflow, the return format ({ascii}), and the output schema exists. No additional context is needed 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'components' parameter, whose description 'Components array to render' is clear. The tool description does not add additional parameter-level detail beyond restating that it renders a layout, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Render a Components V2 layout as ASCII') and clearly distinguishes from siblings by stating it is for sanity-checking structure without sending. It also pairs with components_v2_validate, which reinforces its unique role among the components_v2 tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'so the agent can sanity-check structure without sending' and 'for offline iteration'. It also names a complementary tool (components_v2_validate), providing clear context for when this preview is appropriate vs. sending or editing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the return payload shape and 'all custom emojis' scope, which is useful context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four labeled sections (Purpose, When to use, When NOT to use, Returns), each one line, front-loaded with the purpose. Zero fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity list tool (single param, output schema available), the description covers purpose, usage, exclusions, and return format. It is complete and leaves no decision gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% – guild_id is described as 'Guild to inspect' with a regex pattern. The description does not add parameter-specific detail, but none is needed here; the schema carries the load, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'List all custom emojis defined in a guild' – a specific verb, resource, and scope. It explicitly distinguishes from app_emojis_list, an unambiguous sibling, in the 'When NOT to use' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' (inventory custom emoji, pick for reaction) and 'When NOT to use' sections naming app_emojis_list as the alternative. This gives clear, actionable selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the read-only, idempotent, non-destructive nature, and the description adds valuable behavioral details: the projected event shape, optional user_count, missing creator_id for pre-October 2021 events, and the raw/untrusted_text distinction. This goes well beyond the annotation 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, using bold labels (Purpose, When to use, Returns) to front-load key information. Every sentence adds 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the rich annotations (readOnly, idempotent, openWorld), full schema coverage, and presence of an output schema, the description covers all necessary context: purpose, usage timing, return shape quirks, and edge cases like historical creator_id absence. It is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters. The description adds no extra parameter-level semantics beyond referencing the optional user_count, which is already in the schema. The schema fully carries this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Fetch a single scheduled event by id', clearly identifying the verb (fetch), resource (scheduled event), and scope (by id). This distinguishes it from sibling tools like events_list, events_create, events_modify, and events_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly states: 'Inspect a specific event before modifying or deleting.' This provides clear context for when to call this tool rather than event-modification tools, though it doesn't explicitly mention alternatives by name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds significant behavioral context: the tool also disconnects associated webhooks, is gated by ConfirmRequired, requires both __confirm:true and MCP_DRY_RUN=false to actually execute. This goes beyond the structured fields and gives the agent crucial safety information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with clear labels (Purpose, When to use, Returns, Security). Every sentence provides essential information—purpose, use case, output shape, and safety gate—without any filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, four parameters, and existing annotations and output schema, the description covers all necessary aspects: what it does, when to use it, side effects, return value, and confirmation requirements. It is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with descriptive text for every parameter (guild_id, __confirm, audit_reason, integration_id). The description does not add new parameter-level semantics beyond the schema, only restates the confirmation requirement already present in the __confirm field. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states 'Delete an integration from a guild' with a specific verb and resource, and distinguishes itself from sibling tools by mentioning the destructive side effect of disconnecting associated webhooks. This clearly identifies what the tool does and separates it from other delete-type tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section identifies a concrete scenario (remove stale or compromised third-party integration) and the security requirement clarifies prerequisites. It does not explicitly state when not to use the tool or point to alternatives, but the context is clear enough for an agent to make a reasonable selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool non-destructive, read-only, open-world, and idempotent. The description adds valuable context with the no-auth note and the mention that it's a raw passthrough of the Discord API, giving the agent a clearer picture of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise yet well-structured, using bold headings to separate purpose, usage, and return value. Every sentence adds relevant information, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter GET tool with an output schema, the description covers the purpose, usage conditions, authentication requirements, and return fields. It is complete and sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter (guild_id) with a pattern and description. The description doesn't add extra parameter-level semantics, but since schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving the public guild widget JSON, with a specific verb and resource. It also distinguishes itself from sibling tools like guild_get_widget_settings and guild_get_widget_image_url by focusing on the raw JSON endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says when to use it (rendering a public widget on a website), notes a prerequisite (widget must be enabled), and references the relevant settings tool. It also clarifies that no bot auth is required, which helps the agent choose this over authenticated alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. The description adds a critical behavioral trait: 'No REST call is performed', which means the tool is purely a URL synthesizer and the agent decides whether to fetch. This goes beyond annotations and manages expectations about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized via bold headers and bullet lists. Purpose is front-loaded, and each sentence serves a clear function: purpose, usage context, exclusions, and return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, output schema present, annotations available), the description covers all necessary aspects: purpose, usage, non-usage exclusions, and return structure. No significant gaps 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—both `guild_id` and `style` have descriptions, including enum values and defaults. The description's Returns section illustrates how `style` is embedded into the URL, but this is only a marginal addition over the schema's existing parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'synthesize' plus resource 'public widget PNG URL', and immediately clarifies that no REST call is performed. It also distinguishes itself from sibling tools by referencing `guild_get_widget` and `guild_get_widget_settings`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is an explicit 'When to use' section (embedding a widget image) and a 'When NOT to use' section pointing to `guild_get_widget` for JSON data and `guild_get_widget_settings` for admin settings. This is exactly what this dimension asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds further context: it explicitly returns `{enabled, channel_id}` and notes it is an admin view. This goes beyond the annotations by clarifying the exact data inspected, though it omits details like authentication requirements or potential errors, which are not critical given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with headers for purpose, usage, and returns. Every sentence adds value, with no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with full annotations and an output schema, the description is complete. It covers purpose, usage guidance, return values, and differentiates from siblings, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the only parameter `guild_id` is described as 'Guild to query'). The description does not add significant semantic detail beyond the schema, so a baseline score of 3 is appropriate since the schema already handles parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves widget settings for a guild in an admin view, using a specific verb and resource. It also distinguishes itself from the sibling tool `guild_get_widget` by explicitly mentioning the admin view, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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, including a direct reference to the alternative tool `guild_get_widget` for public data. This leaves no ambiguity about when to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond the annotations: it explains that suppress means 'mute on stage', clarifies the audience/speaker role, and notes the return behavior (`{ok, user_id, channel_id}` and Discord's 204 no-body response). Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description complements rather than repeats them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely well-structured with bolded labels (Purpose, When to use, When NOT to use, Returns). Every sentence adds value and there is zero redundancy. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, usage constraints, exclusion criteria, and return behavior. Combined with the annotations and 100% schema coverage, it provides the agent with all necessary context to correctly select and invoke the tool. No critical gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 a small semantic clarification for `suppress` ('mute on stage') but does not deeply enhance the parameter explanations beyond what the schema already provides. This aligns with the expected baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource construction: 'Update another user's voice state in a stage channel', and clarifies the suppress semantics as 'mute on stage'. It clearly distinguishes from the sibling `guild_modify_current_voice_state` by specifying 'another user's' versus the bot's own state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 provide explicit guidance, including the exact alternative tool for the agent's own voice state (`guild_modify_current_voice_state`). This directly addresses when the tool is appropriate and when it is not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the server has no API keys and relies on MCP sampling from the client, plus a fallback returning raw messages when sampling is unsupported. This notably expands on the readOnly/idempotent annotations by exposing a dependency on client capabilities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Uses bold section headers to separate Purpose, When to use, Returns, and Fallback. Every sentence conveys meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage triggers, return shape, and critical fallback behavior for clients lacking sampling. This is especially valuable given the tool's dependency on client-side LLM capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all three parameters (limit, style, channel_id) with defaults and constraints; the description adds no per-parameter semantics. Baseline score due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Summarize') and resource ('recent messages in a Discord channel'), with the additional qualifier of using the client's LLM. This distinguishes it from sibling intelligence tools and directly matches 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete example user queries ('what was discussed in #X?', 'catch me up', 'TL;DR') that signal when to invoke. Does not explicitly exclude cases or name alternatives, but the use-case framing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description adds critical behavioral details: irreversibility, auth specifics (token-secured, no bot token), return payload, and the dry-run/confirmation gate. This provides substantial value beyond what 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, using bold labels for Purpose, Auth, and Returns. Each sentence is purposeful: it covers what the tool does, safety, authorization, and critical execution requirements. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with a 4-parameter schema and output schema, the description covers all essential aspects: purpose, irreversibility, auth, return format, and the confirmation/dry-run mechanism. The presence of an output schema means return-value explanation is not necessary. It is sufficient for an agent to invoke safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful context for __confirm (requires MCP_DRY_RUN=false) and emphasizes the interaction_token's scoped nature, which goes beyond the schema's field-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a follow-up message.' It uses a specific verb and resource, making it distinct from sibling tools like messages_delete or interactions_delete_original_response. The destructive and irreversible nature is also highlighted upfront.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage requirements (pass __confirm:true AND MCP_DRY_RUN=false) and auth constraints, which are helpful. However, it does not explicitly contrast with alternatives or state when to choose this tool over similar deletion tools. The context is clear from the resource name but lacks direct alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which already indicate destructiveness), the description adds crucial behavioral details: 'DESTRUCTIVE - IRREVERSIBLE', auth requirements ('token-secured NO bot token'), return value, and the explicit confirmation gate ('Pass __confirm:true AND MCP_DRY_RUN=false to actually delete'). This thoroughly explains the tool's side effects and safeguards, 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose first, then a prominent destructive warning, followed by auth, return, and confirmation instructions. Every line adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool, the description covers all essential context: what it does, its irreversibility, security requirements, return value, and the exact conditions to execute. The confirm/dry-run mechanism is fully explained, making the tool safe to invoke correctly even without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions, so the baseline is 3. The description mentions __confirm and MCP_DRY_RUN, but these are already explained in the schema, so the description adds no new parameter-level meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete the original interaction response message' with a precise verb and resource, clearly distinguishing it from sibling tools like interactions_get_original_response, interactions_edit_original_response, and interactions_delete_followup. This is exactly what a purpose statement should do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose clearly conveys when to use this tool (deleting the original interaction response), and the destructive label provides implicit caution. It does not explicitly name alternatives or exclusions, but no confusion arises given the sibling names and the specific resource mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint), the description adds important behavioral context: auth is token-secured and explicitly 'NO bot token', and it details the return structure including that 'content' is raw Discord data while 'untrusted_messages' is a separately fenced copy. This goes well beyond what annotations reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with bold labels (Purpose, Auth, Returns). Every sentence provides necessary information with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 are further specified elsewhere. The description covers purpose, auth, and return behavior concisely. For a simple fetch tool, this is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well documented. The description adds minimal semantic value beyond implying message_id refers to a previously created follow-up, which the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Fetch a follow-up message previously created by interactions_create_followup' — a specific verb ('Fetch'), a clear resource ('follow-up message'), and an explicit reference to the create sibling, distinguishing it from edit/delete/original response tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly implies the tool is for retrieving follow-up messages created earlier, and ties it to interactions_create_followup. It does not explicitly exclude alternatives like getting the original response, but the context is sufficient for an agent to select this tool among the many sibling message tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description goes beyond by specifying 'active' invites (implying expired ones are excluded) and detailing the return object shape. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded section headers (Purpose, When to use, When NOT to use, Returns) and bullet-like formatting. Every sentence conveys needed information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and clear annotations, the description fully explains the tool's scope, usage boundaries with a sibling tool, and the return payload structure. No important behavioral or contextual elements are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter `channel_id` is fully described in the schema ('Channel to list invites for') with a validation pattern, so schema coverage is 100%. The description adds no extra parameter-level details, meriting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'List active invites for a single channel' — a specific verb + resource + scope that clearly distinguishes it from guild-level invite tools. It also explicitly contrasts with `guild_list_invites` (all invites across a guild).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit '**When to use**' scenarios (audit invite creators, cleanup candidates) and a '**When NOT to use**' section naming the exact alternative tool (`guild_list_invites`). This gives the agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include idempotentHint=true and destructiveHint=false, so the bar is lower. The description adds value by clarifying that re-adding is a no-op and by listing the return shape `{added, user_id, role_id}`. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, well-structured with clear sections, and every sentence provides essential information. It front-loads the purpose and includes only necessary guidance, keeping it highly readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple role-add operation, the description covers the essential context: purpose, usage, alternative, idempotency, and return values. With a high-quality schema and annotations, nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the description doesn't need to elaborate on parameters. The description adds no parameter-specific details beyond the schema, which is acceptable for the high-coverage case, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a single role to a guild member.' It uses a specific verb and resource, and distinguishes itself from related tools by explicitly noting it handles a single role, not the entire role set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 with a concrete example of a targeted role grant, and names the alternative tool `members_modify` for replacing role sets. This gives clear guidance and prevents misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses the two-step API call sequence ('via GET /users/@me followed by GET /guilds/{guild.id}/members/{bot.id}') and the return structure. It also highlights a nuance: 'Structured nick remains raw Discord data; the human-readable text response fences it.' 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with bolded labels, a concise purpose sentence, a bullet-point use case, and a compact returns section. Every sentence contributes useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read operation with an output schema, the description covers purpose, when to use, and return fields. It also mentions the intent requirement avoidance, making it fully sufficient for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of the single parameter with a clear description ('Guild to inspect'). The tool description only refers to 'target guild' generically, adding no new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Fetch the current bot user's own member entry in a guild.' This clearly distinguishes it from siblings like members_get by focusing on the bot's own membership. The mention of the underlying endpoints further anchors its exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
A 'When to use' section explains the key scenario: discovering the bot's nick and role assignments without needing the GUILD_MEMBERS intent. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of full comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating operation (readOnlyHint=false). The description adds context about the thread being public, anchored to an existing message, and includes the return structure. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, using clear sections for purpose, usage, non-usage, example, and return value. Every sentence contributes value without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for this tool: it explains when to use it, when not to, provides an example, and specifies the return format. Given the schema is fully detailed and output schema exists, no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description provides a concrete example with placeholder IDs and a name, which adds some practical illustration, but does not deeply explain parameter semantics beyond the schema's existing descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Start a public thread anchored to an existing message.' This is a specific verb+resource combination that distinguishes it from sibling tools like channels_forum_create_thread, which is explicitly called out.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 alternatives such as channels_forum_create_thread for forum channels and a future standalone thread tool. This gives clear decision-making guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating, non-read-only operation, but the description adds the specific 403 rejection for non-bot messages and discloses the return object format. This goes beyond the structured fields to clarify an important behavioral constraint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured using bold labels for Purpose, When to use, When NOT to use, and Returns. Each sentence earns its place, providing essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple edit tool, the description covers the core purpose, key limitations, and return value. The output schema exists, so return details are explicitly stated. This is complete given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (content, channel_id, message_id) described in the schema. The tool description does not add additional parameter semantics beyond what is already provided, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits a Discord message previously sent by the bot, using a specific verb and resource. It also differentiates from sibling message tools by emphasizing the bot-author restriction, which is a key distinguishing factor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists concrete use cases (typos, status updates, embeds), and the 'When NOT to use' section explicitly warns against editing foreign messages with the 403 error. This provides clear guidance on when to use the tool and when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context about the return shape (field list) and the raw Discord data vs. human-readable MCP content distinction, which is beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold headers, concise bullets, a concrete example, and a compact returns list. Every sentence serves a purpose; no filler or redundant repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 required params, read-only, output schema present). The description covers purpose, usage criteria, when not to use, an example, and expected return fields. Combined with annotations and schema, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both params described ('Channel containing the message', 'Message to fetch'). The description's example is illustrative but adds no new semantic meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Fetch a single Discord message by ID.' It clearly distinguishes from sibling messages_read (which reads windows of messages) by the word 'single' and explicit scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 named alternative: 'use messages_read' for windows of recent messages. This is precise guidance with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 clear. The description adds value by specifying the exact return structure (`{pins:[...], count, channel_id}`) and clarifying that structured pin fields are raw Discord data while the human-readable MCP content response fences message text. This goes beyond the annotations, though it does not mention potential permission requirements or edge cases like empty pins.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded headers (Purpose, When to use, When NOT to use, Returns) and concise bullets. It front-loads the purpose, uses short sentences, and contains no fluff; every sentence contributes distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter, the description covers purpose, usage context, return format, and a nuance about raw vs human-readable content. Combined with strong annotations and the schema covering all parameters, it provides a complete picture for an AI 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter (`channel_id`) with a clear description ('Channel to inspect'). The tool description does not add parameter-specific semantics, but the schema already provides sufficient meaning, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List the pinned messages in a channel' with a specific verb and resource, and it distinguishes itself from `messages_read` by explicitly saying 'Reading recent activity → use `messages_read`'. This makes the purpose unambiguous and clearly differentiates from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It includes a dedicated 'When to use' section with concrete use cases ('persistent pinned content (FAQs, rules, announcements)') and a 'When NOT to use' section that names `messages_read` as the alternative. This gives explicit, actionable guidance for when to select this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 by disclosing that the tool 'only fans out the most recent N messages of ONE channel and filters client-side,' which clarifies its scope and implementation. It also explains the return format behavior (raw Discord data vs. human-readable fenced content). This goes beyond the annotations but does not cover auth/rate-limit details, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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, Example, Returns) and no redundant prose. Every section earns its place, and the entire text is compact and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nuanced behavior (client-side filtering, single-channel scope, no server-wide search). The description covers purpose, usage windows, limitations, a concrete example, and the return shape. Given the existing annotations and output schema, this fully equips an agent to decide when and how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a descriptive comment covering meaning, defaults, and constraints (e.g., limit is 'Max recent messages to scan (1-100, default 100). NOT a result cap.'). The description adds an example mapping channel_id, query, and limit, but this does not fundamentally enrich the schema-provided semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Substring-search recent messages in a channel.' This clearly distinguishes it from sibling tools like messages_get (retrieve by ID) and messages_read (read a specific message), and further narrows scope with 'recent messages' and 'ONE channel.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly states the intended scenario (locate a recent message by keyword without manual iteration), and 'When NOT to use' explicitly excludes server-wide search and directs users to external indexing for deep history. This provides clear both positive and negative guidance with an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation. The description adds useful context: it's plain-text only, implies bot rate-limit behavior by recommending webhooks for high-volume, and states the return shape. It does not contradict annotations, though it could have noted permission requirements or side effects more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bolded sections, bullet points, an example, and return type. Every sentence serves a purpose, and the content is front-loaded with the most critical information. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, no nested objects, output schema present), the description covers purpose, usage, exclusions, example, and return values comprehensively. It's sufficient for an agent to invoke correctly without further guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds a concrete example and return fields, but does not introduce additional semantic meaning beyond the schema's parameter docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Send a plain-text message to a Discord channel.' It clearly distinguishes this tool from rich-layout senders (components_v2_send) and webhooks_execute, and the scope (plain-text, programmatic announcements) is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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, naming alternative tools (components_v2_send, webhooks_execute) and a concrete user-request example. This fully guides the agent on selecting 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds the important behavioral nuance that unpinning does not delete the message itself, and it specifies the return format `{unpinned, channel_id, message_id}`. This goes beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: Purpose, When to use, When NOT to use, Returns. Every sentence adds value and it is front-loaded with the primary purpose. No redundant or extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description covers purpose, usage scenarios, exclusions, and return values. Combined with complete schema and annotations, there is no ambiguity for an agent. The presence of an output schema further reduces the need to explain returns, yet the description still does so.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters (channel_id, message_id, audit_reason), so the schema fully documents parameter meanings. The description does not add parameter-level detail, which is acceptable because the schema carries the burden. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Remove a pinned message from a channel.' This clearly distinguishes it from siblings like messages_pin (opposite action) and messages_delete (explicitly noted as different). The verb+resource 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section with concrete examples (rotate pinned content, un-stick stale announcements) and a 'When NOT to use' section that names the alternative tool `messages_delete` and clarifies the scope (only un-pins, does not delete the message). This is explicit and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds valuable behavioral context: it only verifies Discord API readback, not the end-to-end join experience. It also discloses that prompt/option text is raw Discord data and that untrusted_text is a separately fenced copy, giving the agent important expectations about the return data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section labels (Purpose, Verification boundary, Returns, See) and is front-loaded with the core purpose. Every sentence earns its place, and it is appropriately sized for a simple GET tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only fetch tool with annotations and an output schema, this description is comprehensive. It covers purpose, limitations, return fields, and a documentation link, leaving no critical gaps for an agent to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single guild_id parameter, and the description adds no additional parameter-specific meaning. The baseline of 3 applies since the schema already fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Fetch a guild's onboarding configuration.' This clearly distinguishes it from sibling tools like onboarding_modify. The purpose is unambiguous and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Verification boundary' provides clear context on what this tool does and does not verify, explicitly warning that when prompts are enabled, the actual join flow must be validated with a client before declaring completion. This is a strong when-not, though it does not explicitly name alternative tools for that validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the effect on Discord ('result message is updated'), the authorization constraint, and the return shape. These add meaningful behavioral context beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with 'Purpose', and uses labeled sections (Purpose, Note, Returns). Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-required-parameter tool, this description covers purpose, a key constraint, and the return value. The schema covers parameter details and the output schema is present, so the description is complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for channel_id, message_id, and audit_reason. The description adds no extra parameter-specific detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Immediately end a poll (expire it)', which is a specific verb and resource. It clearly distinguishes this from sibling tools like polls_get_voters, and the note about author-only restriction adds precise scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies the usage context, and the note 'Only the poll author (your bot) can end its own polls' provides a clear prerequisite and limitation. There are no direct alternatives to exclude among siblings, so the guidance is adequate but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotent and non-destructive aspects. The description additionally clarifies the scope (only the bot's own reaction) and includes return shape, adding context beyond the schema. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear labels (Purpose, When to use, When NOT to use, Returns). Every section is informative and compact – no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple reaction-removal tool with full schemas, annotations, and output shape stated, the description fully covers purpose, usage boundaries, return values, and safe behavior alternatives. Complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter fully described (emoji format, channel/message ID patterns). The description adds no extra parameter detail, which is acceptable since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Remove the bot's own reaction from a message' – a specific verb and resource combined with scope. It distinguishes from sibling tools by limiting to the bot's own reaction and by referencing alternatives in the 'When NOT to use' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use scenarios (roll back erroneous reaction, cleanup after poll) and explicit when-not-to-use with named alternative tools (reactions_delete_user, reactions_delete_all). This leaves no ambiguity for agent selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), but the description adds valuable behavioral nuance: it warns that `permissions` is a base-10 STRING due to JS number safety, and it discloses the return payload fields. This goes beyond what annotations provide, though it does not mention permissions prerequisites or audit-log side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured with bolded headers for Purpose, When to use, and Returns. Every sentence adds value: purpose, use-case, a critical parameter tip, and return shape. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 9 parameters and a fully descriptive schema, the description covers the essential context: what the tool does, when to use it, a key parameter caveat, and the return structure. The output schema also exists, so the return fields are fully documented elsewhere. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 important semantic detail for the `permissions` parameter (base-10 string, bitfields exceed JS safety), which is not obvious from the schema alone. This elevates the parameter understanding beyond the structured field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a new role in a guild' – a specific verb and resource that clearly distinguishes this from sibling tools like roles_modify, roles_delete, and roles_list. No ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section provides explicit context ('Programmatic role provisioning (e.g. tier-based roles, integration roles)'), which helps guide selection. However, it does not explicitly mention alternatives or exclusions, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint and readOnlyHint false, but the description adds valuable behavioral context: irreversibility, the ConfirmRequired gate, the MCP_DRY_RUN=false requirement, and the return shape. This goes beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with purpose, and uses labeled sections (Purpose, When to use, Returns, Security). Every sentence carries necessary information without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation, the description covers the action, usage scenario, return value, and security prerequisites. With an output schema present and full parameter coverage, this is complete guidance for an agent to use the tool safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 does not add new parameter-level semantics beyond the schema's existing detail — the __confirm behavior, channel_id pattern, and audit_reason are all already fully described in the schema. It only references the confirm requirement without adding new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'End the live Stage instance for a channel' — a specific verb and resource that clearly distinguishes it from sibling tools like stage_instances_create, stage_instances_get, and stage_instances_modify. Adding 'DESTRUCTIVE - IRREVERSIBLE' reinforces the action's nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit 'When to use' context: 'stop a stage talk.' It lacks explicit exclusions or named alternatives, but the context is clear enough for a simple delete operation. The security note about confirm is a form of precondition guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description emphasizes 'DESTRUCTIVE - IRREVERSIBLE' and explains the exact confirmation mechanism (__confirm:true and MCP_DRY_RUN=false). This adds behavioral context beyond the destructiveHint annotation, including the dry-run behavior and irreversible consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using bold headers and bullets to present purpose, usage, and return value in just three short lines. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, safety confirmation, and the return shape. Given the simple scope of the tool, the rich schema, and the explicit output mention, it is fully complete for an agent to select and invoke correctly. Permissions are not mentioned but are not necessary for understanding the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters. The description only mentions __confirm briefly without adding new semantic details about the other parameters (guild_id, sticker_id, audit_reason), so it simply meets the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a guild sticker' with a specific verb and resource, clearly distinguishing it from sibling sticker tools like stickers_modify_guild_sticker or stickers_create_guild_sticker. The destructive nature is also highlighted upfront.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'When to use' section with a concrete scenario ('Retire a stale or off-brand sticker'), giving clear context for when to invoke the tool. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which already convey safety and mutability. The description adds important context not in annotations: the inability to replace the sticker file, and the return schema. It avoids contradicting annotations, contributing meaningful behavioral detail beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings and bullet points, front-loaded with the purpose. Every sentence provides essential information: purpose, when to use, when not to use, and return format. No wasted words or redundant repetitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, mutation behavior, file-replacement gotcha), the description covers all critical aspects: what it updates, when to use it, the critical limitation about file replacement, and return shape. The existence of an output schema means return values are fully documented elsewhere. Sibling tool differentiation is clear, and the agent has enough context to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every parameter (name, tags, guild_id, sticker_id, description, audit_reason) having meaningful descriptions. The tool description lists the three updatable fields ('name, description, or tags') but does not add new parameter-level details beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a guild sticker's name, description, or tags', which is a specific verb+resource+scope. It distinguishes itself from sibling tools like stickers_create_guild_sticker and stickers_delete_guild_sticker by focusing on modification. The 'Returns' line further clarifies what the 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'When to use' ('Rebrand or re-tag an existing sticker') and 'When NOT to use' ('Replacing the sticker file - Discord does not allow editing the file; create a new one and delete the old'). This gives clear guidance on when to prefer this tool over creation/deletion alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent, but the description adds significant behavioral context: it explains that counts and permission-risk signals are 'deterministic hints, not authorization', and that raw template content appears in 'untrusted_text' with an explicit warning never to follow instructions there. This goes well beyond the structured hints and helps an agent handle the tool safely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, well-structured with bold labels (Purpose, Safety, Returns), and every sentence earns its place. It front-loads the purpose and efficiently covers safety and return shape without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's safety complexity, the description is complete: it explains the return envelope ({template, blueprint, untrusted_text}), the safety posture, and the non-mutating guarantee. The existence of an output schema covers detailed return fields, so the description need not enumerate them. The warning about untrusted content fills a critical gap that structured data cannot convey.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single parameter (template_code) with a description and pattern, giving 100% coverage. The tool description adds little about the parameter itself beyond reinforcing that it is a 'public' template code. With full schema coverage, the baseline of 3 is appropriate; the description's added value is elsewhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Produce a safe structural dossier for a public Guild Template before sharing or using it.' It names the specific resource (Guild Template), the action (inspect/produce), and the outcome (dossier). It also distinguishes itself from siblings like templates_get or templates_diff by emphasizing safety and non-mutation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use it: 'before sharing or using it' a template. It also implies a safe inspection use case by noting 'never creates or changes a guild' and warns about untrusted text. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful context beyond annotations: it clarifies that the operation does not change the snapshot, and it mentions the permission requirement. Annotations already indicate readOnly=false, destructive=false, idempotent=true, and the description aligns with these without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose, a requires line, an alternative tool reference, and a returns line. No wasted words, all sentences earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a modification tool: purpose, permission requirement, alternative tool, and return value. With annotations and output schema available, it covers all necessary context without redundancy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already described. The description only mentions 'name and/or description' which maps to the schema but adds no new 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a Guild Template's name and/or description without changing its snapshot. This specific verb-resource pairing and the explicit 'without changing its snapshot' scope distinguishes it from sibling tools like templates_sync.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the required MANAGE_GUILD permission and tells the agent to use templates_sync when the source guild layout changed, providing a clear alternative for a different scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the annotations: read-only and strict safety gates, rejection criteria, confidence levels for unknown dirty states, source permission risk handling, and fencing of untrusted text. It also explicitly states 'This tool never changes a guild', consistent with readOnlyHint and destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded sections (Purpose, When to use, Safety, Returns) and front-loaded with the most important information. Every sentence carries meaningful detail, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage scenarios, safety behavior, and return values (primary template, bounded inspirations, evidence, digests, rejection reasons). Combined with the output schema and annotations, it provides a complete picture for an AI 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters in the input schema have complete descriptions (100% coverage), so the description contributes no additional parameter-level semantics. The schema already explains 'request' and 'preferred_primary_code' well, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('recommend') and resource ('Discord template from bundled public catalog') for natural-language server requests. It clearly distinguishes the tool from siblings like templates_list or templates_get by focusing on recommendation and portfolio selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section with concrete examples ('build a professional gaming server', 'design a technology community') and instructs to use this tool first. It lacks explicit exclusions or named alternatives, but the context is clear enough for an AI agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond the annotations: the operation requires a specific permission, does not affect existing guilds, has fidelity limitations due to Discord's serialization, and returns a specific structure. This is valuable information that annotations alone do not 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Purpose, Requires, Snapshot fidelity, Returns). Every sentence serves a purpose, providing necessary context without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's niche purpose, the description covers prerequisites, side effects, limitations, and return format. The output schema exists, so return details are already structured; the description completes the picture with usage guidance and verification steps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a clear description. The tool description does not add additional parameter-specific semantics beyond what the schema provides, which is acceptable given the baseline for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Replace') and resource ('Guild Template snapshot') with the specific action of syncing from the source guild. This distinguishes it from sibling tools like templates_create, templates_modify, and templates_diff, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: the MANAGE_GUILD permission requirement, the effect on future vs existing guilds, and a recommendation to use templates_diff for verification. However, it does not explicitly contrast with alternatives or state when not to use it, so a small gap remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces idempotency while adding the return shape `{left, thread_id}` and the rationale about reducing event fanout. This adds context beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with clear headers for purpose, usage, exclusions, and return value. Every sentence conveys essential information with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation tool, the description covers purpose, usage guidance, exclusion cases, return value, and idempotency. Combined with rich annotations and output schema, no further information is needed for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: `thread_id` is described as 'Thread to leave.' The description does not add further parameter detail, but since the schema fully explains the parameter, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Remove the current bot user from a thread.' It uses a precise verb and resource, explicitly distinguishing from removing a different user via `threads_remove_member`, which makes it unmistakable among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 scenario (bot finished task, reduce noise) and a clear alternative tool (`threads_remove_member`). This exceeds the minimum by offering both affirmative and negative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the GUILD_MEMBERS privileged intent requirement for with_member=true and the snowflake cursor semantics for after. This goes beyond the structured 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with clear headers (Purpose, When to use, Pagination, Returns). Every sentence carries distinct information—purpose, use cases, pagination caveat, and return shape—with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, clear annotations, and an output schema, the description covers all essential aspects: purpose, usage context, pagination nuance, privileged intent requirement, and return structure. It is complete enough for an agent to invoke correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover all parameters, so baseline is 3. The description adds meaningful extra context, particularly the note that Discord requires the GUILD_MEMBERS privileged intent when with_member=true, which is not in the schema. This elevates the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List members of a thread', a specific verb+resource combination that clearly states the action. This distinguishes it from sibling tools like threads_get_member (single member), threads_add_member, and threads_remove_member.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context with 'Audit who is in a private thread; build mention lists' and a dedicated 'When to use' section. However, it does not explicitly state when not to use this tool or point to alternatives like members_list or threads_get_member, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds behavioral context by specifying the returned payload `{removed, thread_id, user_id}` and the user-removal semantics, which goes beyond the structured annotations. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and uses clear labels (Purpose, When to use, When NOT to use, Returns). Every line adds either purpose, usage guidance, or return structure, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter membership-removal tool, the description covers purpose, usage boundaries, and return shape. The output schema exists and annotations cover mutability/idempotency, so no major contextual gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters with descriptions ('User to remove', 'Thread to remove from'), so schema coverage is 100%. The description adds minimal extra param insight beyond referencing the fields in the return shape, matching the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: 'Remove a guild user from a thread.' It distinguishes from the sibling `threads_leave` by explicitly noting that tool is for bot removal, making the tool's specific scope obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists concrete scenarios ('Drop a user out of a private thread; thread cleanup'). The 'When NOT to use' section explicitly names the alternative `threads_leave` for bot removal, providing a clear decision point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 useful context about return data being raw Discord and the untrusted_text field, which is 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with bold headers. Every sentence serves a purpose: purpose, when to use, when not to use, and return details. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read-only tool with rich annotations and an output schema, the description covers purpose, usage, exclusions, and return characteristics. It is fully complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter (user_id) with pattern and description. The description reiterates 'user id' but does not add new parameter-level semantics beyond what the schema provides. Baseline 3 applies due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Look up a public user profile by id'. It distinguishes from siblings by explicitly naming members_get and users_get_current as alternatives for different scenarios.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 with direct references to alternate tools (members_get, users_get_current). This gives clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context by specifying the endpoint and the exact return fields (`{id, username, global_name, avatar, bot, verified}`), which helps the agent understand what data to expect. It does not cover auth requirements or rate limits, but these are not critical for this simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with clear labeled sections: Purpose, When to use, and Returns. Every sentence provides valuable information, and the return type is explicitly listed, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters), the presence of a return description, and supporting annotations, the description fully covers what an agent needs to select and invoke the tool correctly. It includes the endpoint, use cases, and return shape, leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there is nothing to explain. As a baseline for a no-parameter tool, the description appropriately focuses on purpose and return value rather than input semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and identifies the exact resource ('authenticated bot/user profile') with the endpoint (`/users/@me`), making the tool's purpose unambiguous. It also distinguishes from siblings by clarifying it returns the current user's profile, not a specified user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section clearly states two concrete scenarios: confirming bot identity and obtaining the bot ID for tools like `commands_list_guild`. It does not explicitly mention when not to use it or name alternatives, but the guidance is clear and sufficient for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond these: pagination mechanics (cursor types, limit range), the exact return shape, and a special behavioral note about untrusted_names fencing raw Discord data. This significantly enhances understanding of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section labels ('Purpose', 'When to use', 'Pagination', 'Returns') and concise bullet-style sentences. Every line contributes necessary information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of full parameter schema, output schema, and comprehensive annotations, the description covers all necessary operational details: the exact endpoint, pagination limits, return structure, and the untrusted_names caveat. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter having a descriptive comment. The description consolidates this by explaining `before`/`after` as guild-id cursors and reiterating the limit range, but does not add substantial new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List guilds the bot/user is a member of' and directly references the API endpoint `/users/@me/guilds`. This clearly distinguishes it from sibling tools like `guild_get` or `guild_modify` by focusing on the current user's guild membership.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section: 'Discover all guilds the bot has joined.' This provides clear context for when to invoke this tool. It does not mention when not to use it or name alternatives, but for a straightforward read-only list tool, this is adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context about the global scope and the returned shape, which is helpful beyond annotation signals. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely compact with two clearly labeled sections: Purpose and Returns. Every sentence contributes useful information, and the return shape is provided in a structured format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter, read-only listing tool with an output schema, the description covers scope, intended use, and response format. The mention of 'global' adequately separates it from the guild-specific sibling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description correctly includes no parameter-specific details, and the empty input schema means there is nothing further to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the exact resource ('global voice regions') plus the use case ('voice/stage channels'). The word 'global' distinguishes it from the sibling tool guild_list_voice_regions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies global scope, which gently distinguishes it from guild-specific voice-region listing. However, it does not explicitly state when to prefer this tool over the sibling guild_list_voice_regions or provide alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true and readOnlyHint: false, but the description adds meaningful context beyond that: the requirement to pass __confirm:true and set MCP_DRY_RUN=false to actually delete, the return shape {deleted, webhook_id}, and the behavior that audit_reason is ignored on token routes. This enriches the agent's understanding of execution 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, using bold headers for purpose, when-to-use, auth, and returns. Each sentence delivers distinct value with no redundancy. It packs essential operational details into four short blocks while remaining easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 all critical aspects: the action, destructiveness, auth requirements, return value, and the confirmation/dry-run mechanism. Combined with a rich output schema and 100% parameter documentation, this provides a complete operational picture for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 goes beyond schema by explaining the purpose of __confirm and the MCP_DRY_RUN gate, which is critical for correct invocation. It clarifies token handling context ('treat as credential') is already in the schema, but the description's confirmation/dry-run guidance adds semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete a webhook using its token' with a specific verb and resource, and distinguishes it from the sibling webhooks_delete tool by mentioning the token-based auth route. It also flags it as DESTRUCTIVE - IRREVERSIBLE, making the action's nature 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear 'When to use' section: 'Self-decommission when the agent only holds the token.' This communicates the primary scenario and implicitly contrasts with bot-authenticated webhook deletion, though it does not explicitly name the alternative sibling tool. The auth note ('NO Authorization: Bot … header') further clarifies when this route is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description adds crucial behavioral context: it states the tool requires NO Authorization header (uses webhook token) and discloses that returned content is wrapped as untrusted and must be treated as data, not instructions. This security-relevant behavior is not visible in annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (about 60 words), uses clear bolded section labels for Purpose/When to use/Auth/Returns, and each sentence adds distinct value: purpose, use cases, auth requirement, and return format. No redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only fetch tool, the description covers all necessary aspects: what it does, when to use it, authentication model, and return contract. The output schema exists but the description still usefully warns about untrusted content, and the annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is fully described (100% coverage), so the baseline is 3. The description does not elaborate on individual parameters beyond what the schema provides; the auth note touches on the token's role but doesn't add semantic detail for the parameters themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource construction ('Fetch a message previously sent through a webhook'), which precisely identifies the action and object, distinguishing it from sibling webhook tools like webhooks_get (webhook metadata) and messages_get (regular channel message).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section enumerates specific scenarios (confirm delivery, audit, edit prep), and the auth note clarifies it uses webhook token rather than bot auth, giving clear context. However, it doesn't explicitly mention when not to use it or contrast with sibling tools like messages_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it discloses the absence of the bot auth header and Discord's rejection of bot auth on token routes. It also clarifies return semantics (token preserved, `untrusted_name` fenced), which is not evident from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with bold headers and bullet points that make it skimmable. Every sentence adds unique value—purpose, when-to-use, auth behavior, and return details—with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter GET tool with an output schema and comprehensive annotations, the description covers purpose, usage context, authentication nuance, and return specifics. Nothing important is missing to guide correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both `webhook_id` and `token` already described in the schema (e.g., token length, credential warning). The description adds minimal new parameter meaning beyond reinforcing that the token comes from `webhooks_create`, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get a webhook by id + token without bot auth.' This clearly distinguishes it from the sibling `webhooks_get`, which presumably uses bot auth. The purpose is unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly specifies the context: holding the token (e.g., from `webhooks_create`) but lacking guild access. It provides a clear scenario, but does not explicitly name the alternative `webhooks_get` for when guild access is available, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, open-world, idempotent, and non-destructive safety profile, lowering the bar. The description adds valuable behavioral context beyond annotations: 'Structured names remain raw creator-controlled data; the human-readable text response fences them.' This discloses how the tool handles potentially untrusted user input in its output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into three labeled sections (Purpose, When to use, Returns), each with a single focused sentence. It is front-loaded with the purpose and avoids any fluff, making efficient use of every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple single-parameter read-only tool with a full output schema and strong annotations. The description effectively covers purpose, use cases, return shape, and a security-relevant caveat about raw data. No critical behavioral aspects are missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% (channel_id with description 'Channel to query'), so the schema already documents the parameter fully. The description does not add new semantic details about the parameter beyond what the schema provides, such as format or constraints, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List webhooks attached to a single channel.' This clearly distinguishes it from sibling tools like webhooks_list_guild (which lists guild-wide webhooks) and webhooks_get (which retrieves a single webhook by ID). 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section provides concrete scenarios: discovering webhooks before sending via webhooks_execute and auditing a channel for unauthorized webhooks. It explicitly names an alternative tool (webhooks_execute) and implies the channel-scoped nature, offering clear guidance on 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the most important behavioral nuance: welcome_channels is a full replacement list rather than a PATCH-merge, and passing null to description clears it. This prevents a common misuse of the API and is exactly the kind of context annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded, and formatted with bold labels for Purpose, When to use, and Returns. Every line adds information: the replacement semantics, null-to-clear behavior, and return shape, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter update tool, the description covers purpose, when to use, critical replacement semantics, and return value, while the schema covers ids and audit reason. Minor gaps remain, such as prerequisites like the server needing Community settings enabled or explicit pointers to the read-only sibling, but the tool is adequately invocable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes guild_id and audit_reason but leaves enabled, description, and welcome_channels undocumented. The description compensates for two of those by explaining the replacement-list semantics and null-to-clear behavior, while the remaining enabled parameter is self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update the Community welcome screen,' a specific verb+resource statement that distinguishes this tool from broader guild mutation tools. It further lists the three editable aspects (enabled, description, highlighted channels), making the scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section gives concrete scenarios: toggling enabled, changing the top description, and swapping the up-to-5 highlighted channels. It does not explicitly name alternatives or exclusions, such as using guild_get_welcome_screen for reads, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details beyond annotations: auth requires a token but 'NO bot token', the body mirrors a webhook execute body, the ephemeral flag behavior, and the return shape {message_id, channel_id}. This adds significant operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with bolded labels (Purpose, Auth, Body, Returns). Every sentence contributes: purpose, auth, body semantics, ephemeral flag, and return value. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 12 parameters and nested objects, the description covers the essential aspects: when to use, auth, body semantics, and returns. It relies on the schema for parameter details and the output schema for return structure, which is acceptable. It could go deeper on edge cases, but it is sufficiently complete for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, so the description partially compensates by noting the body 'mirrors a webhook execute body' and by explaining the ephemeral parameter's effect. This adds meaning beyond the schema, but does not elaborate on the remaining parameters individually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Send a follow-up message after an interaction has been acknowledged.' This clearly distinguishes the tool from siblings like interactions_create_response (initial response) and messages_send (non-interaction messaging) by specifying timing and context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: 'Useful for long-running work where you replied with a deferred response.' This gives clear context, though it does not name alternative tools or explicitly state when not to use it, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavior: 'Pass only the fields you want to change' and explains voids (null) for clearing nick/timeout. However, it omits permission requirements (e.g., MANAGE_NICKNAMES, MUTE_MEMBERS) and doesn't disclose that replacing roles is a wholesale operation beyond the phrase 'replace role set wholesale.' With annotations present, this is solid but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a single-sentence purpose, a bulleted list of use cases, a bold key instruction, and a return type. Every sentence earns its place, and the format is easily scannable for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, an output schema, and annotations that declare it non-read-only, non-destructive, and idempotent, the description is thorough. It covers purpose, usage, partial-update behavior, and return format. The missing piece is explicit permission requirements, which is a notable gap for a mutation tool, but overall the description is comprehensive enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter described. The description enhances this by grouping parameters into use cases and clarifying the partial-update model (undefined fields ignored). It also explains the null semantics for nick and communication_disabled_until, which are present in the schema but reinforced contextually. The baseline for full schema coverage is 3, and the description adds meaningful semantic grouping, making it a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb ('Modify') and a clear resource ('guild member'), listing the exact fields covered (nick, roles, voice state, timeout). It explicitly distinguishes itself from related tools like members_add_role and members_remove_role, and its sibling set includes similar member tools, making this differentiation valuable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
A dedicated 'When to use' section enumerates specific scenarios (set nickname, replace roles, mute/deafen, move channel, timeout, flags). It explicitly instructs to prefer members_add_role/members_remove_role for single-role operations, providing clear alternative tool guidance. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the prerequisite (channel type 5) and the failure mode (400 error), plus the return fields. Annotations already indicate mutation (readOnlyHint=false), so description adds useful context beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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 is front-loaded. Every sentence is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers purpose, usage, failure conditions, and returns. It lacks explicit permission requirements, but the annotations and output schema compensate, making it sufficiently complete for tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds crucial semantics by specifying that the channel must be an Announcement channel and that the message is an existing announcement, reinforcing the schema's parameter meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool publishes/crossposts a message from an Announcement channel to all following channels. The verb 'Publish (crosspost)' is specific and the resource is well-defined, distinguishing it from sibling tools like messages_send.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 clear alternative (messages_send) for fresh content and a specific error condition (non-Announcement channel). This fully guides the agent in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, non-destructive, and idempotent behavior. The description adds valuable context: no Authorization header needed, body mirrors webhooks_execute except thread_name, thread_id is a query parameter, and return structure. This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured with bold labels, bullet points, and a clear hierarchy. Every sentence serves a purpose—purpose, usage, alternative, auth, body shape, returns—without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with nested objects, the description covers purpose, usage, alternatives, auth, body shape, thread_id distinction, and return value. It doesn't mention error handling or rate limits, but the annotations and output schema fill some gaps, making it nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 58% schema coverage, the description helps by clarifying that the request body mirrors webhooks_execute minus thread_name and that thread_id is a query param. This compensates for undocumented params like content and attachments, even though it doesn't enumerate them directly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Edit a message previously sent by this webhook'—a specific verb + resource that clearly distinguishes it from sending (webhooks_execute) or editing regular messages (messages_edit). It also notes V2 layout support, further differentiating from non-webhook editors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete 'When to use' list (resolved alerts, typo fixes, V2 layout swaps) and explicitly names components_v2_edit as the preferred alternative for V2 layouts. This gives clear guidance on when to use this tool vs. siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms a creation operation ("Upload a new") consistent with readOnlyHint=false. It adds the application-scoped vs. guild-scoped distinction and specifies the return shape `{id, name, animated}`. While annotations cover safety hints, this description adds useful behavioral context beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, using clear sections for purpose, when to use, when not to use, example, and returns. Every sentence provides essential information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with three parameters, the description covers purpose, usage scenarios, an example, and return values. The annotations handle the safety profile, so the description is complete enough for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for all three parameters. The description adds a concrete example (`{application_id:"…", name:"spark", image:"data:image/png;base64,…"}`) that illustrates parameter relationships and expected formats, slightly exceeding schema-only semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource combination: "Upload a new application-scoped custom emoji." It clearly distinguishes from sibling tools like `emojis_create` (guild-scoped) and other app_emojis operations (list/get/modify/delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is provided: "Register an emoji available wherever the bot is - independent of guild." It also includes a clear when-not-to-use with a direct alternative: "Guild-only emoji → use `emojis_create`." This fully satisfies the dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate that this is a write operation. The description adds valuable behavioral context beyond annotations: 'Pick fields that match the type - extra fields are ignored by Discord' and a concrete example illustrating usage. It stops short of describing permission requirements or failure modes, but with annotation coverage this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet well-structured, using bolded mini-headings (Purpose, When to use, When NOT to use, Type values, Example, Returns). Every sentence serves a purpose: defining scope, giving usage context, listing type enums, demonstrating usage, and summarizing output. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 19 parameters, nested objects, and an output schema, the description provides comprehensive context: purpose, type values, exclusions, an example, and a return summary. It fully addresses the agent's need to decide when and how to use the tool, with the schema handling detailed parameter semantics. No significant gaps remain for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, which sets a baseline of 3. The description goes beyond the schema by explaining Discord channel type values (0-16), noting that type-specific fields should be chosen and extra fields are ignored, and providing an example that ties guild_id, name, type, and parent_id together. This adds meaning beyond raw schema definitions, though it doesn't elaborate on every parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new channel in a guild (text, voice, category, announcement, forum, etc.)', which is a specific verb+resource that immediately conveys the tool's function. It also distinguishes from thread creation by explicitly referencing alternative tools for threads, making its scope clear relative to siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance ('Programmatic guild bootstrap; tier-based channel provisioning') and a clear when-NOT-to-use with named alternatives ('Threads - use `messages_create_thread`, `channels_forum_create_thread`, or thread-specific tools'). This is precisely the kind of contextual guidance that helps an agent select the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations indicating read-only, idempotent, and non-destructive behavior, the description adds meaningful context: the bot's visibility limitation, the return structure, and the note about raw Discord data vs. fenced human-readable text. This goes beyond annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured using bold headers (Purpose, When to use, When NOT to use, Returns). Every sentence conveys necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, supportive annotations, and presence of an output schema, the description fully covers purpose, usage, exclusions, and return behavior. No critical gaps remain 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with a description for guild_id. The tool description does not add further parameter-level detail, so the baseline of 3 for high schema coverage applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The purpose is clearly stated with a specific verb and scope: 'List every active thread the bot can see across an entire guild.' This distinguishes it from sibling thread-list tools by emphasizing the guild-wide scope and active-thread filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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, naming alternative tools (channels_list_public_archived_threads / channels_list_private_archived_threads) for excluded cases. This gives the agent clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the annotations by specifying bot-user scoping, the return shape `{threads, has_more, count, channel_id}`, and a note about raw Discord data versus the human-readable response. No contradictions with the annotations (readOnlyHint, idempotentHint, etc.) are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headers, concise bullet points, and no filler. Each sentence earns its place, covering purpose, usage, alternatives, and return format efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only, idempotent nature (annotations), comprehensive schema parameter descriptions, and an output schema, the description is complete. It covers the tool's specific scope, how to distinguish it from alternatives, and the expected response format, which is sufficient for an agent to select and invoke the tool properly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 extra parameter semantics beyond what the schema provides; it only reinforces the return shape, which is already implied by the schema. The parameter details (limit, before, channel_id) are fully documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists private archived threads joined by the current bot user under a parent channel, using the specific verb 'list' and a specific resource. It distinguishes itself from the sibling `channels_list_private_archived_threads` by emphasizing the 'current bot user' scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' and 'When NOT to use' sections provide clear guidance. The description names the alternative tool `channels_list_private_archived_threads` and notes its MANAGE_THREADS permission requirement, making it easy to decide when to use this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by explaining pagination mechanics (pass `before` and `limit`, use `has_more`) and noting that structured names remain raw Discord data while the human-readable response fences them. This adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with labeled sections (Purpose, When to use, Pagination, Returns). Every sentence adds distinct value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, use cases, pagination behavior, and return format. It even includes return details despite an existing output schema, making the tool easy to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already covers all parameters 100%, the description enriches them by clarifying that `before` is derived from a prior `archive_timestamp` and that `has_more` indicates additional pages. This provides practical usage context beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states it 'List archived public threads under a parent text/announcement channel,' which clearly specifies the verb, resource, and scope. This distinguishes it from sibling tools like channels_list_private_archived_threads and channels_list_joined_private_archived_threads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases: 'Recover stale discussions; audit what was archived.' This gives clear context for when to use the tool, though it doesn't explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-destructive operation. The description adds meaningful behavioral context beyond these hints: validation is performed via validateComponentsV2, the call rejects with VALIDATION_FAILED for illegal layouts without making an API call, and the IS_COMPONENTS_V2 flag is irreversible. It also discloses the return 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear bold headers (Purpose, When to use, When NOT to use, Validation, Returns) and is concise. Every sentence serves a purpose: explaining usage, exclusions, validation behavior, and return value. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite moderate complexity (nested allowed_mentions object, validation, irreversibility), the description covers purpose, valid usage contexts, exclusions, validation behavior, and return fields. The existence of sibling tools like messages_send and components_v2_validate is referenced, and the description provides enough context for an agent to select and call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (channel_id and components have descriptions, allowed_mentions does not). The description adds no parameter-specific meaning beyond what the schema already provides; it doesn't explain allowed_mentions or how to structure components. It does reinforce the purpose of components but doesn't compensate for the undocumented allowed_mentions parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Send' and resource 'Components V2 message', and clearly distinguishes it from siblings by stating it's mutually exclusive with content/embed/poll/sticker and by noting the irreversible IS_COMPONENTS_V2 flag. The list of rich layout types (Container, Section, MediaGallery, ActionRow) further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides a 'When to use' section (announcements, release notes, dashboards, polls) and a 'When NOT to use' section that directs to messages_send for simple text replies. This naming of an alternative tool is exactly what strong usage guidance requires.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable behavioral context beyond the annotations: offline operation, rejection of file components with a reason, and the exact return structure. Annotations already declare readOnly/idempotent, but the description discloses additional constraints and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three clearly labeled sections (Purpose, When to use, Returns) with no fluff. Every sentence adds information, and the structure is front-loaded with the most critical info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description fully covers purpose, usage, constraints, and return format. No notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single param, but the schema description is tautological ('Components array (will be validated)'). The tool description enriches the parameter meaning by defining what validation entails (Components V2-specific rules) and clarifying scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Validate a Components V2 components array OFFLINE (no Discord API call)'. Also lists specific validation rules (40-cap, placement, nesting, etc.) and distinguishes it from sibling send/preview tools by emphasizing offline validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance: 'iterate on a layout before sending' and notes it 'saves round-trips'. It implies use before API calls but does not explicitly name alternatives or state when not to use it. Still, the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds the mandatory base64 data URI format, the 256KB rejection threshold, and the return shape, which are useful behavioral details. However, it doesn't explicitly mention permission requirements or what happens on failure (e.g., duplicate emoji), so it stops short of full 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headers, bullet points, and an example. Every sentence adds value: purpose, usage, exclusions, example, and return info. No redundant or filler content exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage context, exclusions, a concrete example, return value, and a critical size constraint. Given the tool has 5 params (3 required) and an output schema exists, the description provides sufficient context for an agent to select and invoke it correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds an example showing the exact format for guild_id, name, and image, and introduces a size limit (256KB) not present in the schema. It doesn't add much for roles or audit_reason, but the provided example and constraint meaningfully extend parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Upload') with a clear resource ('new custom emoji') and target ('guild'). It distinguishes from sibling tools like emojis_modify, emojis_delete, and app_emojis_create by specifying the scope (custom emoji to a guild).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 use cases and alternatives, including the exact sibling tool `app_emojis_create` for application-wide emojis. It also provides a concrete constraint (image > 256KB before base64 is rejected), guiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful context beyond annotations, notably the limitation that image bytes cannot be edited and that image replacement requires creating a new emoji and deleting the old. It also states the return shape. Annotations already declare read-only as false, destructive as false, and idempotent as true, and the description is consistent with these.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with clear section headers (Purpose, When to use, When NOT to use, Returns) and no redundant information. It is front-loaded with the purpose and provides all necessary guidance in a compact format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Combined with the input/output schemas and annotations, the description provides sufficient context for correct tool selection and invocation. It covers usage scenarios, a critical limitation (image bytes cannot be edited), and the expected return structure, making it complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to add parameter details. The description mentions 'name' and 'role restrictions' but does not elaborate on the `roles` replacement semantics or `audit_reason`, leaving those to the schema. Thus, it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update a guild emoji's name and/or role restrictions,' clearly identifying the action and resource. It distinguishes from sibling tools like emojis_create, emojis_delete, and emojis_get by focusing on modifying existing emojis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes 'When to use' and 'When NOT to use' sections, with explicit scenarios like renaming and role tier restrictions, and an exclusion for image replacement with a suggested alternative (create new and delete old). This provides clear guidance on when to use this tool versus alternative operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds critical behavioral details: irreversible deletion, the ConfirmRequired gate, the need for __confirm:true, and the MCP_DRY_RUN=false prerequisite. This greatly exceeds annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three clearly labeled lines (Purpose, Returns, Security) front-load the essential information. Every sentence is informative and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with full schema coverage and an output schema, the description covers purpose, safety, confirmation, and return shape. The security details are particularly complete, making the tool's behavior predictable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for parameter descriptions, so the baseline is 3. The description adds value by explaining the __confirm parameter's role and its interaction with MCP_DRY_RUN, which goes beyond the schema's per-parameter text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' and identifies the exact resource 'test entitlement (dev tool)'. It clearly distinguishes this from sibling tools like entitlements_consume or entitlements_create_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The dev tool tag and delete vs. consume distinction provide clear context for when to use this tool. However, it does not explicitly name alternatives or state when not to use it, so it falls slightly short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive, but the description adds crucial context: "DESTRUCTIVE - IRREVERSIBLE" and the dry-run/confirmation requirement (__confirm:true and MCP_DRY_RUN=false). This goes beyond the annotations and is highly valuable for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings (Purpose, When to use, Returns) and every sentence carries essential information. It is compact with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage guidance, safety/confirmation requirements, and return value. With output schema present, it doesn't need to detail return shape. It is complete for a destructive tool with the given annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description doesn't need to repeat parameter meanings. The description does mention __confirm and MCP_DRY_RUN, but the schema already covers these. No additional parameter-level insight is provided beyond what the schema gives.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: "Delete a scheduled event." It also distinguishes this from modifying an event by contrasting with setting status=4, which is a different sibling tool behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a "When to use" section and gives an alternative (vs. setting status=4 that keeps the record). This helps the agent choose between events_delete and events_modify.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral detail: caller-owned bot and allowlisted guild checks, fail-closed behavior on missing/tampered/cross-caller/wrong-target records, and explicit statements that it never acquires locks, writes checkpoints, or mutates Discord. This is rich context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses clear bolded sections (Purpose, When to use, Safety, Returns) and each sentence earns its place. It is compact despite covering safety and return behavior, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema and strong annotations, the description still adds essential context: the exact usage sequence after guild_blueprint_apply, the security model, and what the return payload contains (proof summary, inventory, drift flags). This is fully sufficient 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all three parameters with full descriptions, so the baseline is 3. The description adds meaning by explaining why these parameters are safety-critical (explicit caller-owned bot, allowlisted guild, active caller boundary), reinforcing the schema's intent without repeating syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Read'), resource ('immutable Activity Evidence for one completed blueprint plan'), and secondary purpose ('verify its current Discord state without changing the guild'). It distinguishes itself from sibling blueprint tools (compile/plan/apply) by focusing on post-apply evidence verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'Use after guild_blueprint_apply reports completion, or later to prove whether the target still matches that approved blueprint.' This is clear context, though it does not explicitly list alternatives or when not to use it beyond the direct use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the non-obvious prune role semantics (ALL roles must be listed, no-role members always pruned) and clarifies that this is a preview returning an estimate, not an actual prune. This adds behavioral context beyond the read-only/idempotent 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headers (Purpose, When to use, etc.), front-loaded with the key purpose, and every sentence earns its place. It is compact yet thorough without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and strong annotations, the description covers purpose, usage, parameter semantics, and return value. No significant gaps remain; it is fully self-contained for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented. The description repeats the include_roles logic verbatim from the schema and does not add new parameter meaning, though it does clearly reference the return value. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Preview' and names the exact resource ('how many members would be pruned'), clearly distinguishing this from sibling tools like guild_begin_prune. It states the tool's purpose succinctly and unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use it: 'Estimate impact before calling guild_begin_prune', naming the relevant sibling tool. It also clarifies the nuanced behavior of include_roles, which helps avoid incorrect use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint:false), the description adds substantial behavioral disclosure: it makes an external request only when invoked, sends no Discord token or query to Emoji.gg, matches queries locally, and warns about third-party metadata and license review. This goes well beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into five labeled sections (Purpose, External request, Safety, Search quality, Returns) and every sentence delivers relevant information without redundancy. It is appropriately sized for the tool's complexity and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with external integration, the description is remarkably complete: it covers purpose, external behavior, privacy, safety/licensing, search limitations, and return structure. The output schema existence is supplemented by the explicit return format, making it highly self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds valuable semantics by explaining that multi-word natural-language queries are matched locally against names/slugs and that user-submitted descriptions are not used for relevance, enhancing understanding of the query parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific purpose: 'Search Emoji.gg for custom-emoji inspiration without changing Discord.' It names the external resource (Emoji.gg), the action (search), and the intended use case, which distinguishes it from Discord-native emoji tools like emojis_get or 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use it: 'before downloading or using `emojis_create`', and explicitly states what it does not do ('never downloads, uploads, or imports an emoji'). However, it does not name alternative tools or offer explicit when-not-to-use guidance, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds crucial behavioral context: 'Returns a SUGGESTED draft for human review - does NOT auto-post' and 'uses the client's LLM.' It also discloses the return shape ({draft, reasoning, sampling_used}), enriching the agent's understanding of what the tool does without modifying Discord state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with four sentences organized under bolded headings: Purpose, When to use, Returns. Every sentence adds value, and the use of bold labels makes it fast to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with 75% schema coverage, an output schema, and rich annotations, the description fully covers the tool's purpose, usage scenarios, return value, and the critical non-posting behavior. It provides enough context for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% with useful descriptions for channel_id, intent, and context_message_count, and tone is covered by its enum. The description adds no parameter-specific guidance beyond the schema, so it meets the baseline but does not exceed it. The usage examples indirectly clarify intent, but not enough to raise the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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: 'Draft a reply to a Discord channel using the client's LLM.' It also explicitly distinguishes itself from sending messages by noting 'Returns a SUGGESTED draft for human review - does NOT auto-post,' which separates it from sibling tools like messages_send.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit 'When to use' section with concrete use cases: 'prepare a moderator response, suggest replies for staff, draft outreach.' It also names the alternative action by stating 'The agent decides whether to actually call messages_send after review,' giving clear guidance on when to use this tool versus sending a message directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context by explaining the input accepts a full URL with prefix stripping, and that return values include raw guild/channel names with a separately fenced `untrusted_names` copy. This is useful added insight beyond the annotation 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with bold headers, bullet points, and a compact example. Every sentence earns its place—no redundancy or fluff—and the most important information (purpose) appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, complete schema coverage, output schema, and strong annotations, the description covers purpose, usage scenarios, exclusions, an example, and return behavior. Nothing essential is missing; the output schema handles the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters, so the baseline is 3. The description adds meaningful extra semantic detail for `code` (accepts full URL, strips prefix) and provides a usage example, enriching the parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('look up') and resource ('Discord invite') with a clear method ('by its code or full URL'). It distinguishes from sibling tools such as invites_list_channel (listing invites) and invites_delete (deleting), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' and 'When NOT to use' sections provide concrete scenarios (inspect an invite before deleting, resolve target guild/channel) and name an alternative tool (`invites_list_channel`) for listing invites. This is clear, direct guidance with exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, but the description adds valuable context: it is 'IRREVERSIBLE without manual unban', requires ConfirmRequired gating, and explains the dry-run mechanism (`MCP_DRY_RUN=false`). It also discloses partial-failure behavior (Discord returns 200 with both arrays), which is not available from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with bold section headers (Purpose, When to use, When NOT to use, Returns, Security). Every sentence adds value, and there is no redundant or filler content. It is appropriately sized for a tool of this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a rich output schema, the description provides a complete overview: purpose, usage cases, exclusions, return shape, and security gating. For a destructive operation with 5 parameters, it covers all critical contextual aspects an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 parameter-level meaning beyond the schema; it simply restates the purpose and confirmation flow. It correctly aligns with schema but doesn't enrich parameter semantics further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Ban many users at once (1-200 per call)', a specific verb+resource+scope that clearly defines the tool's purpose. It distinguishes this bulk operation from sibling `members_ban` by explicitly contrasting single vs. bulk use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' (mass moderation, raid response) and 'When NOT to use' (single user → use members_ban). This gives the agent clear decision criteria for selecting this tool over alternatives, going beyond mere implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds concrete behavioral consequences: 'they lose roles and must rejoin.' It also discloses the security gating requirement (ConfrimRequired) and the exact conditions needed to perform the kick (__confirm:true with MCP_DRY_RUN=false), which 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear Markdown headers, front-loaded purpose, and each section serves a distinct function. It is concise yet comprehensive, covering purpose, usage, returns, and security in a scannable format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool, the description covers all essential context: what the tool does, when to use it, when not to use it, what it returns, and the security gate required to execute. The schema and annotations cover the remaining parameter and safety details, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains every parameter adequately. The description reinforces the __confirm parameter's role in the destructive operation but does not add significant new parameter-level semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb+resource: 'Kick (remove) a member from a guild.' It also distinguishes itself from the sibling members_ban by explicitly stating the kick is non-permanent and does not ban, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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. It directs users to members_ban for permanent bans, giving clear guidance on selecting this tool over a closely related alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds critical behavioral context: it requires the GUILD_MEMBERS privileged intent, explains the cursor-based pagination behavior, and warns that `untrusted_names` and structured member fields must never be treated as instructions. This goes well beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear markdown sections (Purpose, When to use, When NOT to use, Pagination, Requires, Returns). Every sentence serves a distinct function, and the most critical information (purpose and when-not) is front-loaded. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description still summarizes the return shape and highlights a security concern about untrusted data. It covers prerequisites (privileged intent), pagination details, and alternatives. For a list tool with pagination and permission requirements, this is complete and well-rounded.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 repeats the pagination details already present in the schema (after as a user-id cursor, limit 1-1000) without adding new semantic information. It does not explain the default value of limit (already in schema), nor does it provide additional context for guild_id. Thus it adds no value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear statement: "List guild members (paginated)." It uses a specific verb and resource, and explicitly distinguishes itself from the sibling tool members_search by stating "Searching by name → use members_search." This provides strong differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides use cases (bulk audit, export of roles per user) and a clear exclusion (search by name) with a named alternative. It also covers pagination semantics and the privileged intent requirement, giving the agent concrete guidance on when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description goes much further: it declares 'IRREVERSIBLE', mentions the 400 rejection for old messages, and discloses the `ConfirmRequired` precondition plus the `MCP_DRY_RUN=false` requirement. This enriches the safety profile well beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses bolded section headers and bullet points, front-loads the purpose, and each sentence provides unique value (purpose, when/when-not, example, return shape, security). Despite its length, it is tightly organized and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive bulk operation with a security gate, the description covers everything needed: use cases, exclusions, age limits, example invocation, return format, and required confirmation. The provided output schema and annotations are supplemented, not repeated, making this fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 includes an example with `channel_id` and `message_ids` and reiterates the 2-100 range, but this adds little beyond the already-complete property descriptions in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Bulk-delete 2-100 messages from a channel') and explicitly contrasts itself with the sibling `messages_delete` for single messages. It clearly states the batch scope and the channel context, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section gives concrete scenarios (spam/raid sweep, post-incident cleanup), while 'When NOT to use' explicitly names the alternative tool (`messages_delete`) and a hard constraint (Discord rejects >14 days). This is exemplary guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint=true, and the description reinforces this with 'this tool is read-only.' It goes beyond annotations by detailing the return structure (allowed, effective_permissions, decision_trace, etc.) and explaining that allowed:null means insufficient evidence, which is valuable contextual behavior not present 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (Purpose, When to use, When NOT to use, Returns) and is appropriately sized. Every sentence delivers essential information—scope, usage boundaries, and output meaning—with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, permission hierarchy, multiple action types), the description provides sufficient context for an agent to select it correctly: it explains the exact use cases, limitations, and output semantics. The output schema also exists, so return format is covered; the description adds crucial interpretation details like allowed:null.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 add some context (e.g., 'one guild member or one role' hints at mutual exclusivity), but it does not provide per-parameter semantics beyond what the schema already includes. Thus 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific statement: 'Explain effective Discord permissions for one guild member or one role.' This identifies the verb (explain), the resource (Discord permissions), and the scope (member or role), which clearly distinguishes it from siblings like permissions_audit_channel or mutating tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' and 'When NOT to use' sections are provided. It states to use before writes for verification and diagnosis, and explicitly excludes mutating roles/overwrites or treating partial results as permission to write. This gives clear decision guidance without needing to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which are already informative), the description discloses the permission requirement ('Requires Manage Messages'), the mod-action nature, and the return payload shape. This adds meaningful context about auth needs and expected output, which 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headings, front-loads the purpose, and every sentence earns its place. It is compact yet covers purpose, exclusions, returns, and permissions without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the output schema exists, and the description is complete for decision-making and invocation. It includes sibling differentiation, permission requirements, and return shape, leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with clear descriptions, so the schema does the heavy lifting. The description adds no new parameter-level detail beyond what the schema already provides, but it does reinforce the 'specific user' aspect in the purpose. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Remove a specific user's reaction from a message (mod action).' It identifies the specific verb (remove), resource (reaction), and scope (specific user), and distinguishes it from sibling tools by clarifying what it does not do (bot's own reaction, clearing all users).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'When to use' and 'When NOT to use' sections with named alternatives (reactions_delete_own, reactions_delete_all) and the exact conditions for choosing each. This gives an agent unambiguous guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations' destructiveHint=true, the description adds critical behavioral details: irreversibility, impact on all members, the ConfirmRequired security gate, and the need for MCP_DRY_RUN=false. It also states the return payload shape. This is substantial added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses compact bolded headers and clear bullets. Every sentence carries essential information without fluff. It is well-organized and front-loads the purpose and danger.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool, the description covers prerequisites (__confirm, MCP_DRY_RUN=false), alternatives, side effects, and return values. Output schema exists, so complete context is provided for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with meaningful descriptions for all four params. The description reiterates the __confirm requirement, but does not add significant semantics beyond the schema since the schema already documents the confirmation and audit log purpose. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a role from a guild' with explicit destructive consequences ('All members holding this role lose it'). It clearly distinguishes from sibling tools like roles_create, roles_modify, and members_remove_role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' (tear down deprecated/integration roles) and 'When NOT to use' (removing from a single user) with a specific alternative sibling tool (members_remove_role). This fully guides selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds valuable behavioral context: partial updates ('Pass only fields you want to change') and the requirement that permissions is a base-10 string. It does not discuss auth or rate limits, but annotations cover the basic safety traits, so a 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headers for Purpose, When to use, When NOT to use, and Returns. It is concise, front-loaded with the primary purpose, and each bullet/statement earns its place without redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter modification tool, the description covers the essential selection context: what it does, when to use it, important parameter semantics (permissions format), and return values. The output schema exists, so the return field enumeration is a bonus. No critical information is missing for an agent to correctly select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, so the description must compensate. It does so by explicitly calling out the permissions parameter as a base-10 Discord permission bitfield and enumerating the updatable properties (name, color, permissions, mentionable, hoist, icon). This adds meaning beyond the bare schema, though some parameters like unicode_emoji are not individually described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Update a role's properties.' It clearly defines the tool's function and distinguishes it from siblings by explicitly naming alternatives for reordering (roles_modify_positions) and deletion (roles_delete). This makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists concrete scenarios such as renaming, recoloring, changing permissions, toggling mentionability/hoist, and setting role icons. The 'When NOT to use' section provides explicit alternatives for reorder and delete operations, giving the agent strong guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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 valuable behavioral context beyond annotations by detailing the return structure and specifically noting that 'Names remain raw Discord data; untrusted_names provides a separately fenced copy,' which informs the agent about data trustworthiness and output nuance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two clear sections: Purpose and Returns. It front-loads the core function and then efficiently describes the return payload, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list tool with rich annotations and an output schema, the description fully covers the essential context. It explains the return shape and the special handling of untrusted names, which is sufficient 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds no parameter information, but none is needed; it instead focuses on the return format, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List Discord-provided default soundboard sounds (available globally).' This specifies the verb 'list', the resource (default soundboard sounds), and the scope ('globally'), effectively distinguishing it from sibling tools like soundboard_list_guild_sounds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through 'Discord-provided default' and 'available globally', making it clear this is for platform-wide sounds rather than guild-specific ones. However, it does not explicitly name alternative tools for guild sounds, so there is clear context but no direct exclusion or alternative mention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by specifying the permission requirement, the non-effect on existing guilds, the exact return object, and the security gating via `__confirm:true` and `MCP_DRY_RUN=false`. This provides crucial behavioral disclosure for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is composed of four short, labeled sections (Purpose, Requires, Returns, Security), each containing essential information. There is no redundant or filler text, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool, the description covers purpose, required permissions, irreversibility, return value, and security confirmation flow. With an output schema present and annotations already indicating destructiveness, the description provides all necessary contextual information for an agent to use the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all four parameters with 100% coverage, providing a baseline of 3. The description adds explanatory context about the confirmation parameter (`__confirm:true`) and the MCP_DRY_RUN setting, which is not in the schema. It does not elaborate on audit_reason, but the schema covers it, so the extra value warrants a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a Guild Template' with the clear verb 'Delete' and resource 'Guild Template', and emphasizes it is DESTRUCTIVE and IRREVERSIBLE, distinguishing it from sibling tools like templates_modify and templates_sync. This is a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the required Discord `MANAGE_GUILD` permission and clarifies that it only removes the template code, not existing guilds, which helps the agent understand the impact. It does not explicitly name alternatives or exclusion criteria, but the usage context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint), the description discloses multiple behavioral nuances: it refuses to read the guild if guild_id mismatches, raw names are isolated in untrusted_text, Discord-managed roles are excluded, and missing optional fields require manual review. These are valuable, non-obvious behaviors that the annotations do not capture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into Purpose, Safety, and Returns sections. Every sentence delivers necessary information without fluff. It is front-loaded with the core purpose and then elaborates on critical safety and return details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the existence of an output schema, the description covers all essential aspects: purpose, safety constraints, comparison scope, exclusions, and the return shape. The mention of manual review for missing fields fills a completeness gap that a simple function description would leave open.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both guild_id and template_code. The description adds some context about guild_id being the source guild and refusing mismatches, but this is largely behavioral rather than new parameter semantics. The schema already carries the load, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Detect channel and role drift between a Guild Template snapshot and its source guild before templates_sync.' It clearly differentiates from siblings like templates_sync (which performs the sync) and other template tools by emphasizing its role as a pre-sync detector.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions this tool as a precursor to templates_sync, which tells the agent when to use it. It also states 'This tool is read-only and never syncs the template,' implying templates_sync should be used when syncing is desired, and its safety notes explain when manual review is needed. This provides clear usage context relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds specific context: re-joining is a no-op, the return value structure ({joined, thread_id}), and the purpose of joining. This aligns with and enriches the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the purpose, uses bullet points for quick scanning, and every line adds value (purpose, when, when not, returns, idempotency). No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter tool with an output schema and informative annotations. The description fully covers when to use, when not to use, the return value, and idempotent behavior. It is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (thread_id is described as 'Thread to join'), so the schema already documents the parameter. The description adds no additional syntax, format, or semantic detail beyond what the schema provides, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Join the current bot user to a thread.' It clearly distinguishes from the sibling threads_add_member by specifying 'current bot user' versus adding another user. This is exactly the level of specificity needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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, including the prerequisite for receiving thread events/sending messages and naming the alternative tool threads_add_member. This gives clear decision-making guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include idempotentHint=true, and the description reinforces with 'Idempotent: repeat calls return the same DM channel id.' It also discloses the endpoint is user-scoped, does not accept audit_reason, and specifies the return payload shape. This adds significant behavioral context beyond the annotations, with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold section headers (Purpose, When to use, Idempotent, Note, Returns). The description is compact, every sentence serves a distinct purpose, and the most important information (purpose) is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description is complete. It covers the endpoint, usage context, idempotency, restrictions (no audit_reason), and return value fields. Even without the output schema, the description tells the agent exactly what to expect and how to proceed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'recipient_id' described as 'User to DM'. The description adds minimal extra meaning by mentioning 'between the bot and a user' and the return field recipient_ids, but the schema already fully documents the parameter. Baseline of 3 is appropriate as the description is not needed to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Open (or fetch) a DM channel between the bot and a user', and even includes the API endpoint. It clearly distinguishes this from sibling tools like messages_send or users_get by focusing on DM channel creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Send a private message to a user - Discord requires a DM channel id first.' This gives clear context and implies that this step is a prerequisite for sending DMs, which effectively tells the agent when this tool is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it warns that the bot loses access immediately, explains the __confirm and MCP_DRY_RUN interaction, and specifies that audit_reason is not accepted. This complements the destructiveHint annotation effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Purpose, When to use, Note, Returns). Each sentence provides essential information with no redundancy or filler. It is concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature and confirmation requirement, the description covers the necessary context: usage scenario, destructive consequence, confirmation mechanism, and return value. The output schema is referenced, and the interaction with MCP_DRY_RUN is clarified, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters well (100% coverage). The description reinforces the semantics of __confirm by explaining the dry-run behavior and confirmation requirement, adding value beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb-resource pair: 'Make the authenticated bot/user leave a guild.' It explicitly labels the operation as DESTRUCTIVE and distinguishes it from thread-leaving tools like threads_leave by targeting the guild object. This is unambiguous and differs from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly states the intended scenario: 'Decommission the bot from a guild it should no longer be in.' While it does not name alternative tools, it provides clear contextual guidance. Including a note about the user-scoped endpoint and audit_reason adds practical usage detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only basic hints (not read-only, open world), but the description adds crucial behaviors: the response includes the token and instructs to store it as a secret, webhooks_get omits the token, and untrusted_name is separately fenced. These are valuable disclosures beyond the annotations and are consistent with them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headings, concise bullet-like lines, and no filler. Every sentence earns its place: purpose, usage, exclusion, return value, security note, and token behavior are all covered without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers when to use, when not to use, return value, security handling, and relationship to webhooks_execute and webhooks_get. With complete schema coverage and an output schema present, this description leaves no significant gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive comments for all four parameters (e.g., channel_id pattern, name maxLength, avatar nullability). The description does not add input parameter details beyond the schema; its mention of 'name' relates to the response, not the parameter. Baseline of 3 applies given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new webhook attached to a channel,' which uses a specific verb and resource, clearly distinguishing this tool from webhook execution, modification, and message-sending siblings. It also adds concrete use-case context (automation endpoint) that reinforces its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('Provision an automation endpoint') and when NOT to use ('Sending one-off bot messages → messages_send'), directly naming the alternative tool. Also provides a follow-up workflow hint that the token is needed for webhooks_execute, giving clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description discloses critical behavioral quirks: the bot-auth path strips the token from the response, and `name` is raw creator-controlled data with `untrusted_name` as a fenced copy. This adds substantial context for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Purpose, When to use, Asymmetry, Returns) and every sentence adds value. It is concise yet dense with useful information, front-loading the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description provides essential contextual details about the response (token stripped, untrusted_name) and explains the key asymmetry with the token-bearing endpoint. This is complete for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description ('Webhook to fetch') and a pattern for the ID. The description does not add additional meaning 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get a webhook by id' with a specific verb and resource, and explicitly distinguishes itself from `webhooks_get_with_token` by noting the difference in token handling. This clearly differentiates it from its sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Inspect a webhook you discovered via webhooks_list_channel or webhooks_list_guild') and provides a clear alternative ('Use webhooks_get_with_token when you already hold the token and want the freshest record'). This is excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive hints, and the description adds context by outlining the return payload shape and warning that names are raw creator-controlled data fenced in human-readable responses. This provides additional transparency 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headers and concise sections. It covers purpose, usage, exclusions, and return format without unnecessary verbosity, front-loading the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Combined with the rich annotations and output schema, the description sufficiently covers the tool's purpose, selection criteria, and return format. The security note about raw data adds important contextual completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter `guild_id` is already fully described in the schema with pattern and description, and the description does not add extra parameter-level semantics beyond referencing the guild context. With 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List every webhook in a guild (across all channels)' with a specific verb and resource scope. It distinguishes from sibling `webhooks_list_channel` by explicitly noting the cross-channel scope and naming the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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, listing use cases like server-wide audit and directing to `webhooks_list_channel` for single-channel scope. This gives clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by disclosing local checkpointing, Discord reconciliation, pre-write verification checks (bot identity, allowlist, permissions, hierarchy, drift, apply lock), guarantees that it never deletes resources or grants its own permissions, and behavior on ambiguity. It also explains the resume-safe nature and duplicate-prevention mechanisms. No contradiction with annotations 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold labels (Purpose, When to use, Safety, Resume, Returns) and front-loads the purpose. It is longer than minimal, but every section adds necessary safety or workflow detail for a complex destructive tool, so the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive and multi-step nature, the description covers purpose, usage prerequisites, safety guarantees, resume semantics, and return contents. With an output schema present and 100% parameter coverage, the description leaves no critical gap 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and individual fields already have rich descriptions. The description adds workflow-level meaning by specifying 'exactly one unchanged local plan_ref or legacy plan_token', the need for exact IDs, and the MCP_DRY_RUN=false requirement, reinforcing the oneOf contract and the confirm flow in a way the schema alone does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with an explicit purpose: 'Apply a previously previewed guild_blueprint_plan safely to one explicit guild using the exact caller-owned bot.' This names a specific verb, resource, and scope, and clearly differentiates the tool from siblings like guild_blueprint_plan, guild_blueprint_compile, and guild_blueprint_evidence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section is explicit: call only after receiving approval for the approval_id, pass exactly one unchanged plan_ref or legacy plan_token, exact guild/bot IDs, set __confirm:true, and run with MCP_DRY_RUN=false. It also provides resume guidance for partial failures, making the usage conditions unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description greatly expands on this by disclosing that no Discord mutation or checkpoint is written, that deterministic plan material may persist locally, that the tool resolves bots/guilds from environment variables, fails closed on ambiguity, preserves unrelated resources, and that the token is not standalone authorization. This rich context goes far beyond annotations and fully aligns with them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with bold headers (Purpose, When to use, Safety, Returns). It is front-loaded with purpose and every section adds necessary detail. It could be slightly trimmed, but the length is justified for a complex orchestrating tool with safety considerations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage guidance, safety/behavioral details, and expected return values. Given the tool's complexity and the presence of an output schema, this is comprehensive. It also explicitly mentions verified source evidence, blueprint, bindings, dry-run ops, blockers, and plan_ref, ensuring the agent understands the full invocation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions, so the baseline is 3. The description adds meaningful param-related semantics by explaining omission behavior (e.g., 'resolves an omitted guild only from DISCORD_DEFAULT_GUILD_ID or exactly one ALLOWED_GUILDS entry') and the rule that 'Explicit values are never overwritten and must match the locked profile.' These are not in the schema and help the agent choose correct parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase 'Build, create, or design a complete Discord server' and clearly scopes the resource as a Discord guild. It distinguishes itself from siblings by explicitly positioning it as the required first step before `guild_blueprint_apply` and by contrasting it with manual chaining of template, role, channel, onboarding, AutoMod, and Components V2 tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly says this is the required first step for unqualified build/design/create server requests, provides examples, and clarifies that 'server' means Discord guild. It also tells the agent to call it immediately instead of asking clarifying questions or manually chaining other tools, giving clear guidance vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description adds critical behavior: 'DESTRUCTIVE - IRREVERSIBLE', the need for `__confirm:true` and `MCP_DRY_RUN=false` to actually delete, and the returned object shape. This attributes beyond what annotations provide, especially the dry-run interaction, which is not in 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with bold headers, bullet points, and a direct return statement. Every sentence serves a purpose, with no redundant filler. It is appropriately sized for the complexity of a destructive delete tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with annotations already covering safety flags, this description is complete: it explains purpose, when to use, when not to use (with alternative), the confirmation/dry-run requirements, and the return value. The presence of an output schema reduces need to explain returns in detail, and the description handles the crucial behavioral nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the `__confirm` parameter's role in authorizing the destructive operation and tying it to the server's `MCP_DRY_RUN` flag, going beyond the schema's parameter descriptions. It doesn't detail every parameter, but the schema already does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a custom guild emoji' with a specific verb and resource, and distinguishes from the sibling `app_emojis_delete` by explicitly mentioning application emoji use that tool. This makes the purpose unambiguous and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' (retire stale/off-brand emoji) and 'When NOT to use' (application emoji → use app_emojis_delete), naming the alternative tool. It also includes the required confirmation and dry-run conditions, giving clear guidance on when and how to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds critical behavioral details: the 3-second hard deadline, one-time-only callback, token scoping for 15 minutes, and auth characteristics. It explains side effects (message acknowledged or returned) and failure modes, going far 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings (Purpose, 3-SECOND DEADLINE, Auth, etc.) and every sentence provides distinct value. It is compact given the complexity, front-loads the purpose, and avoids redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex interaction response tool, the description covers purpose, deadline, auth, alternatives, type enum, and return values. It is fully self-contained for an agent to select and invoke it correctly, even with the rich schema and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema covers all 5 parameters, the description enriches semantics by listing all INTERACTION_RESPONSE_TYPE values (including 6,7,8 which the schema omits) and clarifying the data shape depends on type. It also elaborates on interaction_token as a scoped credential, adding context beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear, specific verb+resource: 'Send the initial response to an interaction (slash command, button, modal submit, etc.)'. It explicitly distinguishes this from follow-up interactions by naming interactions_edit_original_response and interactions_create_followup as alternatives, making it distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete usage guidance: the 3-second deadline, and if more time is needed, instructs to respond with type=5 and follow up via specific tools. It clarifies the initial callback may be sent once, giving an explicit when-to-use and when-to-defer strategy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint is true, but the description adds crucial context: irreversibility, the exact return shape `{deleted, code}`, and the explicit requirement to pass `__confirm:true` and set `MCP_DRY_RUN=false` to actually delete. This goes well beyond the annotations and equips the agent with the safety mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headers, front-loaded purpose and warning, and zero filler. Every sentence conveys necessary information for safe and correct invocation. It remains compact despite covering usage, safety, and return behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex destructive nature, the description covers purpose, when/not to use, irreversibility, confirmation requirement, and return shape. Combined with rich annotations and complete schema, there are no significant gaps for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds behavioral semantics for `__confirm` by specifying the required value and its interaction with MCP_DRY_RUN, which is not in the schema. This enhances the agent's understanding of how to activate the destructive operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Revoke a Discord invite by code.' This clearly distinguishes it from sibling invite tools like invites_create_channel or invites_get. The warning 'DESTRUCTIVE - IRREVERSIBLE' further reinforces the action's nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' and 'When NOT to use' sections provide clear context. It advises creating a new invite before deleting the old one when rotation is needed, naming an actionable alternative. This is precisely the guidance needed for an agent to decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the generic annotations (readOnlyHint=false, openWorldHint=true, etc.), the description discloses critical behavioral details: interpolation via {{step_id.path}}, step skipping via 'if' path checks, the default abort on error with continue_on_error option, max 20 steps, and no recursion. It also describes the return structure. This goes far beyond what 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headers: Purpose, When to use, When NOT to use, Step shape, Example, Returns, Limits. It front-loads the purpose and uses concise bullet-like phrasing. Every section adds necessary information, and the example is compact yet illustrative. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex meta-tool with only one top-level parameter (steps), the description covers purpose, usage criteria, step schema, interpolation, control flow (if/continue_on_error), return format, and operational limits. The presence of an output schema reduces the need to detail return values, but the description still summarizes them. It is fully complete 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage with descriptions for all properties, including default id naming. The description adds a concrete example showing interpolation and step chaining, plus clarifies 'if' path semantics ('resolves to falsy') and that args support placeholders. This adds meaningful context beyond the schema, though the schema already does substantial work, so a 4 is appropriate rather than a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific statement: 'Execute a sequence of MCP tool calls in one request.' It further clarifies the unique interpolation capability, which distinguishes this orchestration tool from all sibling tools that perform single operations. This is a specific verb+resource definition that leaves no ambiguity about what the 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('when a workflow needs ≥2 sequential calls'), when NOT to use ('parallel-safe independent calls', 'long-running batch ops'), and points to an explicit alternative ('dedicated bulk tool (Plan 7+)'). This is exemplary usage guidance covering both inclusion and exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint=true, idempotentHint=true, readOnlyHint=false, openWorldHint=true. The description adds beyond this: explains consequence (can't rejoin until unbanned), idempotence (re-banning no-op), and the dry-run/confirm gating mechanism. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold section headers, bullet lists, and no filler. Every sentence conveys essential operating information: purpose, alternatives, optional parameter, return value, idempotence, and security. Appropriate length for a destructive tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with output schema, description covers purpose, usage vs alternatives, behavioral consequences, parameter semantics, return format ({banned, user_id, guild_id}), idempotence, and security. It is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage for all five parameters, so baseline is 3. The description adds explicit semantics for delete_message_seconds ('deletes that user's recent messages' with range) and explains the __confirm parameter's role in the security flow, which adds value over the schema. Therefore 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Ban a user from a guild' (specific verb+resource), and immediately distinguishes from siblings by noting it is DESTRUCTIVE and 'user can't rejoin until unbanned.' The 'When NOT to use' section explicitly names members_kick and members_bulk_ban as alternatives, making purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear 'When to use' and 'When NOT to use' sections with explicit alternative tools (members_kick for soft-removal, members_bulk_ban for multiple users). Also states security prerequisites (ConfirmRequired, __confirm:true, MCP_DRY_RUN=false) which guide invocation. This is comprehensive usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the destructiveHint annotation by labeling the action IRREVERSIBLE, explaining the ConfirmRequired precondition, describing the DRY_RUN_PREVIEW behavior tied to MCP_DRY_RUN and __confirm, and warning against invoking it based on messages_read output. This is rich, safety-critical disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and destructiveness, then uses compact labeled sections for usage, example, return value, and security. Every sentence adds operational value without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-delete tool, the description covers purpose, alternatives, return shape, and safety gates. The presence of an output schema means return details are not the description's burden, and the security caveats make it complete for an agent to decide and execute.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all three parameters at 100%, so baseline is 3. The description adds a concrete JSON example with realistic snowflake IDs and reinforces the __confirm requirement in context, which helps correct invocation beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a single message from a Discord channel', which uniquely identifies the exact operation, scope, and verb. The 'When NOT to use' section explicitly distinguishes it from messages_bulk_delete, clarifying its position among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear use cases (removing spam/policy violations, cleaning up stale bot messages) and explicit exclusions (bulk delete with an alternative tool named, audit trail removal). This is the highest level of guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare read-only and idempotent behavior, the description adds significant context: roles are evaluated independently with @everyone, member-specific overwrites are excluded, and thread management uses MANAGE_THREADS. It also clarifies that it audits baselines rather than mutable thread state, providing real behavioral depth 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded section headers (Purpose, When to use, When NOT to use, Returns) and front-loaded with the core purpose. Every sentence serves a distinct function—definition, usage context, exclusions, or parameter behavior—with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with moderate complexity, the description covers purpose, usage scenarios, exclusions, parameter effects, and output summary. With output schema and strong annotations present, the description fully complements structured data, leaving no critical gap for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the consequence of omitting `actions` ('audit all three actions') and that selecting fewer actions reduces output, which is a behavioral nuance not fully captured in the schema's enum description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Audit which individual guild roles can view, send in, or manage one channel or thread.' It clearly defines scope and explicitly contrasts with sibling tool `permissions_explain`, making the tool's unique function unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Dedicated 'When to use' and 'When NOT to use' sections provide explicit context and alternatives. It names `permissions_explain` for member-specific access, excludes thread-state prediction, and warns against mutation, giving unambiguous guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing irreversibility ('DESTRUCTIVE - IRREVERSIBLE'), explaining the exact scope of deletion (all vs. per-emoji), and describing the return payload shape. This adds valuable context that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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, Examples, Returns). Every sentence adds value, and the use of bold headers and examples makes it scannable and useful without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature and the complexity of the scope behavior, the description is fully complete: it explains when to use/not use, provides examples, states the return format, and clarifies edge cases. The output schema exists, so return details are covered sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds crucial semantics for the 'emoji' parameter, explaining the conditional behavior when provided vs. omitted. It also gives concrete examples for both invocation modes, which is more helpful than the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Clear reactions on a message', with precise scope differentiation between clearing all reactions and clearing a specific emoji across all users. It also explicitly distinguishes from the sibling tool reactions_delete_user, making it easy to select the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 direct reference to an alternative tool (reactions_delete_user) for removing a single user's reaction. This gives unambiguous guidance for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly=false, idempotent=true), the description discloses the auth requirement (no Bot header), absence of audit_reason on token-auth routes, and the untrusted_name fenced copy for raw creator data. This adds significant behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Purpose, When to use, Restrictions, Auth, Returns) and every sentence adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations provide idempotency/destructive hints, the description covers the critical context: auth method, parameter scope, restrictions, and return value nuances. It is complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description further clarifies that only name and avatar are modifiable, and that channel_id is not accepted, adding semantic meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Update a webhook (name + avatar only) using its token, no bot auth.' It clearly differentiates from sibling webhooks_modify by stating the token-auth method and scope (name/avatar only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly states the condition (holding token but lacking guild access), and the Restrictions section points to webhooks_modify as the alternative for moving webhooks, providing clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive, and the description richly expands on behavior: it never changes Discord, rejects dangerous permissions, validates limits, and requires placeholder revalidation. This adds substantial context 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold headers (Purpose, When to use, Safety, Returns), front-loaded with the core purpose, and every sentence carries meaningful information. Size is justified for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, safety, and return values, with an output schema present. It gives a complete picture for an agent to decide and invoke the tool correctly, including prerequisites for later dry-run/apply.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though schema coverage is 100%, the description adds meaning to the 'request' parameter (natural-language server design) and clarifies the optional preferred_primary_code is only used when relevant and live-verified safe, which is beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Purpose is crystal clear: 'Turn one natural-language server request into a complete, deterministic, read-only Discord guild blueprint.' It names the specific verb+resource, describes the internal process, and explicitly distinguishes itself as the high-level entrypoint, noting it doesn't require calling templates_recommend first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use this as the high-level entrypoint for requests such as “build a professional gaming server”. A small model needs only this one call; it does not need to call templates_recommend first.' This directly guides when to use versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false), the description adds critical behavioral context: the special auth requirement (no `Authorization: Bot` header), the low-level V2 validation being `z.record`, query params being passed in the URL not body, and return behavior for `wait:true` vs otherwise.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headers and bullet-like lines. Every sentence serves a purpose: purpose, when to use, alternatives, auth caveat, required payload note, and return contract. It is appropriately sized for a complex escape-hatch tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (18 params, nested objects, special auth, low-level escape hatch), the description covers the essential context: auth constraints, query param placement, required fields, and return values. The presence of an output schema does not obviate the need for these behavioral details, and they are all included.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds vital parameter semantics beyond the schema by explaining that `wait` and `with_components` are URL query params, that at least one of `content`, `embeds`, `components`, `attachments`, or `poll` is required, and that V2 component layout validation is intentionally loose (z.record). These nuances are not inferable from the input schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Execute (send a message through) a webhook.' It further distinguishes itself with 'Low-level escape hatch' and explicitly points to `messages_send` and `components_v2_send` as alternatives, making its role among siblings unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' and 'Prefer instead' sections with named alternatives (`messages_send`, `components_v2_send`). It also states the prerequisite of holding the token, which is actionable guidance for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/cappyeo/discord-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server