remote_run_script

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the risk profile is covered. The description adds real context by disclosing the upload mechanic (the script lands on the remote host) and the supported language matrix, but says nothing about cleanup deleting the uploaded file, the 600s default timeout, or output truncation behavior.

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 with the core action front-loaded and the language support enumerated compactly. Nothing is redundant, though the second sentence could have carried operational detail instead of just a format list.

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 need not be explained. However, for a destructive, open-world execution tool with 11 undocumented parameters and several close siblings, the description leaves critical gaps around target selection and cleanup semantics.

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 11 parameters, so the description must compensate and it largely does not. The language list loosely maps to the language parameter and "inline or local" maps to script/local_path, but cleanup, timeout, output_limit, profile, connection, interpreter, remote_path, and args are left entirely undefined.

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 pair ("Upload and run") and resource ("inline or local script"), which is concrete enough for an agent to know the operation. It does not differentiate from siblings like remote_execute, remote_run_program, or remote_session_execute, which occupy similar space.

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 mention of "inline or local script" implies two input modes but gives no guidance on when to pick this tool over remote_execute, remote_run_program, or remote_session_execute. No prerequisites, no exclusions, no conditions are stated.

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