stop_server

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

With no annotations, the description carries the full burden of behavioral disclosure, and it delivers: it states there is no approval prompt, the terminal window and SSH tunnel close, stale tunnel sockets are removed, the tool polls for socket disappearance, and it returns a non-error 'not running' message when no socket exists. This is exceptionally transparent about side effects and return behavior.

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?

Every sentence earns its place: the first states the core action and outcome, the second covers parameter semantics and return behavior, and the third handles a compatibility edge case. It is dense but not padded, with the main purpose front-loaded.

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 one optional parameter, no annotations, and no output schema, the description is complete. It covers target selection, side effects, success and failure return behavior, the no-socket case, and the old-version fallback. An agent has everything needed to invoke it correctly.

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% for the single `host` parameter, so the baseline is 3. The description adds value beyond the schema by specifying that `host` selects a daemon started via start_server, and it explains the remote-vs-local selection semantics more richly than the schema's 'omit for the local daemon'.

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 opens with a specific verb and resource ('Stop a running sudo-proxy daemon') and goes on to explain exactly what happens: a stop request is sent, the daemon exits, and its terminal/tunnel closes. This clearly differentiates stop_server from siblings like start_server and status.

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?

It gives concrete selection guidance: `host` selects a remote daemon started via start_server, and omitting it targets the local daemon. It also explains the fallback for old versions that predate remote stop. However, it does not explicitly contrast with alternatives like status or execute, though the context makes the intended use clear.

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