ssh_tail

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

No annotations are provided, so the description carries the full burden of behavioral disclosure — and it delivers. It states the tool is read-only and does not modify remote state, and crucially reveals a non-obvious behavior: in follow mode (the default), output is written to server process stderr and the response only returns a session note, not content. It then tells the agent how to get content (set follow=false). This is exactly the kind of behavioral nuance a caller must know and could never infer from the schema alone.

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 purpose is front-loaded in the first sentence, and every sentence earns its place — purpose, safety claim, behavioral mode explanation, and defaults. The third sentence is a long, multi-clause run-on that packs several facts (streaming, stderr destination, session-note response, follow=false alternative, lines default) into one dense stretch. It is information-dense rather than bloated, but it could be restructured into clearer discrete sentences for easier parsing.

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?

With no output schema and no annotations, the description must explain return behavior — and it does, telling the agent that follow mode yields only a session note while follow=false returns the last N lines. Defaults are disclosed. Minor gaps remain: no mention of error behavior (unknown server, missing file), no clarification of whether grep applies in follow mode, and no detail on what the session note references. These are secondary to the core call-and-interpret cycle, which is well covered.

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. The description adds significant value on top: it explains that `follow` changes the entire output behavior (session note vs. returned lines) and that `lines` defaults to 10. It also reinforces `server` as a named configuration entry and `file` as the log path. The description does not merely echo schema text; it explains the behavioral consequences of the key parameter, which lifts it above baseline.

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 opens with a specific verb and resource: 'Reads the tail of a remote log file on the named server, optionally filtered by a grep pattern.' This precisely states what the tool does and clearly differentiates it from siblings like ssh_execute, ssh_monitor, or ssh_db_query — none of which tail log files. An agent can identify this tool's purpose without opening the 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?

The use case is clearly implied: tail a remote log file, with optional grep filtering. The description gives strong internal mode-selection guidance (set follow=false to capture content directly vs. follow=true for streaming). However, it never names alternative tools or states when NOT to use this tool, despite 35 siblings including monitoring-oriented tools (ssh_monitor, ssh_service_status, ssh_health_check) that an agent might confuse it with. The routing to siblings is left to inference.

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