study_download_files

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

Annotations declare this is a mutation (readOnlyHint=false) with a safe, non-destructive, open-world profile. The description adds real value beyond that: it is asynchronous (returns a job_id), requires polling to completion, and operates through a plugin-owned session. The refresh statement ('checks by a new transfer') is vaguely worded.

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?

Three dense, front-loaded sentences. The list of excluded manual actions is slightly verbose but reinforces the automation contract; the job_id/poll and refresh notes are correctly placed at the end.

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?

No output schema exists, so the description must explain returns; it does by naming the job_id and the polling tool. Safety is covered by annotations. Remaining gaps (error behavior, meaning of 'observed') are minor for a 2-parameter async 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 coverage is 0%, so the description carries the burden. It constrains item_ids to 1..30 observed resources, which is useful, but the refresh semantics are stated opaquely as 'checks by a new transfer', leaving the default-true behavior only partially explained.

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?

Names a specific verb (download) and resource (Learn resources) with batch scope (1..30). It is clear what the tool does, though it does not explicitly differentiate itself from the closely related siblings study_download_resource and study_downloads.

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?

States the automation context (plugin-owned session, no manual URL/browser/screenshot) and gives a concrete follow-up workflow: poll study_school_job for verified paths and checksums. It stops short of stating when to prefer this over the sibling download tools.

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