Skip to main content
Glama

kill_shell

DestructiveIdempotent

Terminates a background shell and its entire process group using the returned shell_id, stopping lingering processes from continuing to run.

Instructions

Stop a background shell (kills its whole process group).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "shell_id": "<shell_id>"
    },
    "name": "kill_shell"
  }
}

Input Schema

NameRequiredDescriptionDefault
fleetNoFleet name. Omit to use the default.
contextNoContext name. Omit to use the default.
shell_idYesThe shell_id bash returned for a background shell.
workspaceNoWorkspace id. Omit to use this session's workspace on the fleet.

Output Schema

NameRequiredDescriptionDefault
noteNo
endedNo
stateYes
whereYes
outputNo
runningNo
startedNo
shell_idYes
warningsNo
exit_codeNo
workspaceYes
descriptionNo
stderr_bytesNo
stdout_bytesNo
omitted_bytesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is largely covered. The description still earns credit for specifying that the entire process group dies, not just the parent shell — a real consequence beyond the annotations — but it omits error behavior for unknown shell_ids and any permission or cross-fleet considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with the destructive scope front-loaded in the parenthetical; nothing is padded or repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-required-parameter kill tool with an output schema covering returns and annotations covering destructiveness, the definition supplies what an agent needs. Only the edge cases around missing or already-dead shells are left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters, including the defaulting behavior for fleet, context, and workspace, are already documented in structured fields. The description adds only the origin of shell_id, which the schema states as well, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Stop a background shell" gives a specific verb and resource, and the parenthetical narrows scope to the process group. It is unmistakably distinct from read-oriented siblings like bash_output or read_output, though it does not name a sibling to contrast with explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: only background shells qualify, and the required shell_id must come from bash's background launch. It never says when not to use it, nor what happens if the shell already exited or if the wrong fleet/context is targeted.

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