pbs_protect_snapshot

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

The description discloses that this is a write operation requiring PBS_ALLOW_WRITE=true and confirm=true, and explains the consequences on prune/forget. This complements the annotations (readOnly=false, destructive=false, idempotent=true) without contradiction.

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?

Three concise sentences front-load the purpose and provide the needed behavioral context without unnecessary detail.

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?

The description covers the tool's purpose, behavioral impact, and prerequisites, which is sufficient for a simple flag-setting operation. The output schema exists, so return values need not be described.

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 provides detailed descriptions for each parameter, so the description adds little new parameter-specific meaning beyond reiterating the confirm requirement. Baseline 3 is appropriate as the schema covers the semantics.

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 clearly states 'Set or clear the protected flag on one snapshot' with a specific action and resource, distinguishing it from siblings like pbs_forget_snapshot and pbs_prune.

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 explains the operational context: protected snapshots are skipped by prune and cannot be forgotten until unprotected, making it clear when to apply protection. It doesn't explicitly name alternatives but gives clear behavioral criteria.

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