set_reactions

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

No annotations are provided, so the description carries the full behavioral burden, and it does substantial work here: it discloses that existing reactions are destroyed ('replaces existing reactions'), that input is validated against a strict schema, and gives concrete validation rules (transition/direction constraints, destination compatibility per navigation type). It stops short of error behavior or required permissions, but the destruction and validation semantics are strong disclosure for an unannotated mutation tool.

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 and destructive semantics are front-loaded in the first clause, followed by two dense sentences of hard constraints. It is long, but nearly every clause encodes a real validation rule an agent needs, so the length is largely earned rather than padding.

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 2-param mutation tool with no annotations and no output schema, the description covers the critical complexity: what it overwrites and the cross-field validation rules that will otherwise cause failures. Remaining gaps (nodeId conventions, response/error shape) are minor given there is no output schema to explain.

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% for the two parameters, so the description must compensate. It richly specifies the semantic content of the reactions payload (action types, transition constraints, destination rules) but says nothing about the nodeId format or the concrete field layout of the reactions array, so it partially closes the gap rather than fully covering it.

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 verb and resource ('Set prototype reactions on a node') and immediately qualifies scope with 'replaces existing reactions.' It enumerates the supported action types, which cleanly separates it from read-only siblings like get_reactions and from narrower writers like upsert_reaction, set_transition_reaction, and set_smart_animate_reaction.

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 replacement semantics imply when to reach for this versus an additive tool, and the enumeration of supported action types hints at its breadth. However, it never explicitly names an alternative (e.g., 'use upsert_reaction to add without clearing') or states when-not to use it, leaving sibling routing to inference.

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