privileged-command

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

Annotations only declare destructiveHint: true. The description goes well beyond this by disclosing the approval gate mechanics (prompt/allow/refusal based on profile approvalPolicy), the stdin password handling (never visible in process list), and the single-line-only refusal. This adds rich behavioral context beyond what annotations provide, and it does not contradict the destructive hint.

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 concise sentences that are front-loaded with the core purpose and immediately provide the most critical operational constraints (approval gate, password handling, single-line rule). Every sentence earns its place; no filler or repetition.

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 destructive, elevated execution tool, the description covers all critical operational aspects: approval behavior, password security, input constraints, and the alternative path for multi-line scripts. The absence of an output schema is fine since command execution tools typically return stdout/stderr, and that is implied. Nothing an agent needs to call this tool correctly is missing.

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 100%, so baseline is 3. The description adds value by explaining that the profile parameter determines the approval policy behavior, and it clarifies the command's single-line constraint. It doesn't elaborate on the exact format of command, but the schema already covers that. The added profile context justifies a 4.

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 states a specific verb ('Execute a command'), a resource ('with sudo elevation'), and the approval gate context. It distinguishes from siblings by making clear this is the privileged variant (run-command is non-privileged) and explicitly references sftp-upload for multi-line scripts, so an agent can select it correctly without opening schemas.

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 explicitly says when to use (when sudo elevation is needed) and provides a clear alternative: 'upload a multi-line script with sftp-upload and run it by path' for anything containing a line break. It also implies that non-privileged commands belong in run-command, which is evident from naming and context.

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