resume_persistence

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

The description goes well beyond the annotations by disclosing the non-obvious shared-bucket side effect: without a session_key, resuming can 're-enable writes for every other keyless session too.' It also explains what `was_active` means and that only the selected bucket is cleared. This is exactly the kind of behavioral nuance annotations do not capture, and there is no contradiction with the readOnlyHint/idempotentHint/destructiveHint flags.

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 compact and front-loaded: the first sentence states the action and return value, and the second sentence details the critical scope side effect. No sentence is wasted, and the bolded scope warning earns its place because incorrect usage could affect other sessions.

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 one-parameter tool with no output schema, the description covers the essential agent decision points: what operation occurs, which bucket is affected, what happens when session_key is omitted, and what return value to expect. The behavior is fully specified enough for correct invocation, especially with the schema's additional session_key clarification.

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 input schema already documents session_key well, including that it is a partition hint rather than authentication. The description adds value by explaining the real-world consequence of each choice: with a session_key, only your own pause is cleared; without one, the shared keyless bucket is affected. This goes beyond the schema's neutral wording and helps the agent choose correctly.

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 states a specific action: 'Re-enable persistence immediately, clearing this caller's active no-persist TTL.' It clearly identifies the resource (the caller's no-persist pause bucket) and distinguishes this tool from siblings like pause_persistence and persistence_status by its reversal semantics. It also names the return value, giving the agent a concrete outcome.

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 makes the usage context clear: this tool undoes a pause and works on either the session-specific bucket or the shared keyless bucket depending on session_key. It explains the behavioral difference between providing and omitting session_key, but it does not explicitly state 'use this instead of X' or list conditions when not to use it. This is clear context without formal exclusions.

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