power_off_all

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

No annotations provided, but description fully discloses that this is a drastic action that cuts power to all systems, requires explicit re-powering, and re-reads and confirms results per system. References set_power's docstring for an upgrade note, showing awareness of version-specific behavior.

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?

Somewhat verbose with alternative phrasings and comparisons, but each sentence adds value. Could be slightly more concise, but the information is well-organized and front-loaded with the main action.

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 no output schema, the description covers return behavior (confirmation per system), side effects (power loss and need for re-powering), and contextualizes relative to siblings. It fully explains the tool's behavior and impact.

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?

No parameters exist, so no parameter description needed. The description does not discuss any input schema details, but that is appropriate given zero parameters. Baseline 4 for no-param tools.

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?

Description states 'Cut power to EVERY DCC system at once' with explicit verb 'cut power' and resource 'all DCC systems'. Clearly distinguishes from sibling emergency_stop_all by explaining the scope (all locos regardless of session) and the fact it cuts power, not just e-stops. Also provides alternative phrasings like 'coupe le courant' to avoid confusion.

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?

Explicitly says 'Call for generic power-cut request with no specific system named' and contrasts with emergency_stop_all when user mentions 'power' vs 'stop'. Warns not to use for routine stop and explains re-powering requirement. Provides clear when-to-use and when-not-to-use guidance.

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