discord_pin_message

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

Annotations are empty, so the description carries the full burden of behavioral disclosure. It only says what it does, not whether channel permissions are required, whether the pin is visible immediately, whether there are Discord pin limits, or what side effects happen.

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?

It is a single clean sentence with no filler words, so it is easy to parse and front-loaded. However, the brevity comes at the cost of operational detail that would make the description genuinely helpful.

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 mutating action with no annotations and no output schema, the description is too incomplete. An agent selecting this tool needs extra guidance on permissions, pin behavior, optional guild context, and why to choose this over discord_unpin_message or discord_list_pinned_messages.

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 only echoes 'channel' and 'message', which maps weakly to channel_id and message_id. The optional parameters reason and guild_id get no explanatory value from the description, and the schema itself provides no param descriptions beyond titles.

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 action ('Pin'), a specific resource ('a message'), and the location context ('in a channel'). It reads clearly different from sibling tools like discord_unpin_message or discord_list_pinned_messages, so an agent can grasp the operation without ambiguity.

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 about when to use this tool versus alternatives, no mention of prerequisites, and no distinction from unpin or list pinned messages. The only use guidance is implicit in the operation name itself.

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