Run a shell command

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

Adds real behavioral context beyond annotations: output is redacted of tokens, and specific classes of destructive commands (force-push, deleting tags/repos/releases, unpublish, recursive delete) are refused. Annotations already flag openWorld and destructive, so this enriches with the refusal policy. Doesn't mention default timeout behavior or permission requirements.

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 tight sentences, front-loaded with what it does and the platform detail, then the refusal policy. No 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?

For a 3-param tool with no annotations explaining timeout/cwd and no output schema, the description covers the command and refusal policy well but leaves parameter meanings and the 300s default timeout fully unexplained. Adequate but with clear gaps given the safety-critical nature of executing arbitrary shell commands.

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% – none of the three parameters (command, cwd, timeoutSeconds) are documented in the schema. The description doesn't explain command format, cwd semantics, or timeout behavior, leaving all params undescribed. It fails to compensate for the coverage gap.

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 (shell command line), including the platform-specific interpreter (PowerShell on Windows, sh elsewhere). This is clearly distinguishable from siblings like run_checks or git_commit, which are narrower.

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?

Implies general command execution, but doesn't say when to prefer a dedicated sibling (e.g., use git_commit instead of running raw git commands) or when-not to use it. Usage is implied by purpose rather than guided.

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