Capes

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the emoji input format but says nothing about permission requirements or behavior on duplicate reactions, so it only modestly exceeds the structured data.

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

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

Two short sentences, front-loaded with the action and followed immediately by the non-obvious parameter format. No filler.

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

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

For a simple three-parameter reaction tool with no output schema, the description covers the action and the tricky emoji format. Only minor gaps remain (permissions, duplicate handling) that annotations partially offset.

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

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

Schema coverage is 67%; the emoji parameter has no schema description, but the description compensates by defining valid syntax (unicode emoji or custom name:id), which is the most error-prone input. channel_id and message_id are already documented in the schema.

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

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

States a specific verb and resource: 'React to a message.' This naturally distinguishes it from the sibling discord_remove_reaction and discord_list_reactions, though it never names an alternative to make the contrast explicit.

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

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

No when-to-use guidance, prerequisites, or routing to alternatives is given. The agent must infer from the name alone that this adds rather than removes or lists reactions.

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

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

Annotations already declare destructiveHint=true, so the danger is known. The description adds two non-obvious behavioral constraints beyond the annotations: the 14-day message-age limit and the required 'Manage Messages' permission. It omits partial-failure/irreversibility and rate-limit behavior, keeping it from a 5.

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

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

A single compact sentence with two parenthetical constraints, front-loaded with the core action. No filler; every clause carries a constraint the agent needs.

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

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

For a destructive bulk operation, the critical gotchas (batch size, 14-day window, permission requirement) are all present and the schema is fully annotated. Missing only secondary details like batching beyond 100 or partial-failure semantics, which is minor given the rich schema and annotations.

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

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

Schema description coverage is 100%, so all three parameters (reason, channel_id, message_ids) are already documented. The description's '2-100' restates the message_ids schema description rather than adding new syntax or constraints. Baseline 3 applies.

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

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

States a specific verb and resource ('Delete ... messages') plus a clear scope ('2-100 ... at once'), which implicitly distinguishes it from the single-message sibling discord_delete_message. It stops short of explicitly naming that alternative, so it's a clear purpose without full sibling differentiation.

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

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

Provides operating conditions (2-100 batch size, must be newer than 14 days, needs Manage Messages) but never frames when to choose this over discord_delete_message or discord_delete_channel. Usage is implied by 'at once' rather than instructed.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds the important permission requirement 'Needs Manage Channels,' which is not captured elsewhere. However, it does not disclose other behavioral traits such as error conditions, rate limits, or what happens to existing channels.

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

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

Two short sentences, front-loaded with purpose and then the permission requirement. Every word earns its place, with no redundancy.

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

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

For a mutation tool with 8 parameters and only 50% schema coverage, the description is too sparse. It omits usage guidance and parameter semantics, leaving the agent with gaps that structured fields only partially fill. Annotations help with safety, but the overall definition is incomplete.

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

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

The description mentions no parameters at all, despite there being 8 parameters and only 50% schema description coverage. Key parameters like name, nsfw, topic, and slowmode_seconds lack schema descriptions, and the description does nothing to compensate.

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

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

The description states a specific verb and resource: 'Create a channel in a server.' This clearly distinguishes it from read/update/delete channel siblings, though it does not explicitly differentiate from other create tools like discord_create_thread. Still, the purpose is immediately clear.

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

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

The only guidance is 'Needs Manage Channels,' which is a permission prerequisite, not when-to-use versus alternatives. There is no indication of when to choose this over discord_edit_channel or other creation tools, nor any exclusion criteria.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is partly covered. However, the description adds nothing about required permissions (Manage Channel), whether invites can be revoked, or how max_uses/temporary interact. For a mutation tool with open-world side effects, this is a notable gap.

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

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

A single, front-loaded sentence with zero redundancy. It is appropriately sized, though it is arguably too terse to be maximally useful — concision alone doesn't compensate for missing guidance.

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

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

For a 4-parameter mutation tool with no output schema, the description should at least indicate what the returned invite link is or any permission/expiry caveats. It leaves that entirely to the schema, so an agent knows the action but not its operational context.

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

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

Schema description coverage is 100%, with each parameter documented including defaults (max_age_seconds default 86400) and semantics (0 = unlimited). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (Create) and resource (invite link) with a scope qualifier (for a channel), so an agent can distinguish it from sibling tools like discord_create_channel or discord_list_invites. It stops short of naming explicit alternatives, so it lands at 4 rather than 5.

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

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

Provides no when-to-use guidance, prerequisites, or alternatives. Nothing tells the agent why it would pick create_invite over, say, create_webhook or when a channel is eligible for an invite. Only the bare purpose is implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the agent knows this is a non-destructive write to an external system. The description adds only the 'native' qualifier (vs. a message-based poll) and the answer-count range, which the schema already states; permission requirements and result behavior are unaddressed.

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

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

A single front-loaded sentence with zero filler and the key constraint in parentheses. It is tight, though arguably too sparse for a 5-parameter create tool.

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

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

With annotations covering the safety profile and no output schema required, the minimum is met, and three of five parameters are at least nominally documented. Still missing: required permissions, what the call returns (poll message), and any behavior around duration limits.

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

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

Schema coverage is 60%, so the description should compensate, but it only restates the 2-10 answer constraint already in the schema and implies the channel target. duration_hours and allow_multiselect receive no clarification in the description, leaving their semantics entirely to the partial schema.

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

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

Clear verb (Post) plus specific resource (native Discord poll) and scope (2-10 answers, in a channel). An agent can distinguish this from discord_send_message without opening the schema, though no sibling is named explicitly.

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

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

The description states what the tool does but gives no when-to-use guidance, no indication of when a regular discord_send_message is preferable, and no prerequisites or permission context. Usage must be inferred from the name alone.

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

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

Beyond the annotations (which flag a non-readOnly, non-destructive write), the description discloses two non-obvious constraints: the required Manage Roles permission and that the bot can only grant permissions it holds itself. The latter especially prevents a class of failed/incorrect invocations and is not derivable from the schema.

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

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

Two tight sentences, front-loaded with the action and followed by the operative constraints. Every clause earns its place with no padding.

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

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

For a mutation tool whose annotations already carry the safety profile, and with no output schema to explain, the description covers the critical auth/privilege constraints well. The only shortfall is that it doesn't clarify the semantics of the permissions parameter it references.

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

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

Schema coverage is moderate (67%) with color, hoist, and guild_id described inline, while name, mentionable, and permissions lack descriptions. The description adds no parameter meaning, so it neither compensates for the gap nor duplicates the schema; baseline 3 is appropriate.

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

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

States a specific verb ('Create') plus resource ('role'), so an agent immediately knows the action. It does not distinguish itself from close siblings like discord_edit_role or discord_delete_role, but the verb makes the intent unambiguous.

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

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

It gives a prerequisite ('Needs Manage Roles'), which tells the agent when the call can succeed, but offers no guidance on choosing this over sibling role tools or any exclusions. Usage is implied via the permission requirement rather than explicit selection criteria.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds the lifecycle context (what to use instead for edit/delete) but says nothing about required permissions, forum-vs-text channel constraints, or side effects of starting a thread on a message.

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

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

One dense sentence front-loads the verb and the three modes, followed by a short routing sentence. No filler, every clause carries information.

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

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

For a 7-parameter non-destructive write with no output schema, the description covers the main decision points and the lifecycle alternatives. Gaps remain around auto_archive_minutes semantics and channel-type restrictions, but the essential call-shaping context is present.

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

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

With 71% schema coverage the description adds real value by tying the creation modes to specific parameters: message_id for message-anchored threads and content for forum posts. It does not explain auto_archive_minutes or the private flag's restriction, which are only partly covered by the schema.

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

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

