discord_threads

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description does nothing to localize that risk to specific actions such as leave, remove_member, or archive-related mutations, nor does it flag that read-style actions (active, archived_public) are non-destructive. It also omits permission/audit expectations despite exposing a `reason` parameter, leaving the behavioral picture thin beyond the generic annotations.

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

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

Two short sentences, front-loaded with the resource and the full action enumeration, then the delegation pointer. The long action list earns its place as the primary dispatch surface, though the bare enumeration lacks grouping by read vs. write.

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

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

This is a high-complexity multiplexed tool: 11 actions, nested objects (files, params, query), destructive behavior, and no output schema. Offloading all detail to discord_help leaves the agent unable to distinguish similar actions (active vs archived_public vs archived_joined) or know what each returns, which is a substantial gap for a tool of this breadth.

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 body, files, query, params, and reason; the description adds no parameter meaning it does not already contain, only a pointer to discord_help. Baseline 3 is appropriate when the schema carries the semantic load.

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 (Discord threads) and enumerates the concrete operations (create, from_message, active, archived_*, join/leave, member management), so an agent can see the tool's scope at a glance. It does not explicitly contrast itself with siblings such as discord_channels or discord_messages, but the resource name plus action list 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 only implied through the action names; the sole explicit instruction is to call discord_help with group="threads" for IDs and request fields. There is no guidance on when to pick this tool over discord_channels (e.g., public vs private archive listing, or creating a thread from a message vs standalone), so selection still requires inference.

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