Download ISO/template from URL

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

Annotations already indicate it is a write operation (readOnlyHint=false) and not idempotent (idempotentHint=false). The description adds that it triggers a server-side fetch and mentions Proxmox fetches directly, but does not disclose potential side effects like storage space impact, network usage, or failure handling. With annotations providing basic safety profile, the description adds moderate value.

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 sentences: first front-loads the action and target, second adds mechanism and benefit. No wasted words. Efficient and clear.

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 simple download tool with no output schema and well-covered parameters, the description is largely complete. It conveys the core function and use case. However, it omits mention of prerequisites (e.g., storage pool must exist) or return behavior (e.g., task status), which could be added for full completeness.

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?

Input schema covers 86% of parameters with descriptions (e.g., url, node, storage, filename, checksum). The description does not add any parameter-specific meaning beyond the schema. Baseline 3 is appropriate as schema does the heavy lifting.

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 'Trigger a server-side download from a URL into a storage pool' with a specific verb ('download'), resource ('URL'), and target ('storage pool'). It differentiates from client-side uploads by noting it's server-side, and highlights being useful for large ISOs, distinguishing it from sibling tools that are primarily local operations.

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 provides guidance by stating it is 'useful for large ISOs', implying it is optimized for large files where client-side download-upload would be inefficient. However, it does not explicitly state when not to use it or provide alternatives, leaving some ambiguity. No other sibling tool directly competes, so the guidance is adequate but not explicit.

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