moodle_sync

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

With no annotations, the description carries the full burden and mostly delivers: it discloses destination-path resolution (SlideMate library vs ~/MoodleFiles), background execution, the literal {"running": true} return for the bulk mode, and the same-size skip rule. It omits auth/precondition requirements and any indication of whether a skipped file is reported, so it falls short of fully transparent.

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?

Both modes are front-loaded in the first sentence and the async contract is stated compactly with the literal return value. The text is dense but nearly every clause carries operational information; only the destination-path parenthetical is a slight detour.

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?

With no output schema, the description correctly assumes responsibility for return shapes and does so for the bulk mode ("running": true plus polling instruction). It also explains the destination layout and skip rule. It stops short of describing what the with-course synchronous result contains, which leaves a gap for a tool with zero structured return documentation.

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 must compensate. It does well for `course` by spelling out accepted forms (id, short name, or partial name), which the schema's bare string type does not convey. However, `skip_existing` is only implied via "Existing files of the same size are skipped" and the behavior when set to false is never stated.

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 course files") and clearly splits the two operating modes by presence of `course`. It distinguishes itself from moodle_sync_status by pointing at it as the polling companion, but says nothing to separate it from the sibling moodle_download, which an agent could easily confuse it with.

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?

Gives concrete when-to-use guidance for both branches: pass a course to download one course synchronously, omit it to bulk-download PDFs from all current courses in the background, and call moodle_sync_status to get the eventual result. It names the alternative tool for the async path, but offers no exclusion guidance versus moodle_download or moodle_browse.

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