React to Relay Message

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

Annotations already indicate this is a mutating, non-idempotent, and destructive operation. The description adds useful scope context by saying the reaction applies to a message 'part' and supports both add and remove. It does not disclose behaviors like replacing an existing reaction or what happens when removing a non-existent reaction, but the annotations carry much of the safety burden.

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 a single, front-loaded sentence with no redundant wording. It clearly names the action and target, which is appropriately concise for a tool whose schema already defines the enumerations and required fields.

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 five parameters, zero parameter descriptions in the schema, and no output schema, the tool description is under-specified. It lacks guidance on when 'part_index' should be used, how custom emojis are handled, and what the result of the operation is. The annotations cover safety, but not the operational details needed to call the tool correctly.

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 0%, so the description must compensate by explaining parameters, but it only clarifies the operation concept. It does not explain the relationship between 'type', 'custom_emoji', or 'part_index', nor specify that 'custom' likely requires a custom_emoji value.

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 ('add or remove a reaction') and a specific resource ('Relay Message part'), making the tool's purpose immediately clear. It also differentiates this from sibling tools like send or get by focusing on reactions rather than message content.

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 intended usage is implied by the action: use this tool when a reaction needs to be added or removed. However, the description gives no explicit guidance about when not to use it or how it compares with alternatives such as sending a message or modifying a chat.

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