States a specific verb and resource ('Create a thread') and enumerates the three distinct creation modes (from message_id, standalone, forum post). It also routes lifecycle operations to the correct siblings by name, so an agent can distinguish it from discord_create_channel or discord_edit_channel without opening a schema.

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

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

Explicitly names the alternative tools for editing, archiving, and deleting threads, which is strong routing guidance. However, it never states the conditions for choosing between the three creation modes (message-based vs standalone vs forum), leaving that inference to the caller.

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

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

Annotations already flag a non-read-only, non-destructive, open-world operation, but the description adds real value beyond them: the return shape ('Returns its ID only'), the required Manage Webhooks permission, and the recommended next tool. It doesn't mention rate limits or whether the returned token is exposed, which would push it higher.

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

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

Three compact clauses, zero filler, with the core action front-loaded and the follow-up tool and permission requirement ordered by importance. Every sentence carries distinct information.

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

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

For a two-parameter creation tool with no output schema, the description covers the action, the return value, the permission prerequisite, and the natural next step. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 50%: channel_id carries a description including the thread-ID allowance, while name is undocumented. The phrase 'in a channel' confirms channel_id's role as the target, but the description adds no syntax or constraint detail (e.g., the 80-character name limit) beyond the schema. The undescribed parameter is trivially inferable from the verb, so this lands at baseline rather than below.

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

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

States a specific verb and resource ('Create a webhook in a channel') and immediately distinguishes the tool's role from its closest sibling by naming discord_send_webhook_message as the posting path. An agent can tell it apart from discord_list_webhooks and discord_delete_webhook without opening any schema.

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

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

Explicitly routes the follow-up action ('use discord_send_webhook_message to post through it') and states the permission prerequisite ('Needs Manage Webhooks'). It stops short of a full when/when-not clause (e.g., when to prefer an incoming webhook over a bot message), so it's clear context rather than complete routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description only needs to add specifics. 'Permanently' and 'This cannot be undone' add real weight by making clear that content is irrecoverable, which is stronger than the generic destructive flag, though it says nothing about permissions or what happens to the channel's messages.

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

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

Two short sentences with the irreversible warning front-loaded. Nothing extraneous or repetitive.

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

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

For a two-parameter delete tool with full schema coverage and annotations carrying the safety profile, the description covers action, scope, and irreversibility. It could still note permission requirements or the fate of the channel's contents, but nothing essential for invocation is missing.

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

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

Schema description coverage is 100%, with channel_id's ID pattern/thread note and the 'reason' audit-log purpose fully documented. The description adds no parameter detail, so baseline 3 applies.

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

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

States a specific verb ('delete') and resource ('channel or thread') plus the permanence qualifier. The 'channel or thread' scope clearly separates it from discord_delete_message, discord_delete_role, and other delete siblings.

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

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

No when-to-use guidance versus alternatives such as discord_edit_channel (to modify rather than remove) or discord_delete_message. No mention of required permissions (e.g., Manage Channels) or preconditions before calling.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the destructive nature is covered structurally. The description is consistent with these hints but adds little behavioral context beyond the action itself - no mention of required permissions, irreversibility, or what happens if no matching overwrite exists.

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

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

A single front-loaded sentence with no filler. Every word earns its place and the action is stated immediately.

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

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

For a destructive mutation with no output schema, the description is minimally adequate but thin. Annotations carry the safety profile, yet the description omits permission requirements and the delete-vs-null distinction, leaving notable gaps.

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

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

Schema description coverage is 100%, so target_id ('Role ID or user ID') and channel_id ('Channel ID (a thread ID also works)') are already documented. The description's mention of 'role's or member's' echoes the schema without adding format or edge-case detail, so baseline 3 is appropriate.

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

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

States a specific verb (remove) and resource (role's or member's permission overwrite) scoped to a channel. This clearly distinguishes it from siblings like discord_set_channel_permission and discord_delete_channel. It does not, however, explicitly name those siblings to route the agent.

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

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

No when-to-use guidance and no alternatives named. In particular it never clarifies the distinction from discord_set_channel_permission (setting an overwrite to null) versus deleting the overwrite entirely, which is the ambiguity an agent most needs resolved.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds genuinely new behavioral context by spelling out the required permissions, which the annotations do not convey. It omits, however, whether the invite is immediately invalidated or that the audit-log reason is recorded.

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

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

Two short sentences, with the action front-loaded and the permission constraint following. No filler or redundancy.

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

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

For a simple two-parameter mutation with no output schema, the essentials (action, permissions) are present, but the undocumented 'code' parameter and the absence of any note on where to obtain an invite code leave a meaningful gap in what an agent needs to call it correctly.

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

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

Schema description coverage is only 50%: 'reason' is documented in the schema, while 'code' has just a pattern and no description. The description adds nothing about either parameter, not even clarifying that 'code' is the invite code obtainable from an invite URL or discord_list_invites, so the coverage gap is left unfilled.

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

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

States a specific verb and resource ('Revoke an invite link'), which an agent can trivially distinguish from discord_create_invite and discord_list_invites. It does not name any sibling explicitly, so it stops short of the strongest possible routing signal, but the operation itself is unambiguous.

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

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

The description gives a precondition (Manage Server, or Manage Channels for that channel) but never says when to reach for this tool versus alternatives such as discord_list_invites (to find the code) or other invite-management tools. Usage is implied by the verb rather than stated.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds real value by disclosing the permission requirement and that it applies specifically to other people's messages, but says nothing about irreversibility or the audit-log effect of the reason field.

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

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

Two short sentences, no filler, with the action stated first and the permission caveat second. Every sentence earns its place.

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

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

Adequate for a small three-parameter destructive tool: the permission requirement and the optional audit-log reason are covered, and no output schema is needed. It is still thin on irreversibility guarantees and on how it relates to the bulk-delete sibling.

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

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

Schema description coverage is 100%, with all three parameters documented in-schema, so baseline 3 applies. The description adds no extra parameter meaning, for example how channel_id differs for threads or how reason surfaces in the audit log.

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

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

States a specific verb and resource (delete a message) that is unambiguous. It does not distinguish itself from the close sibling discord_bulk_delete_messages or discord_edit_message, so a clear-but-undifferentiated 4 is right.

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

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

