Runs a terminal command and captures its output for quick tasks that do not require a visible terminal tab.
Executes a terminal command and captures its output. Preferred for quick commands (ls, git status, cat, echo, etc.) that don't need a visible terminal tab. Use open_terminal_tab only for long-running processes.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The command to execute | |
| working_directory | No | Optional working directory for command execution |
Changes observed during successful MCP inspections.
v8.0.4Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It usefully discloses that output is captured rather than shown in a tab, but omits whether the call blocks until completion, timeouts, output size/truncation limits, and any risk/permission profile for arbitrary shell execution.
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 with no filler; the core behavior leads and the alternative/scope guidance follows immediately. Every clause earns its place.
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 an unannotated tool that runs arbitrary shell commands with no output schema, the description should cover execution semantics (blocking vs async, timeouts, truncation) and the risk profile. It covers intent and one alternative but leaves these behavioral gaps open.
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% and both parameters are self-describing, so the baseline is 3. The description adds no detail on command syntax, shell used, or how working_directory defaults, so it adds nothing beyond the schema.
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+resource ('Executes a terminal command and captures its output') and gives concrete example commands, which is clear. However, the many sibling variants (execute_with_streaming, execute_with_auto_retrieve, execute_pipeline, preview_command) are never differentiated, so an agent still cannot fully disambiguate the execute_* family from this text alone.
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?
Explicitly says this is 'preferred for quick commands' and directs long-running processes to open_terminal_tab, giving a real when-to-use/when-not pair. The gap is that it says nothing about when to prefer execute_with_streaming, execute_with_auto_retrieve, or preview_command, which are closer alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.