discord_set_guild_widget

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

Goes well past the annotations: it discloses that enabling publishes a live member list and online count to anyone with the widget URL, states the required permission (Manage Server), and declares the return ('Returns the resulting settings'). The annotations cover the safety profile (readOnly=false, idempotent, non-destructive), and the description adds the real-world side effect they don't capture.

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

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

Three tight sentences: scope first, consequence second, permission third, alternative last. No filler, and the most decision-relevant fact (public member list exposure) is front-loaded.

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

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

For a mutation tool with an output schema, this covers the prerequisites (Manage Server), the side effect, the idempotent nature, the return, and the sibling for reads. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: 'enabled' is not just a boolean toggle but a privacy exposure decision, and 'channel_id' is framed as the channel the widget points at. It doesn't restate the audit-log 'reason' param, but nothing important is lost.

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 + resource: 'Configure the server's embeddable widget: whether it is enabled and which channel it exposes.' It also explicitly separates itself from discord_get_guild_widget, so an agent can tell read from write 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?

Names the read alternative explicitly ('Use discord_get_guild_widget to read the current state and the public URLs') and frames the enabling decision as a privacy choice, which is the key when-to-use/when-to-hesitate signal for this tool.

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