terminal_execute

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that 'Each call is independent — no state (shell variables, working directory) persists between calls (however filesystem does persist),' and that commands time out after 120 seconds by default. This gives agents a clear model of the execution environment. It does not describe error handling or exit code behavior, but the core behavioral traits are well covered.

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 compact yet thorough. The first sentence states the purpose, followed by essential behavioral notes, then parameter-specific guidance. Each sentence serves a purpose—there is no filler or repetition. Paragraph breaks separate high-level behavior from parameter usage, making 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?

For a terminal tool with 5 parameters and no output schema, the description covers the key operational aspects: persistent filesystem, stateless calls, working directory control, stdin usage, and timeout override. It does not explicitly mention how output is returned (e.g., stdout/stderr captured in response), but this is often assumed for such tools. Given the complexity and the absence of annotations, the description provides sufficient context for correct invocation.

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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema: it explains the rationale for `working_directory` (because state does not persist), demonstrates stdin usage with a concrete example, and clarifies the default timeout (120s) vs. the hidden server config default. It also reinforces the mutual exclusivity of `command` and `args` implicitly. These insights help agents select and use parameters correctly.

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 core function: 'Execute a shell command in one persistent Debian Docker computer.' It identifies the specific verb (execute), resource (shell command), and environment (Debian Docker), and immediately notes 'Commands run in bash.' This is unambiguous and distinct from the sibling tools, which handle UI, file operations, status, and network—none of which overlap with general shell execution.

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 provides concrete usage guidance: it explains how to control execution context with 'working_directory parameter or chain commands with &&,' and recommends using stdin for writing files without escaping. It also mentions overriding the timeout for long-running operations. However, it does not explicitly state when to use this tool over specific siblings (e.g., 'use read_file/write_file for direct file access instead of shell commands'), though the context makes this implicit.

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