discord_remove_reaction

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool's behavior changes based on the presence of user_id (removing bot's own vs. user's reaction) and mentions a permission requirement (Manage Messages for user-specific removal). However, it lacks details on error handling, rate limits, or response format, leaving some gaps.

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 front-loaded with the core action and efficiently uses two sentences to cover key usage rules and permissions. Every sentence adds value—no wasted words—making it highly concise and well-structured for quick comprehension.

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?

Given the complexity (a mutation tool with permission nuances), no annotations, and no output schema, the description does a good job covering essential aspects like purpose, usage, and behavioral traits. However, it omits details on return values, error cases, or side effects, which could be important for full agent understanding in this 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 low at 25%, with only user_id having a description. The description compensates by explaining the semantics of user_id (optional, specifies whose reaction to remove, with implications for permissions) and implies the purpose of other parameters (channel_id, message_id, emoji for targeting). It adds meaningful context beyond the schema, though not exhaustive for all parameters.

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 clearly states the specific action ('Remove a reaction') and distinguishes it from siblings like discord_add_reaction and discord_delete_message by focusing on reaction removal rather than addition or message deletion. It specifies the resource (a reaction) and the operation (removal), making the purpose explicit and distinct.

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 provides explicit guidance on when to use this tool vs. alternatives: it specifies that without user_id, it removes the bot's own reaction, and with user_id, it removes a specific user's reaction (requiring Manage Messages). This clearly differentiates usage scenarios and prerequisites, helping the agent choose correctly based on context.

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