Gives one concrete precondition (Manage Messages permission for deleting other people's messages), which is implied usage guidance rather than explicit when-to-use instruction. It never names the alternative (discord_bulk_delete_messages) for deleting several messages at once.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally; the description's 'permanently' reinforces irreversibility but adds little else. It omits the important behavioral consequence that members holding the role lose it, and any permission requirements for the caller.

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

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

A single four-word sentence that front-loads the verb and resource with zero filler. Nothing could be trimmed without losing meaning.

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

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

The tool is a destructive, open-world mutation with no output schema, so the description should ideally state the permission requirement and the side effect on role holders. Annotations cover the safety hint, which keeps this at a minimum-viable 3 rather than lower.

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

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

Schema description coverage is 100%, so role_id, guild_id, and the optional audit-log reason are all documented in the schema itself. The description adds no syntax, format, or constraint detail 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.

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

The description gives a specific verb+resource ('Delete a role') with the 'permanently' qualifier, which cleanly separates it from discord_create_role and discord_edit_role in the sibling list. It stops short of explicitly naming those alternatives, but the operation is unmistakable.

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

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

There is no guidance on when to use this tool versus discord_edit_role or discord_member_role, and no prerequisites mentioned (e.g., needing Manage Roles permission or the role not being managed by an integration). The agent must infer everything from the name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them by stressing 'permanently' (irreversibility) and stating the required permission (Manage Webhooks), which the annotations do not convey.

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

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

Two terse sentences with zero filler; the action and its permanence are front-loaded and the permission note follows. Every phrase earns its place.

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

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

For a single-parameter destructive tool with no output schema, the description plus annotations and full schema coverage give an agent everything needed to call it correctly. Only the lack of any when-to-use context keeps it just short of fully complete.

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

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

Schema description coverage is 100%, so both parameters (webhook_id and reason) are already documented in the schema. The description adds no parameter-level detail, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource — 'Delete a webhook' — with the 'permanently' qualifier making the operation unambiguous. It does not explicitly name or differentiate itself from the webhook siblings (list/create/send), but the destructive action is clear enough to select without opening the schema.

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

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

'Needs Manage Webhooks' gives the prerequisite for use, which is useful context. However, there is no explicit when-to-use guidance or mention of alternatives such as discord_list_webhooks for auditing before deletion; usage is largely implied by the tool name.

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

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

Annotations establish the mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds the real value: required permissions and the thread/channel distinction for archive/lock. It does not describe reversibility or return behavior, but the auth context is a meaningful addition.

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

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

Two tight sentences: the action and field list are front-loaded, and the permission requirement follows. No filler and every clause carries information.

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

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

For a 10-parameter mutation tool with no output schema, the description covers purpose, editable fields, thread-specific caveats, and permissions. It leaves a few parameters and the partial-update/return behavior unaddressed, but no output schema means return values need not be explained.

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

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

Schema coverage is only 50%, with several params (name, nsfw, topic, position, slowmode_seconds) lacking schema descriptions. The description compensates by naming the editable properties (rename, topic, move, slowmode, archive, lock), giving semantic orientation. It omits nsfw, position, and auto_archive_minutes, so it does not fully close the coverage gap.

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

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

States a specific verb (Edit) and resource (channel or thread), then enumerates the mutable fields (rename, topic, move, slowmode; archive/lock for threads). This clearly separates it from siblings like discord_create_channel, discord_delete_channel, and discord_set_channel_permission without needing to open any schema.

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

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

Provides the operative prerequisite (Manage Channels, or Manage Threads for threads) and notes thread-only operations, which tells the agent when the call will succeed. It stops short of explicitly naming alternative tools for non-edit operations, but the context is clear enough for invocation.

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

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

Annotations only declare the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false). The description adds the ownership constraint that the bot may only edit its own messages, which is genuine behavioral context not captured by the annotations, though it omits replace-vs-merge edit semantics.

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

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

Two short sentences with zero filler, and the core action is front-loaded ahead of the constraint. Nothing is wasted or redundant.

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

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

It is a mutation tool with no output schema and a nested embed parameter, yet the description does not explain edit semantics (e.g., whether omitted fields are cleared, whether embed replaces content) or what the result contains. The annotations cover safety, but an agent still lacks enough to call it confidently in edge cases.

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

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

Schema coverage is 80% and the description adds no parameter-level detail (nothing about content vs embed precedence, mentions behavior, or IDs). With the schema doing most of the work, the baseline 3 applies.

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

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

States a specific verb+resource ('Edit a message'), which is distinct from the read/send/delete siblings. It stops short of any explicit sibling differentiation or naming of which fields can be changed, so it is clear but not routing-grade.

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

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

It supplies one meaningful precondition ('Discord only lets the bot edit its own messages'), which is real usage guidance. However, there is no when-to-use/when-not framing and no reference to alternatives like discord_send_message or discord_delete_message, leaving routing implied.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, which understates the risk. The description usefully discloses the non-obvious replace semantics of the permissions field, which the annotations do not capture. It still omits any note on required bot permissions or reversibility.

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

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

Two short sentences, no filler, and the highest-value warning about permissions replacement is placed right after the purpose statement so it is read before the agent fills in arguments.

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

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

For a 7-parameter mutation tool with no output schema and partial schema coverage, the core pitfall is covered but permission requirements, partial-update behavior for name/color/hoist, and error cases are not. Adequate but with visible gaps.

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

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

Schema coverage is 57%, with name/hoist/mentionable having no descriptions. The description compensates on the most consequential parameter by explaining that permissions replaces the full set rather than merging, but leaves the remaining parameters' semantics to the schema.

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

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

States a specific verb and resource ('Edit a role'), which is clearly distinct from non-role tools. It does not, however, differentiate from the close siblings discord_create_role and discord_delete_role, so an agent gets no help choosing among role-mutation operations.

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

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

No guidance on when to use this versus discord_create_role, discord_delete_role, or discord_member_role, and no prerequisites (e.g. needing the MANAGE_ROLES permission) are mentioned. The only implicit signal is that the role must already exist.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-redundant context: reverse-chronological ordering ('newest first') and the required 'View Audit Log' permission. It stops short of describing pagination or rate-limit behavior.

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

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

Two short sentences with zero filler, front-loading the resource and the access requirement. Every clause earns its place.

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

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

For a read-only tool with full schema coverage and read annotations, the description covers what it is, ordering, and the permission gate. Nothing critical is missing, though a note on default result size or pagination would round it out.

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

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

Schema coverage is 100%, so limit, user_id, guild_id, and action_type are all documented in the schema. The description adds only the ordering hint (newest first) and does not clarify the audit-log action-type numbering, so it sits at the baseline for a fully documented schema.

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

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

