canvas_list_assignments

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

No annotations are provided, so the description carries the full burden. 'List' plus the enumerated read-only filters make the read-only nature clear and the default course fallback is disclosed, but there is no mention of permissions, pagination, or result limits for what may be a large collection.

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 each argument line earns its place given the empty schema. The multi-line bucket enumeration is slightly bulky but justified because those values exist nowhere else.

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 read-only, zero-required-parameter tool with an output schema already describing return values, the description covers the essentials: scope, defaults, and filter semantics. Only the absence of pagination/volume expectations keeps it from being fully complete.

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% and the schema gives bucket as an untyped string with no enum, so the description does all the work: it names the default for course_id, enumerates all seven legal bucket values, and defines search_term as a title substring filter. This fully compensates for the schema gap.

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?

The description opens with a specific verb+resource ('List assignments in a course') and adds the salient payload ('due dates and needs-grading counts'), so the agent knows exactly what comes back. It does not explicitly contrast itself with siblings like canvas_get_assignment (singular fetch) or canvas_list_submissions, so it falls short of a 5.

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 implied rather than stated: the agent can infer this is the collection-level lister and that course_id falls back to CANVAS_DEFAULT_COURSE_ID. No explicit when-to-use/when-not guidance or named alternative is given, so it stays at the minimum-viable level.

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