Discover the server (read-only, SSH)

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

Well beyond the annotations, the description discloses the fixed command set, secret redaction, that env files are listed by name only, that sudo requires password-less sudo or some commands may be denied, and that command output must be treated as data. Annotations already cover readOnly/idempotent/destructive, so this is bonus context. It doesn't say anything about runtime, output volume, or partial-failure behavior, which keeps it off a 5.

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 what it does, then scope, then the phase/consent guidance, then sudo semantics, then the injection caveat — a sensible ordering with almost no filler. The sudo clause is a deep parenthetical that interrupts the flow, and the closing safety sentence could be tighter, but nothing is genuinely redundant.

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?

Nine parameters, an output schema, and full annotation coverage mean the description's remaining obligations are scope, consent, and safety, all of which are stated. Combined with the note that it cannot execute arbitrary commands and that output is redacted, an agent has everything needed to invoke it safely and 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 coverage is 100%, so the baseline is 3, but the description adds real meaning for sudo ("only if that account has password-less sudo; otherwise they run as the alias's user and some may be denied") that the schema's terse "Run the commands as root with sudo -n" does not convey. The sections parameter and its default when omitted are not discussed, so it isn't a 5.

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?

"Runs the fixed, read-only discovery commands ... on the Plesk server over the user's own ssh" gives a specific verb, a bounded scope ("fixed", "It can't run any other command"), and the transport. It explicitly distinguishes itself from the sibling server_discovery_commands, which only lists those commands, so an agent can route correctly without opening a schema.

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?

"Use it in phase 2, after the user agrees, instead of asking them to paste the output" states the timing, the precondition (user consent), and the alternative it replaces. The only mild gap is that it doesn't say when to prefer the sibling lister over this one, but the purpose sentence already implies that split.

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