session_list

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

With no annotations, the description carries the full burden, and it does disclose one genuinely surprising trait: the call reconciles state and starts queued runs, i.e. a list operation with a mutation side effect. However, it is ambiguous whether this happens unconditionally or only under some flag, and nothing is said about permissions, whether queued runs can fail or block, or whether the call is safe to repeat.

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?

Three short sentences, front-loaded with the core action and ordering, then the parameter note, then the side effect. Nothing is padded, though the side-effect sentence reads as a tacked-on afterthought rather than being flagged as important.

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, and the core action is covered. But for an eight-parameter tool with zero annotations and a hidden state-mutating side effect, the description leaves too much unstated: most filters are undefined and the conditions for reconciliation/queue-starting are unclear.

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 description coverage is only 13% (just 'since'), so the description must compensate and does so for only one of eight parameters: include_external. bot, view, limit, status, cwd_prefix, and needs_attention are left entirely to bare titles, and the enum values for status/view are never explained.

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?

States a specific verb and resource ('List runs') plus ordering ('newest first') and that totals are included, which is more than the bare name conveys. It does not explicitly contrast with siblings like session_status or session_tail, but the listing scope is unmistakable.

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?

There is no statement of when to use this rather than session_status, session_tail, or session_result, which are the obvious alternatives for inspecting sessions. The only guidance offered is about a single parameter (include_external), not about tool selection.

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