rbd_snapshot_create

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered. The description adds meaningful context beyond that: a medium risk rating and, importantly, that the operation is reversible via snapshot deletion, which tells the agent the rollback path. Return behavior is still undisclosed.

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?

Front-loads the operation and risk tag in one sentence, then a compact Args block where each line earns its place. No filler, though the risk/reversibility note could be merged into a slightly tighter form.

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?

There is no output schema, so the description should ideally hint at what is returned, and it does not. Otherwise it is complete for a mutation tool: all params documented, undo path stated, and safety profile covered by annotations, leaving only return-value detail 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?

Schema description coverage is 0%, so the description carries the full param burden and largely does so: it explains pool_name, image_name (with a discovery hint to rbd_ls), snap_name, and that target should be omitted for the default. That maps to all 4 params including the optional nullable one, though format/syntax details are thin.

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?

States a specific verb and resource ("Snapshot an RBD image") with a write/risk tag, and the name itself distinguishes it from rbd_image_create and rbd_snapshot_delete. It does not explicitly name or contrast those siblings, so a 4 rather than a 5.

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?

Usage is implied through the arg notes: image_name is sourced "from rbd_ls" and the reversibility line points to rbd_snapshot_delete as the undo path. However, there is no explicit statement of when to snapshot versus alternatives or any precondition (e.g., image must be quiesced/exported), so guidance is only partial.

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