run_terminal_command

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

With no annotations, the description carries the full burden. It discloses that the tool is disabled by default and requires an environment variable to enable, which is a meaningful behavioral trait. However, it does not mention safety implications, the fact that arbitrary commands can modify system state, or any execution environment details. The 'power-user' label hints at risk but stops short of explicit disclosure.

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 a single sentence that is front-loaded with the core purpose. It is concise, with no filler or redundant wording. Every element contributes to understanding the tool's function and an important prerequisite.

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?

The tool executes arbitrary terminal commands, a complex and potentially destructive operation, but the description does not mention expected outputs (stdout/stderr, exit codes), error handling, or side effects. No output schema exists to fill this gap. The description only covers the enablement prerequisite, leaving significant behavioral and usage context unspecified.

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 0%, and the description adds no parameter information. The parameter names (command, cwd, timeoutMs) are somewhat self-explanatory but not fully defined (e.g., cwd is not described as current working directory). The description does not compensate for the lack of schema descriptions, leaving the agent to infer meaning from names and types alone.

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 action ('Execute a terminal command') and clearly identifies the resource (terminal command). It is distinct from sibling tools like capture_screen or run_macro, which serve different purposes. The 'power-user automation' qualifier adds context without obscuring the core function.

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 implies usage for advanced automation tasks and notes that the tool is disabled by default, providing a prerequisite. However, it does not explicitly state when to use this tool over alternatives or provide exclusions. There are no direct alternatives among siblings, so the context is adequate but not fully explicit.

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