Snapshot a project

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

Annotations already declare it is a write operation that is not destructive, and the description reinforces this with the safety framing 'verified backup copy' and the pre-risky-work timing. Beyond that it says nothing about where snapshots are stored, whether repeated labels overwrite or accumulate, or what the call returns. The dual-mode behavior (list vs. create) under a single non-readOnly annotation is worth flagging but does not directly contradict it.

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 short sentences, zero filler, with the core action and its purpose front-loaded and the mode-switching rule appended. Every clause 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?

With no output schema and no schema descriptions, the description covers the why and the label semantics but leaves the return value, snapshot storage/scoping behavior, and the 'project' parameter format unexplained. Adequate to call the tool, but not complete for a two-mode tool.

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 0%, so the description must carry parameter meaning, and it does define the important one: 'label' is optional and its absence switches the tool into list mode. The required 'project' parameter is never explained (name, path, or handle is left ambiguous), so the compensation is partial.

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 gives a specific verb and resource ('Saves a labelled, verified backup copy') and even discloses a second mode ('Without label: lists snapshots'), which an agent can act on without opening the schema. It falls short of 5 because that listing mode overlaps with the sibling spine_list_backups, and the description never acknowledges the overlap or says which one to prefer.

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 states a clear trigger ('before risky editor work') and names a follow-up tool (spine_reimport_diff), so the agent knows the workflow context. It stops short of explicit when-not guidance, and it doesn't distinguish itself from spine_list_backups or spine_restore_backup, which are the closest alternatives.

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