remote_command_group_run

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, so the risk profile is known from structured data. The description adds genuine value by disclosing that dry_run returns the generated command without executing it — the only safe preview path for a destructive tool. It does not say what side effects occur, whether confirmation is required, or how errors on a multi-host group are reported.

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?

Two short sentences, front-loaded with the core action and followed by the connection and dry_run notes — no filler or repetition. Slight redundancy in the example list, but it does earn its place by hinting at the action domain.

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?

The output schema exists, so return values need not be explained, and annotations cover the safety profile. But for a destructive, open-world, 9-parameter tool with 0% schema coverage and no enum hints, the description leaves the two required parameters and three optional ones undefined, which is thin for the complexity involved.

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% across 9 parameters, so the description carries the full burden and largely fails it: only session_name/profile/connection (as an either/or) and dry_run are addressed. The two required parameters, group and action, get no explanation of valid values or format, and parameters, timeout, and output_limit are never mentioned.

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 gives a verb+resource ("Build and run a specialized action") and concrete examples (user management, services, reboot, system inventory), which is more than a tautology. However, "specialized action" is fuzzy and it never explains what a "group" is or how this differs from siblings like remote_execute, remote_run_program, or remote_run_script, so an agent cannot reliably route between them from the text alone.

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?

It states one real selection rule — "Use either session_name or profile/connection" — and explains what dry_run does, which is actionable. It gives no guidance on when to choose this tool over remote_execute or remote_run_script, and no mention that group/action values likely come from remote_command_groups / remote_command_group_describe, so usage is only partially implied.

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