moodle_download_file

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

With no annotations, the description carries the full burden. It does disclose the key behavior that a file is written to local disk and gives the default destination (~/Downloads/moodle-um/), which is valuable. It omits overwrite behavior when the file exists, any auth/session requirement, and what the tool returns (e.g., the saved path).

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?

One front-loaded sentence states the action and destination medium, followed by a compact per-parameter block. No redundant restatement of the tool name or filler content.

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 two-parameter side-effecting tool with no annotations and no output schema, the definition covers the essentials (what it does, where files go, what url means). Gaps remain around return value, overwrite semantics, and authentication state, which an agent would need before calling it reliably.

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 compensate, and it does for both parameters: url is explained by provenance (from a course or assignment page) and dest is explained as optional with a concrete default. It does not clarify whether dest must be a file path vs a directory or whether parent directories are created.

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: 'Download a course file (pluginfile.php / resource) to the local disk.' The mention of pluginfile.php/resource is concrete, and no sibling tool performs downloads, so it is naturally distinguishable. It stops short of explicitly naming how it differs from the surrounding get/list tools.

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 url parameter note ('file URL from a course or assignment page') implies the tool should be used after locating a file on a course or assignment page, which is useful context. However, there is no explicit when-to-use/when-not guidance and no stated prerequisites such as being logged in via moodle_login.

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