Peek at SSH command output

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds key behavioral details: wait_sec long-polls but never stops the remote command, output is limited independently for stdout/stderr, lines are capped to protect model context, and idle returns cwd and last exit code. These traits are not in the annotations and significantly enhance transparency.

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 well-structured and each sentence adds unique value: purpose, wait_sec semantics, output behavior, usage context, and idle behavior. There is no fluff or redundancy, and the length is justified given the parameter complexity and zero schema descriptions.

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, the description thoroughly explains return values: newest lines in chronological order for stdout/stderr, and when idle, cwd, last exit code, and latest lines. It also covers all operational states (running vs idle) and parameter effects, making the tool fully comprehensible.

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%, but the description compensates fully. It explains wait_sec's long-polling behavior and that it never stops the command, lines defaults to 50 with a cap, and id is implicitly tied to ssh_run's returned handle. This gives meaning to all three parameters beyond their raw schema definitions.

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 observes the current foreground command and its latest output without starting another command. It distinguishes itself from siblings like ssh_run (start) and ssh_interrupt (interrupt) by focusing on passive observation. The verb 'observe' plus specific resource (SSH command output) makes the purpose unmistakable.

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 explicitly says 'Use after ssh_run returns status=running', giving a clear when-to-use directive. It also advises preferring a positive wait_sec over busy-looping, which is a practical usage guideline. The idle-state description further clarifies expected behavior in different conditions.

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