List peer sessions

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

Beyond readOnlyHint and openWorldHint, the description explains key runtime behavior: status_unreadable is reported as busy as a safe default and must not be treated as an observed fact; self is never listed and must be addressed separately; and tincan_version fields reflect the serving process rather than the PATH binary.

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 return shape, then packs in only operationally necessary rules about display labels, self addressing, status_unreadable, and version reporting. Every sentence carries useful guidance, despite the dense single-paragraph structure.

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?

With no output schema and no parameters, the description carries the burden of explaining return values and does so thoroughly: peer name, state, working directory, durable IDs, display_label guidance, self addressing, and tincan_version semantics are all covered. An agent has enough context to invoke and interpret the tool 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?

This tool has zero parameters, so parameter semantics are not applicable; the baseline for a no-parameter tool is 4. The description instead adds useful meaning about the data returned by the call.

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 uses a specific verb and resource: it lists live Codex, Claude Code, and opencode sessions on this machine that are messageable. It clearly distinguishes this discovery tool from send_peer by describing the returned peer identity/state fields and by saying to call this before send_peer.

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 explicit usage guidance: call this before send_peer because names change and sessions come and go, use name rather than display_label when calling send_peer, and use self rather than a bare session id for the current session. It also tells the agent not to shell out to tincan --version for version reporting.

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