States a specific verb and resource ('Read a server's audit log') and adds scope detail ('who changed what') plus ordering ('newest first'). No sibling tool covers audit logs, so an agent can distinguish it cleanly from the many other read/list tools.

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

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

The description tells the agent the prerequisite ('Needs View Audit Log') but gives no explicit when-to-use framing or comparison against alternatives. Usage is only implied by the resource itself, which is a clear but minimal guideline.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds one useful behavioral fact – that permission overwrites are resolved to human-readable permission names – but says nothing about error cases (invalid/unknown channel) or what a thread lookup returns versus a channel.

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

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

One tightly worded sentence with the resource and the notable return detail front-loaded; nothing is wasted. It is perhaps slightly terse given the ambiguity with discord_read_channel, but structurally efficient.

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

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

For a read-only single-parameter lookup with safety annotations, the description covers what is fetched and one notable return field. No output schema exists and none is strictly required, though the overlap with discord_read_channel remains an unresolved gap.

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

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

Schema description coverage is 100% and the lone channel_id parameter is fully documented there, including the note that a thread ID works. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

Specific verb ('Get') and resource ('channel or thread'), plus a distinctive return detail ('permission overwrites translated to permission names') that separates it from generic channel reads. However, it does not differentiate from the sibling discord_read_channel, which appears to overlap, leaving the agent to guess which to call.

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

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

No when-to-use guidance, no prerequisites (e.g. required bot permissions), and no mention of the apparently overlapping discord_read_channel sibling. The agent must infer the choice entirely.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — it doesn't say what fields 'details' returns, whether it can fail for inaccessible guilds, or anything about rate limits.

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

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

A single short sentence with no waste and the key operation front-loaded. It is economical, though arguably too terse for the information it could convey.

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

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

With annotations covering the read-only/open-world profile and the schema fully documenting the one parameter, the minimum is met. But with no output schema, the description should hint at what 'details' comprise, and it does not.

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

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

Schema description coverage is 100% with a single guild_id parameter that is fully documented including a regex pattern in the schema. Description adds no param detail, which is acceptable but earns only the baseline.

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

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

States a specific verb (get) and resource (Discord server/guild), and the parenthetical equivalence of 'server' to 'guild' is mildly helpful. However it does not distinguish this from sibling discord_list_guilds or discord_get_channel, so an agent must infer the boundary.

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

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

No guidance on when to use this versus discord_list_guilds or discord_get_channel, and no prerequisites or context stated. The agent is left to infer usage purely from the name and description.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the name - no return shape, no error behavior (e.g., missing message), no cross-channel caveat even though 'channel_id' is required.

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

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

One front-loaded sentence with zero waste, but it is arguably too sparse for a tool that requires a channel context the description never mentions. Efficient, if minimal.

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

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

A simple read-only tool with full schema coverage and annotations covering safety, so the description is minimally adequate. It omits any note about the required channel context or what the returned message contains.

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

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

Schema description coverage is 100%, including the useful note that a thread ID works for channel_id, so the schema carries parameter meaning. The description adds nothing beyond it, making the baseline 3 appropriate.

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

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

States a specific verb (read) and resource (one message), which distinguishes it from list-style siblings like discord_read_channel and discord_list_pins. However it offers no explicit sibling differentiation or scope detail beyond the schema fields.

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

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

No when-to-use guidance, no mention of when to prefer discord_read_channel/discord_list_pins over this tool, and no prerequisites. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and open-world profile is covered structurally. The description usefully adds that categories, voice and forums are all included and that omission of guild_id broadens scope to all guilds, but says nothing about pagination, result limits, or required bot permissions.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the one behavioral caveat. Nothing is redundant or padded.

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

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

For a simple read-only list tool with no output schema and a single fully documented parameter, the description covers what is needed to invoke it correctly. The only gap is the shape of the returned channel list (fields, ordering), which is minor for this tool type.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning the schema cannot: the parameter is optional and omitting it changes the query from one guild to all guilds. That is real semantic value beyond the schema's bare 'Server (guild) ID'.

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

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

The description states a specific verb and resource ('List channels') and adds scope detail ('all types, including categories, voice and forums'). It implicitly separates itself from discord_list_guilds via the 'every server the bot is in' note, though it never names a sibling explicitly.

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

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

It gives one concrete usage rule ('Omit guild_id to list every server the bot is in'), which is genuine conditional guidance. However, it names no alternatives (e.g. discord_get_channel for a single channel, discord_list_guilds for servers), so the agent must infer when this tool is preferable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds nothing beyond that core statement: no return format, ordering, pagination, or permission context. It effectively restates the name without enriching behavioral understanding.

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

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

A single front-loaded sentence with zero padding; nothing redundant. It is efficient, though arguably too terse to carry much value.

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

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

For a simple one-parameter read with no output schema and annotations covering the safety profile, the description is minimally adequate. It doesn't explain what a 'tag' contains or the shape of the returned list, but that omission is minor given the tool's simplicity.

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

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

Schema description coverage is 100% ('Channel ID (a thread ID also works)'), so the parameter is fully documented by the schema. The description adds no additional meaning about channel_id, making the baseline 3 appropriate.

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

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

The description states a specific verb ('List') and resource ('tags of a forum channel'), so the operation is unambiguous. It implicitly contrasts with the sibling discord_manage_forum_tag (management vs. listing) but never names or distinguishes it explicitly, keeping this short of a 5.

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

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

There is no when-to-use, no prerequisites, and no reference to the obvious alternative (discord_manage_forum_tag) for creating/editing/deleting tags. Usage is only implied by the verb 'List', leaving the agent to infer the read-only listing scenario.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds one piece of meaningful context—the list is scoped to servers the bot is in, not all servers—but says nothing about pagination or return shape.

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

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

A single well-formed sentence with zero filler, front-loading the verb and resource.

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

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

For a zero-parameter list tool whose annotations already convey the read-only, open-world nature, the description is essentially complete. Only minor details (pagination, return fields) are absent, and no output schema exists to cover them.

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

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

The tool takes zero parameters, so the schema has nothing to explain and the baseline is 4. There are no parameter semantics for the description to clarify.

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

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

The description states a specific verb ('List') and resource ('Discord servers'), making the operation unambiguous. It distinguishes from single-resource siblings like discord_get_guild by the plural 'servers', though it does not name alternatives explicitly.

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

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

Usage is implied—an agent would use this to enumerate the bot's guilds—but no explicit when-to-use or when-not guidance is given, nor are alternatives like discord_get_guild mentioned.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds a genuinely useful trait beyond the annotations: the required 'Manage Server' permission, which an agent must verify before invoking. It still omits return shape/pagination, but with annotations present this is a solid addition.

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

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

Two terse sentences, with the core action front-loaded and the permission constraint second. No filler or redundancy.

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

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

For a single-parameter read-only list tool with full schema documentation and annotations, the description covers purpose and the key prerequisite. No output schema exists, but 'active invites' conveys the return subject adequately; only return formatting/pagination is left unstated.

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

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

Schema coverage is 100% and there is a single required guild_id parameter fully documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List a server's active invites') with a scope qualifier ('active') that narrows the result set. The 'list' verb naturally contrasts with the create/delete invite siblings, but the description never names or routes to them, so differentiation is implicit rather than explicit.

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

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

Usage is implied by the verb and the stated prerequisite ('Needs Manage Server'), which tells the agent when it is even permitted to call the tool. However, there is no explicit guidance on when to prefer this over discord_create_invite or discord_delete_invite, nor any exclusions.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), so the burden is lighter. The description still adds non-obvious operational context that annotations cannot express: the call fails unless the Server Members Intent is toggled on, which is a genuine prerequisite an agent must know before invoking.

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

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

Two short sentences with zero filler; the primary purpose is front-loaded and the prerequisite follows. Nothing is repeated from the title or schema.

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

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

For a read-only, three-parameter tool with full schema coverage and no output schema, the definition covers purpose, the optional filter, and the operational prerequisite. Only the shape of returned member records and paging beyond `limit` are unaddressed, which is minor given the schema.

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

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

Schema description coverage is 100%, so `guild_id`, `limit` (1-1000, default 50) and `query` (username/nickname prefix) are already documented. The description only restates that `query` enables name search, adding no format or matching-behavior detail beyond the schema. Baseline 3 for high-coverage schemas.

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

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

The description gives a specific verb ('List') and resource ('server members') and adds a second retrieval mode, search by name via `query`. It clearly separates this from write-oriented siblings like discord_moderate_member or discord_member_role, though it doesn't explicitly name a sibling to route against.

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

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

It states a real prerequisite — 'Server Members Intent' must be enabled in the Developer Portal — which tells the agent when the call will fail. However there is no guidance on choosing between this and, say, searching members another way, and no mention of pagination or result caps beyond the schema default.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that — no mention of pagination, pin ordering, permission requirements, or Discord's 50-pin cap per channel. It carries no additional disclosure.

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

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

A single, front-loaded sentence with no wasted words. It is efficient, though the extreme brevity is part of the incompleteness rather than exemplary conciseness.

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

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

For a simple read-only list tool with full schema coverage and no output schema, the description is minimally adequate. It does not tell the agent anything about return shape or limitations (e.g., pin cap, ordering), which would help an agent use the result correctly.

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

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

Schema description coverage is 100%, and the single channel_id parameter is fully documented in the schema, including the pattern and the useful note that a thread ID also works. The description adds nothing 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.

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

States a specific verb ('List') and resource ('pinned messages in a channel'), so the operation is immediately clear. However, it does not differentiate itself from siblings like discord_pin_message, discord_get_message, or discord_read_channel, which an agent must disambiguate from the name alone.

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

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

