List Downloads

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior: it reads a local cache and never returns file bodies, with the handoff workflow needed to actually read a file. It does not discuss pagination or cache staleness, which would be the next useful detail.

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?

Front-loads the local-cache scope, then the critical 'no file bodies' constraint, then the alternatives. Every sentence carries distinct information with no redundancy.

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 shapes need not be described; the description instead covers the non-obvious gaps (local cache source, absence of file content, handoff path, sibling routing). Nothing needed to invoke it correctly 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 100% and the single course_id parameter is fully documented in the schema. The description adds no format or filtering semantics for course_id (and its 'lists all records' phrasing slightly understates that filtering is possible), so the baseline 3 applies.

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 ('lists all download records stored in the local MCP cache') with an explicit scope qualifier ('[local]'). It also names the sibling tools it must not be confused with, so an agent can distinguish it from eclass_search_downloads and eclass_get_download_status without opening schemas.

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?

Explicitly routes the agent: conditional filtering goes to eclass_search_downloads, per-course summaries go to eclass_get_download_status, and reading a file requires eclass_file_handoff with a file_id. Both the when-to-use and the alternatives are stated outright.

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