run-command

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

Annotations already mark destructiveHint=true, and the description builds on that by adding 'May modify the system' and describing approval-gate behavior based on approvalPolicy. This provides useful safety context beyond the structured annotation without contradicting it. It stops short of detailing what refusal or prompt looks like, but it is still solid.

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 short sentences, front-loaded with the main action and progressively adding risk and policy context. No filler or redundancy.

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 mutation tool marked destructive with a 'session' parameter and several close siblings, the description covers risk and approval policy but omits how command output is returned, whether execution is synchronous, and how this relates to privileged-command/open-session. That leaves meaningful gaps despite the good core.

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?

The input schema covers all 4 parameters (100% coverage), so the baseline is 3. The description adds marginal semantics by linking the profile parameter to approval-policy decisions, but it does not clarify tty or session beyond the schema descriptions.

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 opening sentence names a specific verb and resource: 'Execute an arbitrary shell command on the remote server.' This makes the core function unmistakable and distinguishes it from read-only/session-management siblings, though it does not explicitly contrast with privileged-command.

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?

No when-to-use guidance is given. The description explains the approval gate for destructive/privileged commands but does not say when to choose run-command over privileged-command, read-command, or open-session, nor when not to use it.

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