The description is purely a purpose statement with no when-to-use guidance, no exclusions, and no mention of alternatives such as discord_get_message when a specific pin is needed. Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that the result is the set of reacting users for a single emoji, which is useful because there is no output schema, but it omits pagination behavior and whether the caller's own reactions are included.

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

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

A single well-formed sentence that front-loads the operation and its scope. Nothing is redundant and no filler is present.

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

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

For a 4-parameter read tool with no annotations gaps and no output schema, the description covers the core intent and emoji format, but leaves the limit parameter and the ordering/pagination of returned users unaddressed, which an agent may need to call it correctly.

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

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

Schema coverage is 50%: channel_id and message_id are described in-schema, while emoji and limit are not. The description compensates for emoji by specifying accepted formats ('unicode or name:id'), but leaves the limit parameter's behavior (max users returned, ordering) entirely unexplained.

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

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

The description states a specific verb ('List'), resource ('the users who reacted to a message'), and the scoping constraint ('with one emoji'), which clearly separates it from mutation siblings like discord_add_reaction and discord_remove_reaction. It is clear but never explicitly differentiates itself from those siblings in text.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites (e.g., permissions to view reactions), and no guidance on the 'limit' parameter or pagination. The agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that each role is returned with its permissions, but omits behavioral details such as pagination, ordering, or whether elevated permissions are required to read role data.

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

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

A single, front-loaded sentence with no filler. The verb, resource, and return content are all stated economically.

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

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

For a simple single-parameter read tool with annotations covering safety and a fully documented schema, the description is nearly complete. It notes the return content ('with their permissions'), though it could mention result ordering or that the list may be large.

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

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

Schema coverage is 100% and the single guild_id parameter is fully documented in the schema with a format pattern. The description's 'a server's roles' loosely maps to guild_id but adds no syntax or format 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.

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

