relay_activate_output

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

With no annotations, the description fully discloses the critical side effect: 'WARNING: physically switches hardware.' It also explains the toggling behavior of state, the conditional nature of pulse_duration (only when state='on'), and the confirm safety gate. The reference to UNIFI_PROTECT_MUTATIONS_ENABLED adds constraint context beyond the schema.

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 information-dense with no fluff, front-loading the purpose and warning. However, the formatting is slightly inconsistent: the bullet-like lines for state and pulse_duration are not evenly aligned, and the line break before 'UNIFI_PROTECT_MUTATIONS_ENABLED' interrupts flow. It is concise but not perfectly structured.

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?

Despite having 6 parameters and a physical side effect, the description covers all essentials: purpose, endpoint, parameter semantics, prerequisites, safety confirmation, and a feature-flag constraint. An output schema exists, so omitting return-value details is acceptable. An agent has everything needed to invoke this 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 and does explain every parameter: host (console name/ID/composite ID), relay_id (required, sourced from list_relays), output_id (required), confirm (must be true), state (on/off, omit to toggle), and pulse_duration (auto-off ms, only when state='on'). This fully compensates for the schema's lack of descriptions.

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 opens with 'Switch a relay output,' a specific verb and resource, and reinforces it with the exact HTTP endpoint (POST /v1/relays/{id}/outputs/{outputId}/activate). This clearly distinguishes it from sibling tools like list_relays, get_relay, and update_relay, which serve different purposes.

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 provides explicit prerequisites: relay_id is required and must be obtained from list_relays; confirm must be true to execute; state can be omitted to toggle. It also warns about physical hardware switching and mentions the feature flag UNIFI_PROTECT_MUTATIONS_ENABLED. It does not explicitly name alternatives or when-not-to-use conditions, but the usage context is clear.

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