add_reaction

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

Annotations already indicate this is a non-read-only, non-destructive operation. The description adds useful behavioral context about supported emoji formats and automatic URL encoding. However, it does not disclose potential side effects such as duplicate reactions or what happens with invalid emoji, leaving some behavioral 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?

A single, front-loaded sentence with no redundant wording. It conveys the core action, accepted formats, and a key technical detail (URL encoding) efficiently.

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 mutation with no output schema, the description is largely complete. It covers the one non-obvious detail (emoji format) and encoding behavior. It could mention idempotency or duplicate behavior, but the essential information for calling the tool correctly 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 0% schema description coverage, the description must compensate. It does clarify the emoji parameter by specifying Unicode emoji or custom name:id format and automatic URL encoding. It provides no added meaning for channel_id or message_id, though their names and numeric patterns make their purpose fairly self-evident.

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 ('React') with the resource being a message, implied through the message_id parameter. It clearly identifies the emoji input format, making the tool's function understandable. It does not explicitly differentiate from siblings like send_message, but the verb is specific enough.

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 the tool is for adding reactions to messages, but it gives no explicit guidance on when to choose this over alternatives, nor any exclusions or prerequisites. The context is clear enough for a straightforward mutation, but no alternatives or when-not-to-use scenarios are mentioned.

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