persistence_status

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

Annotations already declare `readOnlyHint: true`, lowering the burden. The description still adds valuable behavioral nuance: the status is scoped to a bucket selected by `session_key`, not the whole server, and in streamable-HTTP deployments a keyless caller may see `paused: true` caused by another session. This meaningfully goes beyond the annotation.

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?

Although the description is longer than typical, every sentence earns its place: the main question is front-loaded, and the subsequent sentences clarify non-obvious scope semantics. No filler or redundant restatement of the tool name or schema exists.

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 present, the description supplies the needed outcome expectations: paused state, TTL remaining in seconds, and scope. It also covers the one optional parameter and the tricky multi-session semantics. Nothing needed to call and interpret this tool correctly is missing.

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?

The schema already documents `session_key` as an opaque partition hint with 100% coverage, so baseline is 3. The description adds extra meaning by connecting the parameter to response scope, explaining that omitting it shares a bucket with other keyless callers, and clarifying that it is not authentication or a data filter.

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 opens with a specific verb and resource: 'Report whether persistence is currently paused and the TTL remaining (in seconds).' It clearly distinguishes itself from broader server-wide status by emphasizing the returned `scope` is tied to a session key, so it is not ambiguous against sibling status or mutating tools.

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?

The description gives clear usage context: it explains what happens when `session_key` is provided vs omitted, and warns that `paused: false` does not mean no other session is paused. It stops short of explicitly naming alternative tools or saying 'use this when X, not when Y,' but the inclusion criteria are strongly implied.

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