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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the requirement to use one idempotency key per intended opening, the explicitness of new-artifact issuance, and the statement that existing legacy balances/receipts retain their rights. Billing quotas (daily free visit, Practice unlimited) are also disclosed. Only the phrasing is obscure.

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 core action is front-loaded and the sentences are short. But the closing line 'Existing legacy balances and stored receipts retain their rights' is cryptic legal boilerplate whose operational meaning is unclear, and 'New artifact issuance is explicit' is likewise opaque, so not every sentence clearly earns its place.

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?

This is a stateful, billable mutation with no output schema and very low parameter coverage, so the description should resolve the ambiguities. Instead it omits what happens on a successful opening, which room values are valid, how duration_seconds is honored, and when spend_paid_credit is needed. An agent cannot reliably invoke it without guessing.

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 17% (just account_ref), so the description must carry the rest, and it largely does not. It obliquely touches request_key ('idempotency key'), new_artifact ('issuance is explicit') and spend_paid_credit ('without charge'), but never explains the required 'room' enum's eight values or duration_seconds' 60–900 bounds. Critical required-parameter meaning is left to the schema alone.

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 name (start_session) plus 'Open received room text' conveys opening a room session, but 'received room text' is opaque jargon that never plainly says a session/visit begins. It also fails to differentiate itself from close siblings like eclypse_complete_session, eclypse_session, eclypse_pause, or eclypse_preview. The intent is inferable but not stated cleanly.

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 supplies operational context ('One new full standard-room visit per account per UTC day is free; Practice includes unlimited visits'), which helps an agent anticipate cost. However, it never says when to prefer this tool over alternatives such as eclypse_preview or eclypse_guest_checkout, nor any precondition for starting a session. Usage is implied rather than directed.

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