hcloud_server_snapshot

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuine value with 'Hand-tuned wrapper that polls the resulting action', telling the agent the call blocks until the action completes when wait=true. It does not cover permissions needed, retention implications of snapshots vs backups, or what is returned.

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 compact sentences, front-loading the core action and following with the default and polling note. No filler, though the polling sentence could be tied explicitly to the 'wait' parameter.

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 mutating tool with no output schema and five undocumented parameters, the description is only minimally sufficient. It hints at polling behavior but does not explain the returned image/action, the meaning of 'id', or the labels/description parameters, so an agent cannot call it fully informed.

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% across 5 parameters. The description only clarifies the 'type' parameter default; it says nothing about 'id' (server identifier), 'wait' (blocking vs fire-and-forget), 'labels', or 'description', leaving four parameters undocumented anywhere.

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+resource ('Create an image (snapshot or backup) of a server'), which is clear and actionable. It does not, however, differentiate itself from close siblings such as hcloud_server_backup or hcloud_server_create_image_action, so the agent cannot tell from the text alone which to pick.

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 only usage hint is 'Default type is snapshot', which clarifies one parameter choice but gives no when-to-use/when-not guidance and no mention of the near-duplicate sibling tools. Usage context is implied rather than stated.

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