unifi_console_poe_overview

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: what power supervisors do and how to read consecutive_failures as an active power-cycle signal. That is genuine diagnostic semantics beyond the structured fields.

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?

Front-loaded with the resource, then the diagnostic guidance, then the return shape — each sentence earns its place except the JSON shape line, which restates what the output schema already provides.

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?

Strong on diagnostic intent and interpretation, and the return payload is already documented by the output schema. The only gap is that the required device_mac argument is never addressed in the description, relying entirely on the schema.

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?

The description never mentions the single device_mac parameter, so it adds no meaning over the schema. The schema property itself does carry format guidance and a hint to find the MAC via device-list tools, so an agent is not left stranded, but the tool text contributes nothing here.

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?

Names a specific verb+resource and scope: 'PoE budget for one switch plus the site's power supervisors'. The parenthetical definition of power supervisors as watchdogs that power-cycle ports makes the resource unambiguous and clearly distinct from sibling switch_port_detail.

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?

Gives a concrete usage trigger ('Check this before diagnosing a PoE device that keeps rebooting') and even the interpretation rule (consecutive_failures above zero = power-cycling). No alternative sibling is named and no when-not condition is stated, so it stops short of a 5.

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