node_exec

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

Annotations already flag destructive/openWorld, and the description adds substantially more: it explains the resource-sharing execution model, the approval mechanism for deletions and process signalling, and — critically — that the approval check resolves the command word even when wrapped in timeout/nice/env/xargs/bash -c, and that os.kill inside `python -c` is also gated. That is exactly the kind of circumvention detail an agent could not infer from the annotations.

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?

Front-loaded with the action and the transport rationale, then examples, then constraints, then the approval rules — a sensible ordering with little filler. The nested parentheticals around the approval-check circumvention make the final third dense enough to require a second read.

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 should ideally say what comes back (stdout, exit status, truncation on long output, behavior on timeout), which it omits. Everything an agent needs to invoke the tool correctly — preconditions, node selection, timeout bounds, approval requirements — is otherwise present.

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 coverage is 0%, so the description must carry the load, and it mostly does: `node` is defined as one of the job's nodes with first-node default, `timeout_s` is bounded 5–120, `approval` is defined as the human's own words for destructive/signalling commands, and `job_id`/`command` are constrained by the RUNNING-job and diagnostic-only framing. It stops short of stating the job_id format or whether `node` accepts a short hostname versus FQDN.

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 and resource — run a short diagnostic command on a compute node of one of the user's RUNNING jobs — and immediately distinguishes itself from ssh and from login-node execution via the `srun --jobid=<id> --overlap` mechanism. An agent can tell this apart from `run_command` and `job_log` without opening any schema.

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?

Gives concrete typical invocations (nvidia-smi, top, free, py-spy, tail of node-local log, df -h /local) that define the intended use envelope, plus explicit exclusions: no background processes, no srun, timeout bounded 5–120s, and only for RUNNING jobs. It references `run_command` for shared rules but never explicitly says when to pick that sibling over this one, so it stops short of full routing guidance.

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