list_sessionsRetrieve recent conversation sessions for a specified agent. Use the optional limit to constrain the number of results.
An agent's recent conversation sessions.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Agent name from list_agents, e.g. 'codex' or 'claude'. | |
| limit | No |
Changes observed during successful MCP inspections.
v1.2.2Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description only adds that results are 'recent', hinting at an implicit recency window, but it does not state ordering, default count, or pagination 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?
A single short sentence-fragment with no padding; nothing is wasted. It is terse rather than bloated, though its fragment form leaves the action implicit.
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 annotations covering return content, the description should describe what a session record contains, its ordering, and how limit behaves. It provides none of these, leaving an agent unable to predict the result set.
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 50%: 'agent' is documented while 'limit' has no description at all. The description's 'recent' vaguely gestures at bounded results but supplies no default, maximum, or ordering to compensate for the undocumented limit parameter.
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 names the resource ('conversation sessions') and scopes it to an agent, but it is a noun fragment with no verb and adds no differentiation from the sibling search_sessions or get_transcript. An agent can infer the action from the tool name, but the description itself doesn't establish a distinct purpose.
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?
No when-to-use, when-not-to-use, or alternative routing is provided. The existence of search_sessions as a sibling is never addressed, so the agent gets no help deciding between browsing and searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.