open_session

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that 'every call goes through the client's permission approval gate', which is a non-obvious side effect. However, it is silent on session lifetime/timeouts, resource cleanup, and the need to pair with close_session, leaving meaningful gaps for a long-lived connection tool.

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 opening sentence front-loads the core purpose, and the remaining prose is organized by concern (target description, routing, serial, permission gate). It is dense but for an 11-parameter tool most sentences earn their place; the route/jump-host explanation is the only slightly expansive part.

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?

An output schema exists, so return values need not be explained. Given the tool's complexity (11 params, discriminated route union, credential backends, opt-in flags), the description covers protocols, routing, serial, and the approval gate but omits the remaining safety flags and the session lifecycle. Adequate but noticeably incomplete for a tool this rich.

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?

Top-level schema description coverage is 0%, so the description must compensate and does so for roughly half the parameters: host/port/protocol, credentials-as-references, the single-hop 'socks'/'proxyjump' route, and serial needing an absolute /dev/tty* path plus allow_serial=true. It says nothing about allow_telnet, host_key_policy, allow_plaintext_password, legacy, or the relationship between protocol and the route discriminator.

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 states a specific verb and resource ('Open a raw interactive terminal session and keep it open') and distinguishes itself from siblings by pointing to terminal_write for follow-up hops inside the same session. It is clear what the tool produces, though it never quite names the alternative tools for session reuse or states that the returned handle feeds terminal_read/terminal_write.

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 real when-to-use guidance: use 'proxyjump to reach a bastion quickly and run further ssh or telnet hops yourself with terminal_write inside the same session', and use 'protocol="serial" with an absolute /dev/tty* path' for local console cables. It stops short of explicit exclusions (e.g. when to reuse an existing session vs open a new one), but the context provided is above average.

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