ssh_shell_send_secret

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that server_password avoids passing the password through correspondence and warns that ssh_shell_send logs text, implying this tool does not log when using server_password. However, it does not explicitly state whether this tool logs, what happens when value is used directly, or any other side effects or prerequisites, leaving behavioral transparency incomplete.

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 description is concise, with three sentences that front-load the purpose and provide critical security guidance. It is efficient and well-structured, with no wasted words.

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 5 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the role of value, idle_ms, or timeout_s, nor does it mention prerequisites like an active shell session or the expected behavior after sending. While the core usage is covered, operational details are missing, making it insufficient for an agent to call the tool correctly in all cases.

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 description only mentions server_password, which is already described in the schema. It does not explain value, idle_ms, or timeout_s. Since schema description coverage is only 20%, the description should compensate for the missing parameters but does not, leaving their semantics unclear and forcing the agent to infer their purpose.

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 clearly states the tool's purpose: entering a password into sudo, passwd, or installer prompts. It distinguishes itself from the sibling ssh_shell_send by explicitly warning against using that tool for passwords, making the specific role of this tool unambiguous.

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 description provides explicit guidance: prefer server_password to avoid passing secrets through correspondence, and explicitly instructs to never use ssh_shell_send for passwords because it logs the text. This gives clear when-to-use and when-not-to-use instructions with a direct alternative.

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