list_course_files

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

With no annotations, the description carries the burden and does well: it enumerates every source scanned (modules, assignments with attachments and description links, Files tab, Pages, announcements) and discloses dedupe-by-file-id, which tells the agent the result set is normalized rather than raw. It implies a read-only no-side-effect operation via 'without downloading', but never explicitly states that nothing is written to disk or that auth/account context is required.

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?

The summary sentence is front-loaded and does the heavy lifting before any parameter detail, and the Args block is scannable. Slight verbosity in the nested compare_dir explanation, but every clause conveys usable information rather than filler.

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?

An output schema exists so return values needn't be explained, yet the description still discloses the local.status vocabulary the agent will encounter. For a four-parameter read tool with no annotations, the description covers sources, dedupe, filtering formats, and the compare mode — nothing material is missing.

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 and it does: course accepts an id, code like '20.201', or name fragment; since accepts YYYY-MM-DD or relative '7d'; compare_dir explains the matching strategy (name+size then content hash, any layout) and the have/changed/missing statuses it produces; account defaults to the active account. All four parameters gain meaning not present in the bare schema.

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 ('List every file... for a course') and immediately scopes it against the sibling tool: it lists exactly what download_course_files would fetch, 'without downloading'. An agent can distinguish this preview tool from its download counterpart without opening either schema.

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?

Usage is strongly implied by the contrast with download_course_files — this is the inspect-before-you-download path — and the compare_dir parameter hints at a sync-check workflow. However, it never states an explicit 'use this when...' rule or any when-not guidance, leaving the agent to infer the workflow position.

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