terminal_close

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

With no annotations, the description carries the behavioral burden. It explicitly states that closing sends SIGTERM to the process in the pane, which reveals the mechanism and that this is a real process termination. It does not mention the force/SIGKILL fallback or post-close state, but the core destructive effect is clearly disclosed.

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 short sentences with no filler; the primary purpose is front-loaded, and the second sentence adds the signal detail. Every word 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?

The tool is simple, has full schema coverage, and the core action and effect are described, so an agent can invoke it with the required name. However, there is no output schema, no error/return behavior, and no guidance on how this differs from terminal_send_signal, leaving some operational context missing.

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%, so the schema already documents both parameters ('Terminal name to close', 'Force kill with SIGKILL...'). The description only reinforces the name parameter via 'by name' and adds no new semantics for force or default behavior, so the baseline 3 applies.

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 uses a specific verb ('close'), names the resource ('terminal session'), and adds the 'by name' scoping plus the concrete effect (SIGTERM to the pane's process). This clearly separates it from siblings like terminal_spawn or terminal_send_signal.

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 the tool is for ending a named terminal session, but it never explicitly states when to prefer it over terminal_send_signal or how it differs from other terminal lifecycle tools. No selection criteria or alternatives are given, leaving usage to inference.

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