buzz_reactions

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description earns credit for a genuine behavioral detail beyond that: reactions removed by their author (kind 5) are excluded, which an agent could not infer from the schema or annotations.

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?

Two short sentences with no filler: the first defines the operation and output grouping, the second covers the read-only nature and the exclusion rule. The most decision-relevant information is front-loaded.

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 two-parameter read tool with no output schema, the description does the important work of describing the return grouping (by emoji, with reactors) and the filtering rule. Minor gaps remain — no mention of ordering, pagination, or behavior on a message with zero reactions — but nothing essential to calling it is missing.

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 100% — 'event' is documented as the target message id from buzz_read and 'channel' as a name or id — so the schema already carries full parameter meaning. The description adds only the generic notion of a message target, matching the baseline for a fully documented schema.

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?

"List the reactions on a message" gives a concrete verb and resource, and "grouped by emoji, with who reacted" pins down the exact shape of the result. This cleanly separates it from the write-side siblings buzz_react and buzz_unreact without needing to name them.

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 read-only framing implies this is the tool for inspecting existing reactions rather than adding or removing them, so usage is inferable. However, it never explicitly says when to prefer it over buzz_read or buzz_thread_read, nor does it name buzz_react/buzz_unreact as the alternatives for changing reactions.

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