Read SSH File

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

Goes well beyond the annotations by disclosing that output is capped and line-redacted by the SSH engine, that ordinary reads are allowed across dev/test/prod, and that sensitive paths may be blocked by connection or OS permissions. That is genuinely useful behavioral context not carried by readOnlyHint/idempotentHint.

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?

Three tight sentences, front-loaded with the core action, followed by use case and constraints. No wasted text, though the constraint sentence could be ordered slightly better.

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 return values needn't be explained, and the safety/redaction profile is covered. But for a seven-parameter tool with zero schema descriptions, the description leaves the paging/subset parameters too underspecified for confident invocation.

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%, so the description must compensate, and it largely does not. The phrase 'bounded remote file slice or tail' hints that limit/offset/tailLines exist, but it never explains their semantics, interaction, defaults, or what timeoutMs, workspaceId, and connectionId mean.

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 specific verb and resource: reads a bounded remote file slice or tail over SSH. It implicitly contrasts with the write/patch siblings, but it never names them or distinguishes itself from exec (which could also cat a file) or read_task_run_log.

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?

'Useful for logs and config inspection' gives an implied usage context but no explicit when-not guidance and no alternatives. An agent must infer on its own whether to prefer exec, read_task_run_log, or list_dir for a given inspection task.

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