ssh_monitor

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

Discloses concrete side effects beyond annotations: close and reload drop live connections, while the other actions only read. It also explains the test output states (ready, limited, no-route, rejected). This does not contradict the annotations; destructiveHint=false is consistent with affecting only transient connections rather than data.

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 tight sentences: the first scopes and enumerates capabilities, the second gives side-effect warnings and usage guidance. No filler; information is efficiently 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 tool with two parameters and an output schema, the description covers all actions, side effects, read/write behavior, and a clear starting use case. Nothing an agent needs to select and invoke it correctly appears 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?

The schema fully covers both parameters, including profile requirements per action, so the baseline is 3. The description adds real meaning to the action enum by explaining what stats, reload, test, list, and close actually do, going slightly beyond the schema's generic 'Which of the five to do.'

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?

States a precise scope: manages SSH connections, not the machines behind them, and enumerates the five actions (list profiles, test, stats, close, reload). This clearly distinguishes it from the ssh_* sibling tools focused on machine health, file operations, and logs.

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 explicit entry-point guidance: start here on an unfamiliar machine because test tells whether other tools will work. It also warns that close/reload are destructive to live connections while other actions only read, though it does not name specific sibling alternatives or state when not to use it.

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