get_failed_logins

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

With no annotations present, the description carries the full burden and does substantial work: it discloses the SSH transport, that root is required because btmp is not world-readable, and that a passwordless sudo/doas escalation (sudo -n / doas -n) is attempted when the login user is not root. It omits what happens on escalation failure (error vs empty result) and says nothing about host-key verification or auth-method precedence, which are meaningful gaps for a remote-execution tool.

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 core identity, output fields, and brute-force use case are front-loaded in the first two sentences, followed by the root requirement and then the optional filter syntax. The 'USE THIS TOOL' capitalization is slightly promotional, 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?

An output schema exists, so re-listing the returned fields is arguably redundant, yet the description still leaves the operationally important pieces uncovered: escalation-failure behavior, output truncation via 'lines' (default 50), timeout semantics for a network-bound call, and connection/auth parameters. For a 9-parameter remote-SSH tool with no annotations, that is adequate but incomplete.

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% across 9 parameters, so the description must compensate and largely does not. It adds real value for 'since' by enumerating accepted expressions ('30 min ago', 'today', 'YYYY-MM-DD HH:MM:SS'), but port, lines, timeout, key_path, password, and accept_new_hostkey are left entirely undefined in both schema and prose.

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 names a specific verb ('Lists'), resource ('recent FAILED login attempts'), data source ('lastb, from btmp'), transport ('via SSH'), ordering ('newest first'), and return fields ('attempted user, terminal, source address, time'). The 'FAILED' emphasis implicitly separates it from the successful-login sibling get_last_logins, though it never names that sibling to make the contrast explicit.

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 THIS TOOL to check for brute-force attempts' gives a clear positive use case. There is no statement of when not to use it and no named alternative (e.g., get_last_logins for successful logins), so it stops short of full routing guidance.

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