list_sessions

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

The description adds significant behavioral context beyond annotations: read-only and no side effects are stated, pagination mechanics are detailed, return shape is given, error handling for malformed cursors or since values is explained, and sandbox key behavior is noted. Annotations already indicate read-only and idempotent, so this adds more value.

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 extremely concise, using three sentences to convey purpose, usage, return data, and errors. Every sentence adds value, and the most critical information (purpose and when to use) is 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 that annotations cover safety (read-only, idempotent) and the input schema is fully described, the description adds all necessary behavioral and usage context. Return type is described, error conditions are noted, and the relationship to sibling tool is clarified. The tool is fully specified.

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%, with descriptions for limit, cursor, and since. The description adds value by explaining how to use the cursor (pass next_cursor back as 'cursor') and that since expects ISO 8601 format. This goes beyond the schema's basic descriptions.

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 clearly states the tool lists sessions in the workspace, sorted newest first, with cursor pagination. It distinguishes itself from the sibling tool 'resume' by specifying that this tool is for discovering sessions when no session_id is known, while resume is for directly accessing a known session.

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?

Explicitly states when to use this tool (when you do not have a session_id) and when to use the alternative (resume if you have one). Also provides clear instructions on pagination: pass next_cursor back as 'cursor' and that null means no more pages.

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