start_remote_batch

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

With no annotations, the description carries the full load and does well: it discloses that execution is process-local, that there is no discovery or retry, that state is lost after a server restart, and that SSH limits jumps to four. It omits what happens on partial per-target failure and whether credentials are required or validated.

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?

A single dense sentence where every clause adds a distinct constraint (target range, concurrency cap, deadline, no retry, jump limit, non-durability). Front-loaded with the core purpose and zero filler.

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 complex multi-transport tool with no output schema, the description should at least point to remote_batch_status for result retrieval and note that the returned handle is in-process only. It hints at volatility ('unknown after server restart') but never closes the loop on how to observe results.

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% and the schema has a large nested surface (credentials, keys, host pins, WinRM auth modes), but the description does add real meaning for the three top-level parameters: 1–32 targets, max 8 concurrency, per-target deadline. It still leaves the SSH-vs-WinRM field semantics and credential options entirely to the schema.

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 action and resource: a process-local SSH/WinRM batch run over explicit targets, which is clearly distinct from the single-host ssh_exec/winrm_exec siblings. It does not explicitly name those alternative tools, so the differentiation is implied rather than stated.

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?

'Opt-in', 'no discovery or retry', and 'Unknown after server restart' imply the operational context (explicit target list, non-durable, single-shot) but the description never says when to choose this over ssh_exec/winrm_exec or that remote_batch_status should be polled afterward. Usage is inferable but not spelled out.

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