States a specific verb+resource ('List a server's roles') and adds what is returned ('with their permissions'), which cleanly separates it from the create/edit/delete role siblings. It does not explicitly name an alternative, but the 'list' verb makes the intent unambiguous.

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

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

No explicit when-to-use guidance or alternatives are given. An agent must infer that this is the read-side counterpart to discord_create_role/discord_edit_role, and nothing tells it when to prefer this over discord_get_guild, which may also surface role data.

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

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

The readOnlyHint/openWorldHint annotations already declare this as a safe, externally-scoped read. The description adds the meaningful behavioral fact that results differ by mode, but says nothing about pagination, limits, or which thread types (private/archived-private) are excluded.

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

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

One sentence, front-loaded with the primary action (list active threads) and the conditional variant second. No filler, nothing to trim.

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

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

For a two-optional-param read tool with annotations covering safety and no output schema, both usage branches are explained. Only pagination/result-size behavior is unaddressed, which is minor.

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

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

Schema description coverage is 100%, and the schema already documents channel_id as the archived-threads selector, so the description mostly mirrors that. It reinforces the mode switch but adds no format, ordering, or default details beyond the schema.

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

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

States a specific verb (list) and resource (threads) and clearly separates two modes: active threads server-wide vs. archived public threads of one channel. No sibling is named, but no other tool in the list lists threads, so ambiguity is low.

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

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

Gives a clear context rule: omit channel_id for active threads across the server, supply it for archived public threads in that channel. It does not state exclusions or point to alternative tools (e.g., discord_create_thread, discord_thread_member), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds two genuinely useful behavioral facts that structured data does not cover: tokens are never returned (important output-privacy trait) and the call requires the Manage Webhooks permission. It stops short of describing result contents or ordering.

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

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

Three short, front-loaded sentences with zero filler: purpose first, then the security behavior, then the permission requirement. Every clause earns its place.

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

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

For a two-parameter read tool the description covers purpose, privacy behavior, and permissions, but with no output schema and no return-format hint, an agent still doesn't know what fields a listed webhook contains. Adequate but leaves a modest gap.

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

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

Schema coverage is 100%, so guild_id and channel_id are already fully documented in the schema. The description only alludes to the channel/server dual scope without naming which parameter drives it, so it adds little beyond the schema baseline.

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

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

States a specific verb (List) and resource (webhooks) with the scoping modes it supports (channel or whole server). An agent can immediately distinguish it from the create/send/delete webhook siblings without opening any schema.

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

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

The phrase 'of a channel or of a whole server' implies the two usage modes and loosely maps them to the two parameters, but it never explicitly states when to pick channel scope vs guild scope. No alternatives or exclusions are given, so guidance remains implied rather than stated.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the bar is lower; the description still adds real value by naming the auth requirement (Manage Channels) and the cascading effect that removing a tag strips it from posts that use it. It does not describe idempotency or failure behavior.

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

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

Three short sentences, front-loaded with the action set, followed by prerequisite and side effect. No filler.

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

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

For a mutation tool with no output schema, the description covers purpose, permission requirement, and destructive side effect, and annotations cover the safety profile. Minor gaps remain around success/failure response shape and whether tag_id alone suffices for removal (left to the schema).

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

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

Schema description coverage is 83%, so parameters are largely self-documented; the description restates the three actions but adds no format or conditional detail beyond the schema's own per-parameter notes. Baseline 3 is appropriate.

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

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

States a specific verb set (add, rename, remove) and resource (tag on a forum channel), matching the action enum exactly. An agent can distinguish it from discord_list_forum_tags without opening either schema.

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

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

Explicitly states the required permission (Manage Channels), which tells the agent when the call will succeed. However, it names no alternative tool or when-not-to-use condition (e.g. listing tags vs. mutating them).

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

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

Annotations already declare this is a non-read-only, non-destructive, open-world mutation, so the safety profile is covered structurally. The description adds a genuinely useful hierarchy precondition, but says nothing about reversibility, idempotency, or failure modes when the role outranks the bot.

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

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

Two short sentences, zero filler, with the core action stated first and the constraint second. Every sentence earns its place.

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

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

For a four-required-parameter mutation with no output schema, the description covers the operation and the key role-hierarchy constraint. However, it omits permission requirements, error behavior, and any indication of what the call returns, leaving gaps an agent would want closed.

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

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

Schema coverage is 75% with role_id, user_id and guild_id documented inline and action constrained by an add/remove enum. The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: assign or remove a role from a member, which is clearly distinct from sibling role-management tools like discord_create_role, discord_edit_role and discord_delete_role. It does not name those siblings explicitly, but the assign/unassign scope is unambiguous.

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

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

Usage is implied by the verb pair (add vs remove via the action parameter), and one real precondition is given: the role must sit below the bot's highest role. There is no explicit when-to-use vs alternatives guidance and no mention of required permissions such as Manage Roles.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false, openWorldHint=true, but the description adds real value on top: required Discord permissions, the human-confirmation protocol, and the semantic meaning of timeout ("mute for N minutes"). It stops short of covering reversibility of ban vs kick or rate-limit/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.

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

Two tightly packed sentences: the capability list leads, and the permission/confirmation constraints follow. Every clause carries information; nothing is padded.

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

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

For a 6-parameter destructive mutation with no output schema, the definition covers actions, permissions, and the safety protocol, and the schema fills in per-parameter bounds and units. It omits what a successful call returns or whether bans are reversible, but that gap is minor given the annotation coverage.

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

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

Schema description coverage is 83%, so the schema already documents user_id, guild_id, reason, timeout_minutes and delete_message_seconds. The description only slightly enriches the action enum by clarifying that "timeout" means mute for N minutes, which is a marginal addition to what the enum and schema already convey.

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

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

Names a specific verb (moderate) and resource (member), then enumerates every supported action: kick, ban, unban, timeout, untimeout. No sibling tool in the list performs member moderation, and an agent can tell instantly what this tool covers.

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

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

Provides explicit prerequisites ("Needs Kick/Ban/Moderate Members") and a strong usage rule ("Destructive: confirm with the user first"). It does not name when-not to use it or point at an alternative, but no sibling overlaps this capability, so the guidance is nearly complete.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful auth context: the Pin Messages permission is required and was split from Manage Messages. It does not describe the return shape or idempotency, but the permission note is real added value beyond the structured fields.

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

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

Two tightly written sentences with zero waste; the primary behavior and its default are front-loaded, and the permission caveat follows logically.

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

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

For a mutation tool with no output schema, the definition covers the key agent needs: what it does, the default direction, and the required permission. Return format and idempotency are unstated, but annotations already carry the safety profile, so the gap is minor.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including 'Set true to unpin'. The description reinforces that pinning is the default, which is a minor clarification rather than net-new meaning; baseline 3 applies when the schema does the heavy lifting.

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

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

States a clear verb+resource ('Pin ... a message') and covers both directions of the operation, distinguishing pin from unpin via the stated default. It does not name the read-side sibling (discord_list_pins), so sibling differentiation is left implicit.

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

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

Usage is implied by the verb: use it to pin or unpin a message. There is no explicit when-to-use vs alternatives or when-not guidance, and the adjacent read tool discord_list_pins is not referenced.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one behavioral detail ('newest first' ordering), but says nothing about pagination via 'before', default limits, or return format.

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

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

A single well-formed sentence, front-loaded with verb and resource, with the useful ordering qualifier in parentheses. Nothing is wasted.

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

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

For a simple read with safe annotations this is nearly adequate, but with no output schema the description could disclose what a returned message looks like or how paging works. It covers the essentials but leaves the return shape implicit.

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

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

Schema description coverage is 100%, so limit, before, and channel_id are fully documented in the schema, including the note that a thread ID works for channel_id. The description adds only the ordering of results, so baseline 3 applies.

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

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

The description states a specific verb ('Read') and resource ('recent messages') with scope ('a channel or thread') and ordering ('newest first'). It implicitly separates itself from siblings like discord_read_dm (DMs) and discord_get_message (single message), though it never names them.

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

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

Usage is implied by 'read recent messages from a channel or thread,' but there is no explicit when-to-use, when-not, or alternative (e.g., discord_read_dm for DMs, discord_get_message for a single message). An agent must infer the routing itself.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds the 'between the bot and a user' visibility boundary and the 'newest first' ordering, but says nothing about pagination, default window size, or the behavior when no DMs exist.

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

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

One sentence, front-loaded with the verb and resource, with the ordering qualifier parenthesized at the end. No filler, nothing wasted.

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

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

For a read-only tool with annotation-covered safety and no output schema, the description conveys what is returned (recent DMs, newest first) but leaves the read window, limit default, and pagination behavior unspecified, which matters given the undocumented limit parameter.

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

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

Schema description coverage is only 50%: user_id has a description, while limit (1–100) is undocumented in the schema. The description clarifies whose DMs are returned (the bot's, for a given user) and implies recency ordering, but never explains limit's default or how it interacts with 'recent'. Partial compensation only.

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

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

The description states a specific verb (read), a specific resource (direct messages between the bot and a user) and a scope (recent, newest first), which cleanly separates it from channel-reading siblings like discord_read_channel. It doesn't name an alternative sibling explicitly, but the 'direct messages between the bot and a user' phrasing makes the target unambiguous.

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

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

There is no explicit guidance on when to pick this over discord_read_channel, discord_get_message, or discord_send_dm — the DM-vs-channel distinction is left to inference from the resource noun. No mention of prerequisites (e.g. bot must share a DM with the user) or exclusions.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely useful info beyond that: the Manage Messages authorization requirement for removing other users' reactions. It does not explain irreversibility or the response, but the auth requirement is a meaningful addition.

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

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

One sentence covers all three modes plus the permission caveat, with the modes front-loaded and no filler. Every clause earns its place.

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

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

For a destructive, no-output-schema mutation tool the description covers the full set of behaviors and the key authorization constraint. It omits secondary details (reversibility, channel/thread nuances already in schema) but nothing critical to correct invocation is missing.

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

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

Schema coverage is 100%, so every parameter is already documented — including that emoji is not needed with clear_all and that user_id targets another user's reaction. The description's parameter mapping largely restates the schema, so it earns the baseline rather than more.

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

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

Names the specific verb (remove) and resource (reaction) and enumerates the three distinct modes — the bot's reaction, another user's via user_id, or all via clear_all. It is clearly separable from its siblings discord_add_reaction and discord_list_reactions.

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

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

Explains which mode each parameter selects and states the prerequisite for the privileged path ('Removing others' reactions needs Manage Messages'). No explicit when-not guidance or alternative routing, but the condition for the restricted operation is clear.

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

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

Annotations already declare this is a non-destructive, non-read-only, open-world operation. The description adds genuinely new behavioral context beyond that: the recipient-side constraints for delivery to succeed and the guarantee that the message never pings anyone. Return format is not described, but no output schema exists.

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

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

Three short sentences, front-loaded with the action, then constraints, then a behavioral guarantee. No filler and every clause carries information.

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

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

For a 3-parameter mutation tool with no output schema, the description covers the key delivery constraints and the no-ping behavior. It omits what the call returns and whether content or embed is required, which are minor gaps against the schema's coverage.

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

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

Schema coverage is 67%, and the description adds no parameter-level detail at all. The 'never pings' note indirectly touches content behavior, but it does not clarify the required user_id, the 2000-char content limit, or the embed object beyond what the schema already documents.

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

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

States a specific verb (send) and resource (direct message) with an explicit recipient scope (to a user), which inherently distinguishes it from channel-oriented siblings like discord_send_message and from discord_read_dm. An agent can select it without opening the schema.

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

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

Gives concrete prerequisites for success: the recipient must share a server with the bot and must allow DMs from server members. It does not, however, name an alternative or state when to prefer another tool, 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.

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

Annotations already cover the safety profile (not read-only, not destructive, open-world). The description adds meaningful behavioral context beyond that: the payload must be base64, the file size is capped at 3 MB, and the message is optional. It stops short of noting auth needs, rate limits, or failure modes, so it is good but not rich.

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

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

A single, tightly packed sentence with the key constraint (base64, 3 MB) and scope front-loaded. Every clause earns its place and nothing is padded.

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

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

For a file-upload tool with 100% schema coverage and annotations covering the safety profile, the description gives the essentials an agent needs to call it correctly. It omits how uploads are reported back (no output schema) and any error/auth context, but that is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents channel_id, filename, mime_type, content, and content_base64. The description restates the base64 encoding and the 3 MB ceiling already implied by the schema's maxLength, adding only marginal value, so baseline 3 applies.

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

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

States a specific verb (upload) and resource (file, base64, up to 3 MB) plus scope (channel or thread). This clearly separates it from discord_send_message, but it never names the sibling, so differentiation is inferred rather than explicit.

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

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

The phrase 'to a channel or thread' implies where the tool applies, and 'with an optional message' hints at the message-attachment use case. However, there is no guidance on when to use this versus discord_send_message or discord_send_webhook_message, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds nothing behavioral: no note that the post is public/visible to channel members, irreversible via this tool, or subject to permissions or rate limits.

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

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

Two short sentences, front-loaded with the action and resource, then the required payload combination. No filler.

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

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

For a low-complexity send tool with full schema coverage and no output schema, the description is minimally adequate. It omits permission requirements, failure behavior, and routing against the many other sending tools, leaving real gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint not encoded in the schema: only channel_id is required, yet the text establishes that content and/or an embed must be supplied. That is genuine additive value.

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

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

States a specific verb and resource ('Send a message to a channel or thread'), which is enough to distinguish it from the DM and webhook siblings. It stops short of explicitly naming those siblings, so differentiation relies on the channel/thread scoping.

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

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

No when-to-use guidance and no alternatives named. Given siblings discord_send_dm, discord_send_webhook_message, and discord_send_file, the agent gets no help deciding which send path applies.

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

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

Annotations already declare a non-read-only, open-world, non-destructive write. The description adds genuinely new information: the server resolves the webhook token itself, so the caller needs only webhook_id and no secret. It stops short of describing irreversibility or rate limits, but it adds real context beyond the annotation set.

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

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

Two short sentences, both front-loaded and free of filler; the token-lookup note follows the primary action naturally.

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

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

With no output schema and a nested embed object, the description is nearly sufficient, but it never says what comes back (e.g. the created message id) and leaves the max-length content field unaddressed. Minor gaps for a simple post operation.

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

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

Schema description coverage is 75%, so the schema documents the embed structure, username, and webhook_id; the description only restates the optional display-name behavior. It adds no meaning for the undocumented 'content' parameter, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Post a message through a webhook') and adds the distinguishing mode (webhook vs. bot-authored post), which separates it from discord_send_message even though that sibling is never named. Clear, though sibling differentiation is left implicit.

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

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

No when-to-use or when-not guidance. The description never explains why an agent would choose a webhook post over discord_send_message or discord_send_file, nor does it note prerequisites such as the webhook having to exist.

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

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

Annotations already declare a non-read-only, non-destructive write. The description adds real value beyond them: it discloses replacement semantics (the whole overwrite is set, not merged), the inheritance rule for permissions absent from both allow and deny, and the Manage Roles authorization requirement.

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

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

Three short sentences, zero filler, and the core replace semantics are front-loaded before the inheritance note and the permission prerequisite.

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

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

For a mutation tool with annotations but no output schema, the description covers replacement semantics, inheritance, and required permissions. It omits error conditions (e.g. overwriting a higher-positioned role) and confirmation of the return value, which is a minor gap.

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

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

Schema coverage is 80%, so the schema documents most parameters. The description still adds meaning the schema lacks: that target_id is a role or member interchangeable with target_type, and the allow/deny inheritance semantics that govern how the two arrays interact.

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

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

States a specific verb and resource ('Set (replace) the permission overwrite'), names both target kinds (role or member) and the scope (on a channel). This clearly separates it from discord_delete_channel_permission and discord_edit_role without needing the schemas.

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

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

The word 'replace' implies this is the write-side counterpart to discord_delete_channel_permission, and 'Needs Manage Roles' gives a precondition. However, it never explicitly says when to use this versus deleting an overwrite or editing a role, so usage is only implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds real value by clarifying that join/leave act on the bot itself while add/remove target another user, but it omits permission requirements and what happens when a user is already a member.

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

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

A single front-loaded sentence with no filler; the parenthetical disambiguation of bot vs user is compact and earns its place.

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

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

There is no output schema, so the description should indicate what 'list' returns (identities? pagination?) and whether membership changes need elevated permissions. With five distinct actions bundled in one tool, those gaps leave an agent under-informed.

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

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

Schema description coverage is 67%: user_id is documented as 'Required for add/remove' and thread_id is labeled. The description only restates the add/remove need for a user, adding no format, ID-sourcing, or validity guidance beyond the schema, so the baseline 3 applies.

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

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

The description names the resource (thread membership) and enumerates the concrete operations (join/leave, add/remove a user, list), which maps cleanly onto the action enum. It is distinguishable from siblings like discord_list_members and discord_list_threads, though it doesn't explicitly name them.

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

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

The action list implies when each mode applies, and the 'join/leave (the bot)' vs 'add/remove a user' split gives useful routing context. However, there is no explicit when-to-use guidance against alternatives (e.g. discord_moderate_member for removing a member) and no prerequisites stated.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds two useful behavioral facts beyond them: the action persists without sending, and the result lands in Drafts. It says nothing about auth requirements, recipient-optional behavior, or size handling for a 4 MB attachment limit.

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

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

Two short sentences, the non-send constraint front-loaded in the first sentence where it matters most. Nothing is wasted and nothing is buried.

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

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

For a 7-parameter create tool with no output schema, the description is thin but the schema carries parameter semantics and annotations carry the safety profile. It never clarifies the notable edge case that a draft can be created with no recipients, which an agent would benefit from knowing.

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

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

Schema description coverage is 86%, so the schema already documents recipients, body/html relationship, and the attachment size cap. The description adds no parameter detail at all (e.g., that 'to' is optional for a draft), so the baseline 3 applies and no credit is earned.

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

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

States a specific verb+resource ('Save a draft in Gmail') and, crucially, negates the sending behavior ('does not send'), which is the core distinction from the sibling gmail_send_draft. The verb/resource pair is unambiguous, though it never names a sibling explicitly.

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

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

The parenthetical 'does not send' implies the usage context (use when you want to stage a message rather than deliver it), which is genuinely useful given gmail_send_email and gmail_send_draft exist as siblings. However, there is no explicit when-to-use, when-not, or named alternative, so guidance is only implied.

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

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

Annotations already declare this is a write (readOnlyHint=false) that is non-destructive and open-world. The description adds the nesting behavior via '/', which is a useful trait beyond annotations, but omits what happens on duplicate names or required scope/permissions.

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

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

Two short sentences, front-loaded with the action and zero filler. Every part earns its place.

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

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

For a simple one-parameter tool with annotations covering the safety profile and no output schema, the description covers purpose and parameter format adequately. Minor gaps (duplicate handling, return value) are low-cost for this complexity.

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

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

Schema coverage is 0% for the single 'name' parameter, so the description compensates by documenting the '/'-delimiter convention for nested labels (Work/Invoices), giving syntax the schema lacks. It does not clarify other formatting constraints, but it adds real meaning.

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

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

States a specific verb+resource ('Create a label'), clearly distinguishing it from siblings like gmail_delete_label and gmail_list_labels by the verb. It stops short of explicitly naming those alternatives, but the action is unambiguous.

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

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

Provides no when-to-use context and no exclusions or alternatives (e.g., how it relates to gmail_modify or gmail_delete_label). The nesting tip is a format hint, not usage guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds the meaningful detail that deletion is permanent/irreversible, which is real added context, but it says nothing about auth scope or what happens to the id afterward.

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

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

A single four-word sentence with zero waste and the critical qualifier ('Permanently') front-loaded. It is appropriately sized, though it is minimal to the point of omitting routing information.

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

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

For a one-parameter destructive tool whose annotations already cover the safety profile and whose schema documents the id, the description is nearly sufficient. The only gap is not routing the agent to gmail_trash or gmail_list_drafts as a discovery path.

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

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

Schema coverage is 100% and the single 'id' parameter already documents its source (gmail_search / gmail_list_drafts). The description adds no parameter-level meaning, so baseline 3 applies.

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

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

States a specific verb+resource ('delete a draft') with the qualifier 'Permanently', which implicitly distinguishes it from the trash-style sibling gmail_trash. It does not name that sibling explicitly, so differentiation is inferential rather than stated.

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

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

No explicit when-to-use guidance and no named alternative. The word 'Permanently' hints at the contrast with gmail_trash, but the agent is left to infer that trashing is the non-destructive option.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely useful context beyond that: messages carrying the label are retained, clarifying that the destruction is scoped to the label itself, not the messages it was applied to.

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

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

Two short sentences, the destructive action front-loaded and the important side-effect stated immediately after. No filler or redundancy.

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

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

For a one-parameter mutation tool with no output schema, the description covers the main effect and its message-preserving side effect. It omits error behavior (unknown label), the expected 'name' format, and any confirmation semantics, leaving meaningful gaps.

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

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

Schema coverage is 0% for the single required parameter 'name', so the schema supplies only a type. The description says nothing about whether 'name' is the display name or label ID, case sensitivity, or how a nonexistent label is handled, so it fails to compensate for the coverage gap.

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

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

The description states a specific verb (Delete) and resource (a label), and the second sentence disambiguates it from operations that remove messages. It does not explicitly name siblings like gmail_create_label or gmail_list_labels, but the action is unambiguous on its own.

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

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

There is no statement of when to use this tool versus alternatives (e.g., gmail_modify, gmail_trash), no prerequisites such as needing the label to exist, and no exclusions. Usage can only be inferred from the name.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write/send nature is covered structurally. The description adds genuinely useful behavior beyond that: the original is attached as .eml, and the message is dispatched immediately with no draft or confirmation step. It omits permission/scope requirements and what is returned, keeping it short of a 5.

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

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

Two short sentences, front-loaded with the core action and followed by the two facts an agent most needs (attachment behavior, immediate send). No filler, no repetition of the schema.

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

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

For a 4-parameter mutation tool with no output schema, the description covers the essential behavior: what is sent, in what form, and that it fires immediately. It leaves minor gaps around failure behavior and the return payload, but nothing critical to invoking it correctly is missing.

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

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

Schema description coverage is 100%, with all four parameters (id, to, cc, note) documented inline, so the schema carries the load. The description adds no parameter-level detail such as id provenance beyond the schema or note placement semantics, so the baseline 3 applies.

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

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

States a specific verb+resource ('Forward an email') that an agent can distinguish from gmail_reply and gmail_send_email on intent alone. It does not, however, explicitly name those siblings or state how forwarding differs from replying, so differentiation is inferential rather than stated.

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

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

'Sends immediately' implies this is the no-draft path and contrasts with gmail_create_draft, but the description never explicitly says when to forward versus reply or send a new email. Usage is implied rather than guided, and no exclusions or prerequisites are given.

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

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

Annotations already establish readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavioral context beyond that: the return format (base64) and, importantly, a ~2 MB size ceiling that signals the call may fail for large attachments.

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

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

A single short sentence, front-loaded with the action and ending with the constraint. No filler whatsoever.

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

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

For a simple annotated read tool the description covers what it returns and the size limit, which is largely adequate. However the undocumented 'filename' matching semantics and the absence of any routing relative to gmail_get_message leave an agent with unanswered questions before a call.

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

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

Schema coverage is only 50% — 'id' is documented (cross-referencing gmail_search/gmail_list_drafts) but 'filename' has no description anywhere. The description adds nothing about how the filename must match (exactness, case, multiple matches), so the gap is left unclosed.

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

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

States a specific verb (download) and resource (attachment), plus the output format (base64) and a size cap. It is clearly distinguishable from gmail_get_message since no sibling performs attachment downloads, but it never explicitly contrasts itself with the message-retrieval tools.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as gmail_get_message. The agent is left to infer that this is the tool for retrieving attachment bytes from a known message.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds a valuable non-obvious behavioral detail: the operation does not mark the message as read unless mark_read is true, which is exactly the kind of side-effect nuance annotations cannot express.

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

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

Two compact sentences, front-loaded with what it does and followed by the one non-obvious side effect. No filler.

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

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

With no output schema, the description appropriately summarizes the return shape (headers, body, attachment list), and annotations cover safety. It omits mention of body truncation/max_chars, but the schema documents that default, so nothing critical is missing.

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

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

Schema coverage is 67%; id and max_chars are documented in the schema but mark_read has no schema description. The description compensates by explaining mark_read's exact effect, closing the gap for the one undocumented parameter.

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

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

States a specific verb and resource ('Read one email') and enumerates the return contents (headers, text body, attachment list). It is clearly distinct from write siblings like gmail_send_email or gmail_modify, though it does not explicitly differentiate itself from the close sibling gmail_get_thread.

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

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

The description implies a single-message read but gives no explicit when-to-use guidance or naming of alternatives such as gmail_get_thread or gmail_get_attachment. Usage must be inferred from context.

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

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

Annotations cover the safety profile (readOnlyHint), and the description adds genuinely useful response behavior beyond them: bodies truncated to 4000 characters each and a 30-message cap. This is important context an agent needs to interpret results correctly.

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

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

Two short sentences, front-loaded with the core action and then the limits. Every clause carries information; nothing is wasted.

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

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

With no output schema, the description usefully discloses ordering and truncation limits so the agent can reason about the returned data. It could note pagination or how to fetch beyond 30 messages, but is otherwise complete.

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

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

Only one parameter (thread_id) and schema coverage is 100%, with the schema already noting it comes from gmail_search. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read a whole conversation') plus scope (whole thread, oldest first). An agent can distinguish it from gmail_get_message (single message) and gmail_search (search) without opening any schema.

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

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

Usage is implied by 'whole conversation' versus a single message, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of using gmail_search first to obtain a thread_id.

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

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

readOnlyHint=true and openWorldHint=true already tell the agent this is a safe, non-destructive read against external data. The description adds one genuinely new behavioral fact — results are sorted newest first — but says nothing about pagination, whether archived sent-drafts appear, or result volume.

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

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

One short sentence with the resource first and the ordering constraint second. Every word earns its place; nothing is padded or redundant.

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

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

For a zero-required-parameter read tool of low complexity, with annotations covering the safety profile and the schema covering the only parameter, the description is nearly sufficient. Minor omissions (pagination or whether more than `limit` results exist) keep it from a 5.

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

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

There is a single optional parameter (limit) with 100% schema description coverage already stating the 1-100 range and default of 20. The description adds no extra meaning about the limit, so the baseline 3 applies.

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

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

States a specific verb+resource ("List drafts") and adds the ordering guarantee ("newest first"), which clearly separates it from gmail_create_draft, gmail_send_draft, and gmail_delete_draft. It does not explicitly name a sibling, so it stops short of a 5.

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

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

There is no statement of when to use this tool versus gmail_search, which can also surface draft content, nor any exclusion or precondition (e.g., mailbox scope). The usage is inferable from the verb but the description provides no actual guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral detail beyond annotations: the response includes the inbox unread count, not just the label list. It says nothing about pagination, ordering, or system-vs-user label handling.

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

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

A single front-loaded sentence naming the action first and the returned extras second. Nothing is wasted and nothing needs to be trimmed.

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

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

For a parameterless read tool with no output schema, the description gives enough to call it correctly and even hints at the return shape (labels plus inbox unread count). Only the absence of return-format detail keeps it short of fully complete.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter semantics to add or omit.

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

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

States a specific verb and resource ("List Gmail labels/folders") and adds scope detail about the inbox unread count. It is clearly distinguishable from siblings like gmail_create_label and gmail_delete_label, though it does not explicitly name them.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer. Usage is only inferable from the name itself; the description adds no routing guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond the action itself — it does not mention reversibility, effect on future filtering, authentication requirements, or any side effects. With annotations carrying the burden, this minimal restatement earns only a low score.

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

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

The description is a single, front-loaded sentence with zero wasted words. It is appropriately sized for a simple, one-parameter tool, though it borders on being too terse to provide any structure or nuance.

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