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

Goes well beyond the annotations by disclosing a hidden side effect (the number appears online and unread messages in the conversation are marked as read), the quota cost of that side effect, and a plan gating condition with the exact error code `payment_required: feature_not_available` plus the instruction not to retry. These are exactly the traits an agent cannot infer from readOnlyHint/destructiveHint/idempotentHint, and none of it contradicts them.

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?

Purpose is front-loaded in the first sentence and the paragraphs are short and purposeful, covering removal, replacement, side effects, and billing. The replacement semantics are restated in two places, which costs a little tightness but not 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?

For a three-parameter mutation tool with an output schema, the description covers everything an agent needs: required inputs, removal path, replacement behavior, hidden read-marking side effect, quota implications, and a non-retryable billing failure. Nothing material is left to inference.

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 meaning the schema does not: that a new emoji replaces this number's previous reaction rather than stacking, and how to restore the earlier one. The single-emoji-character guidance partially duplicates the schema's own emoji description.

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 opening sentence names a specific verb and resource ('Attach an emoji reaction to a message, or remove one') and covers both directions of the operation. This clearly separates it from siblings like get_message_reactions (read) and reply_to_message (send), so an agent can pick it without opening a 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?

It gives a concrete usage cue: 'reacting to something a customer sent is often a cheaper acknowledgement than a reply,' which implicitly routes the agent away from reply_to_message. It also explains the empty-string removal path and the replace-not-add semantics, but it never explicitly names an alternative tool or states when not to use this one.

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