opencode_shutdown

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It explains the primary effect (closing all active sessions), the manner ('gracefully'), and a key non-effect: Gemini and Qwen are unaffected because they are stateless subprocesses. This adds meaningful context beyond the tool name, though it could mention consequences like unsaved work loss or idempotency.

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 appropriately concise: two sentences (or three clauses) front-load the core purpose and usage condition. Every sentence contributes: the first defines the action, the second specifies when to use it, and the third clarifies the scope of impact. No filler or redundancy.

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?

Given the tool's simplicity (no parameters, straightforward shutdown action), the description covers all essential aspects: what it does, when to call it, and its non-effect on other tools. The presence of an output schema means return values don't need to be described. The description is complete for an AI agent to correctly select and invoke this tool.

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?

The tool has zero parameters, so the baseline for this dimension is 4. The description adds no parameter-specific details, but none are needed. The schema is empty, and the description sufficiently describes when to invoke the tool without requiring parameter explanation.

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 action: 'Gracefully stop the opencode server and close all active sessions.' It uses specific verbs (stop, close) and names the resource (opencode server, active sessions), and the phrase 'all active sessions' distinguishes it from the sibling tool opencode_end_session, which likely ends only a single session.

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 tool provides an explicit usage condition: 'Call this when you are done with all opencode work in the current session.' It also clarifies that Gemini and Qwen are not affected, helping the agent understand when this tool is not relevant. However, it does not explicitly name alternative tools for ending individual sessions, so it stops short of a 5.

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