run_login_command

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

Annotations specify readOnlyHint=false and destructiveHint=false. The description adds valuable operational context: shared login node constraints, the 20-second timeout, the allow_heavy flag mechanism, and the policy-based refusal behavior. However, it does not mention possible return values, error modes, or how the refusal manifests, which could be useful given the output schema exists but its contents are not described here.

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?

Three sentences, front-loaded with the core purpose and constraint, followed by the exception condition and the timeout. Every sentence adds essential information without waste.

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?

Given the tool's complexity (command execution on a shared node with policy restrictions) and the presence of an output schema, the description covers the key behavioral constraints, the allow_heavy mechanism, and the timeout. It could mention the default timeout (15s) to complement the stated maximum (20s), and briefly note output/error handling, but overall it is nearly complete for an agent to call it correctly.

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?

With 0% schema description coverage, the description compensates well for the two non-obvious parameters: allow_heavy is explained in detail (lifts heavy-command refusal, only for documented cases), and timeout_seconds is implied by 'Delai maximal 20 s' although this actually overrides the default 15s, which could cause confusion. The command and cwd parameters are self-explanatory by name, but cwd semantics (default behavior) are not described. Overall solid compensation but with a minor gap on the timeout default.

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 (run) and resource (login node command) and names the command categories allowed (inspection, git, ls, grep). It clearly distinguishes from siblings like submit_job or run_cluster_sanity_check by emphasizing short/light commands on the shared login node, not compute jobs.

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?

Explicitly says heavy operations (compilations, installations, calculations) are refused by default, and that allow_heavy=true lifts the refusal only for cases explicitly authorized by ROMEO documentation, giving a concrete example (pip install within a venv targeting x86_64). This tells the agent when to use this tool versus when to use submit_job or build_on_node.

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