List Exploratory Sessions

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

The readOnlyHint annotation already establishes this is a safe read, and the description adds genuine behavioral value by disclosing pagination defaults ('Default page size 25 (max 200)'). It stops short of describing return shape, ordering behavior, or whether results are truncated, so it adds context but not a rich behavioral picture.

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?

Two tight sentences: the resource scope is front-loaded, followed by the filter inventory and the pagination constraint. No filler, no restatement of the name or title.

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 13-parameter, no-output-schema tool, the description covers the primary filtering use case adequately but is not complete: it never mentions the page parameter, sorting controls, or anything about what the response contains. An agent can call it, but the pagination and ordering story is only half told.

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?

At 54% schema coverage, the description carries real weight by mapping filters to names (status, state, sessionType, assignee, release/releaseId, tags, search) and the page-size limit. But it omits meaningful parameters — page, sortBy, sortOrder, and isClosed — leaving those unglossed in both the description and parts of the schema.

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 ('Browse exploratory sessions for a project') and pins the collection scope. It clearly implies a multi-session listing, distinguishing it in spirit from the singular get_session, but never names the sibling or explicitly contrasts the two.

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?

Enumerating the filterable dimensions implies 'use this to find/filter sessions,' which is reasonable context. However there is no when-to-use versus alternative statement and no prerequisites, so the agent must infer the conditions from the filter list alone.

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