terminal_list

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

With no annotations provided, the description carries the full behavioral burden. It discloses important edge-case behavior: stale sessions remain visible and closeable, terminal_send()/terminal_read() will refuse them, and validation sessions are always excluded. This is substantial behavior disclosure, though it does not mention output format or error 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?

The description is front-loaded with the core action and then expands on meaningful edge cases. It is somewhat dense and long-winded, but each clause adds essential selection and invocation context, so the length is justified.

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?

For a zero-parameter listing tool with no output schema, the description is nearly complete: it defines what is included, what is excluded, and how results relate to sibling operations. It could be more complete by stating the return shape, but the core semantics are fully covered.

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 and an empty input schema, so there is no parameter semantics to clarify. The description correctly focuses on behavior rather than parameters, and the baseline of 4 applies because no argument documentation is needed.

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: 'List every currently managed production terminal session.' It clearly differentiates itself from get_active_topology by noting it includes sessions regardless of active topology, and from terminal_send/read/close by specifying stale sessions are closeable but not usable for I/O.

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 gives strong contextual cues: use it to see stale sessions and close them via terminal_close(), and it confirms local validation sessions are excluded. However, it never explicitly states when to choose this over get_active_topology or when not to use it, so the guidance remains implied rather than direct.

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