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

The description discloses key behavioral traits: it runs in a persistent container ('files there persist between calls'), supports real shell features, and returns non-zero exit codes as part of the response. This goes beyond the basic 'Run shell' annotation. It does not explicitly warn about destructive commands, but the persistent container and real shell nature are sufficiently transparent.

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?

The description is concise and well-structured: it starts with the core purpose, then details capabilities, then gives use cases, and finishes with an important behavioral note. Every sentence adds value—no fluff or redundancy. The front-loading of the main function makes it easy to scan.

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 there is no output schema, the description adequately explains what the caller receives: the command's output and a non-zero exit code. It also covers the persistent working directory and shell behavior, which are essential for correct usage. It does not describe timeout enforcement details, but that is covered by the parameter description and is not critical for basic use.

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 schema covers all three parameters (command, dir, timeout) with descriptions, achieving 100% coverage. The tool description adds valuable context: the working directory defaults to /work and files persist, which clarifies the 'dir' parameter. It also notes that non-zero exit codes are in the response, supplementing the schema. This exceeds the baseline for fully described schemas.

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 clearly states the tool's function: 'Run a shell command in your account's container sandbox and get back what it wrote.' It explicitly mentions capabilities like pipes, redirection, and persistence, distinguishing it from tools like shell_write that handle file writing. The purpose is unambiguous and specific.

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?

The description gives direct guidance on when to use it: 'Use it to build, test, run scripts and move files about.' It also explains that non-zero exit codes come back in the response, so it is clearly appropriate for failing builds. However, it does not explicitly mention when not to use it or alternatives, leaving a small gap in exclusion guidance.

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