Quizzes and exams

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral detail — default page size of 20, a 100 cap implied by the schema, and that results include the caller's own attempts and score. It says nothing about authentication, rate limits, or what happens for unpublished quizzes, so it is a moderate rather than rich addition.

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 what the tool returns, then groups scoping, filtering, and pagination guidance, and closes with a natural-language example query. Dense but every clause carries information; the closing example is slightly decorative but reinforces the trigger phrasing.

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 and four optional parameters, the description covers returned fields, scope defaults, filtering semantics, and pagination well enough to call the tool correctly. Minor gaps remain around what counts as an 'active course' and behavior when a course name is ambiguous.

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%, so baseline is 3, but the description genuinely adds meaning: course_id accepts either a numeric Canvas course ID or a course name, and when=upcoming means 'not yet closed' rather than merely 'in the future'. It also restates the 20-item default in a usable way.

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 resource (Canvas quizzes and exams) and enumerates exactly what each result carries: open time, due time, close time, time limit, attempts used, and score. That is enough to distinguish it from siblings like get_assignments or get_discussions without opening a 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?

Gives clear operating contexts: pass course_id to scope to one course (by ID or name) or omit it for all active courses, and use when=upcoming vs past to select unclosed vs closed quizzes. It never names an alternative sibling tool for assignment or grade data, so routing guidance stops short of explicit alternatives.

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